Adding phone numbers to the campaign
The following Calls API method is used for adding phone numbers with parameters to the campaign:
POST /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 | Required | Example |
---|---|---|---|
phone | Customer phone number. | Yes | "79123456789" |
payload | Arbitrary data to be passed into the script. | No | {"promo": "20% off all JAICP business plans!"} |
startDateTime | Call start date. The call will be made in the interval between startDateTime and finishDateTime . | No | "2020-03-23T00:00:00Z" |
finishDateTime | Call end date. After finishDateTime , no calls will be made. | No | "2020-03-23T00:00:00Z" |
allowedDays | Weekdays when calls are allowed. | No | ["mon", "wed", "fri"] |
allowedTime | Time intervals when calls are allowed for each day of the week. | No | "default": [{"localTimeFrom": "10:00", "localTimeTo": "18:00"}] |
retryIntervalInMinutes | The pause between callback attempts, in minutes. | No | 120 |
maxAttempts | The total number of callback attempts. | No | 1 |
gmtZone | Customer time zone. | No | "-05:00" |
dialerPriority | Phone number priority. | No | 2 |
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"
.
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.
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
Note the following 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.
- If
localTimeFrom
is greater thanlocalTimeTo
, the interval is considered correct: it starts on the specified day and ends on the next day.
[
{
"localTimeFrom": "10:00"
}
] // Error: no upper limit specified
[
{
"localTimeFrom": "10:00",
"localTimeTo": "13:30"
},
{
"localTimeFrom": "13:00",
"localTimeTo": "14:30"
}
] // Error: overlapping intervals
[
{
"localTimeFrom": "20:00",
"localTimeTo": "03:00"
}
] // Correct interval from 8 p.m. to 3 a.m.
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
, aGMT
, or aUT
prefix, e.g.GMT-hh:mm
.
- a
- One of the time zone IDs as specified by IANA TZDB.
Phone number priority
The dialerPriority
field sets the phone number priority in a range from 1 to 5, where 1 is the highest priority and 5 is the lowest.
Calls will be made sequentially depending on the value set, starting with the highest priority numbers and ending with the lowest priority ones.
dialerPriority
has several usage details.
- If the priority is not specified explicitly, the priority will be set to 5 by default.
- If the priority is specified incorrectly, for example 7, the call priority will be set to 5 by default.
- If within the dialog
$dialer.redial
with an explicitly specified priority is called, the initially set priority will be overridden. - If within the dialog
$dialer.redial
without an explicitly specified priority is called, the initially set priority will be used.
Duplicate numbers in call campaigns
Phone numbers are considered duplicates:
- If they have the identical
phone
values and the identicalpayload
objects. - If they have the identical
phone
values and thepayload
field is not specified.
If you use the same phone number to test a call campaign, use the GET /api/crmCalls/campaign/{token}/test/addPhone
method.
Restrictions for adding duplicates
Let’s suppose you already added a number to a call campaign. Then you perform a second request to add a duplicate. The result of the second request differs in the following cases:
-
Both requests are performed without an idempotence key :
- If 24 hours have not passed since the first request, the second request returns an error.
- If 24 hours already passed, a new call job is created for this number.
-
Both requests have the same idempotence key:
- If 24 hours have not passed since the first request, the second request is executed successfully, but the call job is not created. The request will returns the ID of the same job that was previously created by the first request.
- If 24 hours already passed, a new job is created for this number, because idempotence keys expire 1 day after their first usage.
-
Requests have different idempotence keys or one of them has no key:
The request is successful, a new call job is created.
Error when adding duplicates in one request
If there are duplicates in the body of the POST /api/calls/campaign/{token}/addPhones
request, it returns an error.
The phonesDuplicates
field contains a list of numbers that have duplicates in the request.
Request body:
[
{
"phone": "79123456789",
"payload": {"Name":"Alex"}
},
{
"phone": "79123456789",
"payload": {"Name":"Alex"}
},
{
"phone": "9991112223330"
},
{
"phone": "9991112223330"
}
]
Response:
{
"type": "phone.duplicated",
"phone": "9991112223330",
"message": "",
// Numbers that have duplicates in the request
"phonesDuplicates": [
"9991112223330",
"79123456789"
]
}
Example request
curl --request POST 'https://app.jaicp.com/api/calls/campaign/8231.7056.1b131df1/addPhones' \
--header 'Content-Type: application/json' \
--header 'Idempotence-Key: d5f41bd4' \
--data-raw '[
{
"phone": "79123456789",
"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": 0,
"gmtZone": "-05:00"
}
]'
The response to this request will be an array of all created call job IDs.