Добавление номеров в обзвон


Следующий метод Calls API служит для добавления в обзвон номеров с параметрами:

  • POST /api/calls/campaign/{token}/addPhones

Тело запроса

В теле запроса к данному методу передается массив объектов, описывающих добавляемые в обзвон номера и политику звонков на каждый номер. В каждом объекте можно задать следующие поля.

Поле Описание Обязательное Пример
phone Номер телефона абонента. Да "79110000000"
payload Произвольные дополнительные данные, которые необходимо передать в сценарий. Нет {"promo": "Скидка 20% на все тарифы JAICP!"}
startDateTime Начальное время звонка. Звонок будет совершен в интервале от startDateTime до finishDateTime. Нет "2020-03-23T00:00:00Z"
finishDateTime Конечное время звонка. После finishDateTime звонки совершаться не будут. Нет "2020-03-23T00:00:00Z"
allowedDays Дни недели, в которые звонок может быть совершен. Нет ["mon", "wed", "fri"]
allowedTime Временные интервалы для каждого дня недели, в которые может быть совершен звонок. Нет {"default": [{"localTimeFrom": "10:00", "localTimeTo": "18:00"}]}
retryIntervalInMinutes Пауза между попытками дозвониться в минутах. Нет 120
maxAttempts Количество попыток дозвониться. Нет 1
gmtZone Часовой пояс абонента. Нет "+03:00"
dialerPriority Приоритет номера телефона. Нет 2

Допустимое время звонка

allowedDays

Поле allowedDays задает дни недели, в которые может быть совершен звонок. Значение поля — массив, в котором могут содержаться следующие строки: "mon", "tue", "wed", "thu", "fri", "sat", "sun".

При явном указании поля allowedDays звонок возможен только в разрешенные в нем дни недели. Настройки allowedTime для других дней недели при этом игнорируются.

allowedTime

Поле allowedTime позволяет указать для каждого дня недели один или несколько возможных временных интервалов, в которые может быть совершен звонок.

Значение поля — это объект с ключами, соответствующими допустимым названиям дней недели из поля allowedDays, а также ключом default. В значении по каждому ключу содержится массив объектов с вложенными полями localTimeFrom и localTimeTo — самым ранним и поздним временем для звонка.

Время указывается в формате HH:mm. Указанное время является относительным — при звонке учитывается местное время абонента.

Звонки в дни недели, не указанные в теле запроса, будут совершаться в рамках интервалов, переданных по ключу default.

localTimeFrom и localTimeTo

При указании localTimeFrom и localTimeTo следует учитывать следующие особенности:

  • В каждом интервале обязательно указывать как верхнюю, так и нижнюю границы. Отсутствие одной из границ приведет к ошибке.
  • Интервалы не должны пересекаться: верхняя граница одного интервала не должна быть позже, чем нижняя граница другого. Такая ситуация также приведет к ошибке.
  • Если localTimeFrom больше, чем localTimeTo, интервал считается корректным: он начинается в указанный день, а завершается на следующий день.
[
  {
    "localTimeFrom": "10:00"
  }
] // Ошибка: не указана верхняя граница

[
  {
    "localTimeFrom": "10:00",
    "localTimeTo": "13:30"
  },
  {
    "localTimeFrom": "13:00",
    "localTimeTo": "14:30"
  }
] // Ошибка: пересекающиеся интервалы

[
  {
    "localTimeFrom": "20:00",
    "localTimeTo": "03:00"
  }
] // Корректный интервал с 8 вечера до 3 ночи

Часовой пояс абонента

Значение gmtZone должно удовлетворять любому из следующих форматов:

  • Z — время UTC.
  • +h, +hh, ±hhmm или ±hhmmss с опциональными элементами:
    • разделитель : между часами, минутами и секундами, например +hh:mm:ss;
    • префикс UTC, GMT или UT, например GMT-hh:mm.
  • ID часовых поясов, установленных IANA TZDB.

Приоритет номера телефона

Поле dialerPriority позволяет установить приоритет номера телефона от 1 до 5, где 1 — наивысший приоритет, а 5 — наименьший.

В зависимости от установленного значения звонки в обзвоне будут выполняться последовательно, начиная с более приоритетных номеров телефона и заканчивая менее приоритетными.

У dialerPriority есть ряд особенностей.

  • Если приоритет не указан явно, то по умолчанию установится приоритет, равный 5.
  • Если приоритет указан неверно, например 7, то по умолчанию установится приоритет, равный 5.
  • Если в ходе диалога будет вызван метод $dialer.redial с явно заданным приоритетом, то изначально установленный приоритет будет переопределен.
  • Если в ходе диалога будет вызван метод $dialer.redial с не заданным приоритетом, то звонок будет совершен с изначально установленным приоритетом.

Пример запроса

curl --request POST 'https://app.jaicp.com/api/calls/campaign/8231.7056.1b131df1/addPhones' \
--header 'Content-Type: application/json' \
--data-raw '[
  {
    "phone": 79110000000,
    "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": "+03:30"
  }
]'

Ответ на запрос — массив идентификаторов всех созданных заданий на обзвон.