Adding phone numbers to the campaign

The following Calls API method is used for adding phone numbers with parameters to the campaign:

POST https://ds.tovie.ai/api/calls/campaign/{token}/addPhones

Request body

The body of requests to this method contains an array of objects defining the phone numbers added to the campaign as well as the call policy for each number. Every object may have the following fields.

Field	Description	Example
phone	Customer phone number. Required field.	"16123456789"
payload	Arbitrary data to be passed into the script. Optional field.	{"promo": "20% off all Tovie DialogStudio business plans!"}
startDateTime	Call start date. The call will be made in the interval between startDateTime and finishDateTime. Optional field.	"2020-03-23T00:00:00Z"
finishDateTime	Call end date. After finishDateTime, no calls will be made. Optional field.	"2020-03-23T00:00:00Z"
allowedDays	Weekdays when calls are allowed. Optional field.	["mon", wed", "fri"]
allowedTime	Time intervals when calls are allowed for each day of the week. Optional field.	"default": [{"localTimeFrom": "10:00", "localTimeTo": "11:30"}]
retryIntervalInMinutes	The pause between callback attempts, in minutes. Optional field.	120
maxAttempts	The total number of callback attempts. Optional field.	1
gmtZone	Customer time zone. Optional field.	"+03:00"

Allowed call time

allowedDays

The allowedDays field configures the weekdays when calls may take place. The field value is an array with the following strings allowed: "mon", "tue", "wed", "thu", "fri", "sat", "sun".

caution

When allowedDays is specified, it is only during these days that calls are possible. Any allowedTime settings for other weekdays are ignored.

allowedTime

In the allowedTime field, every day of the week is mapped to one or several time intervals when calls to the phone number are allowed.

This field contains an object with keys equal to weekday names from the allowedDays field, as well as a default key. The values for each key should be arrays of objects with localTimeFrom and localTimeTo nested fields, corresponding to the allowed time interval thresholds.

tip

The time format is HH:mm. The time is relative, so the customer local time is taken into account.

Calls made during weekdays not specified in the request body will be made in accordance with the settings provided in the default value.

localTimeFrom and localTimeTo

There are some restrictions on the localTimeFrom and localTimeTo fields:

• Every interval should contain both the upper and the lower threshold. A request error occurs when one of them is missing.
• Time intervals should not overlap, i.e. the upper threshold of one should not be greater than the lower threshold of the other. Situations like this also produce request errors.

Customer time zone

The gmtZone value must conform to one of the following formats:

• Z for UTC time.
• +h, +hh, ±hhmm, or ±hhmmss with a number of optional elements:
  • a : separator between hours, minutes, and seconds, e.g. +hh:mm:ss;
  • either a UTC, a GMT, or a UT prefix, e.g. GMT-hh:mm.
• One of the time zone IDs as specified by IANA TZDB.

Redundant numbers in call campaigns

If the same number was added to an outbound call campaign with the same settings and payload two or more times, such duplicates will be ignored. The restriction applies for 24 hours from the moment the number is added.

tip

If you use the same phone number to test a call campaign, use the special GET https://ds.tovie.ai/api/crmCalls/campaign/{token}/test/addPhone method.

Example request

curl --request POST 'https://ds.tovie.ai/api/calls/campaign/8231.7056.1b131df1/addPhones' \
--header 'Content-Type: application/json' \
--data-raw '[
  {
    "phone": 16123456789,
    "payload": {
      "name": "Alex",
      "age": 34
    },
    "allowedTime": {
      "mon": [
        {
          "localTimeFrom": "10:00",
          "localTimeTo": "11:30"
        },
        {
          "localTimeFrom": "13:00",
          "localTimeTo": "14:30"
        }
      ],
      "default": [
        {
          "localTimeFrom": "10:00",
          "localTimeTo": "18:00"
        }
      ]
    },
    "retryIntervalInMinutes": 120,
    "maxAttempts": 1,
    "gmtZone": "+03:30"
  }
]'

The response to this request will be an array of all created call job IDs.