Про API
Сopied

Для работы Вам понадобится ключ (токен) доступа к API.
Ключ позволяет идентифицировать Ваш проект и получать к нему доступ с максимальными привилегиями без необходимости предварительной авторизации каждый раз.
На странице личного кабинета «API» необходимо создать ключ:

api_key_gen_ru

Этот ключ необходимо указывать при каждом запросе в заголовке Authorization.
Все относительные пути всех методов, описанных в этой документации, имеют пути относительно: https://api.unitalk.cloud/tracking/api
Все запросы к методам API выполняются в режиме POST.
Пример указания режима, необходимого заголовка авторизации и адреса метода для запроса в Postman выглядит следующим образом:

API references

Также можно отправлять ключ в формате «Bearer *Ваш ключ*»

В случае если заголовок или ключ в нем авторизации будет отсутствовать или указан неверно, результат выполнения метода
будет следующим:

{"status": "Error", "message": "Authorization invalid"}

Любой метод из описанного API может вернуть ошибку:

{"status": "Error", "message": "Internal error"}

О таких ошибках сообщайте, пожалуйста, в техническую поддержку.

В общем случае ошибки выполнения методов имею следующую структуру:

{
    "status": "Error",
    "message": "*Текст ошибки*",
    "data": "*Дополнительная информация*"
}

Далее в этой инструкции будут рассматриваться поля message и data (если присутствует).

Да, мы знаем что в JSON не может быть комментариев, но уверены что так понять будет проще 🙂

Обзвон номеров
Сopied

Работа с обзвонами выполняется с помощью действий, метод :

Относительный путь: /autodial/action
Режим: POST
Content-Type: application/json

Действия указываются в теле запроса в обязательном параметре action и определяют перечень необходимых параметров. Перечень существующих действий:

GET_LISTПолучить список обзвонов
GET_WITH_DATAПолучить список обзвонов со всеми данными
ADDДобавить обзвон
UPDATEОбновить обзвон
REMOVEУдалить обзвон
REFRESHПрозвонить повторно
CANCELОтменить обзвон
PAUSEПоставить на паузу
UNPAUSEСнять с паузы
ADD_NUMBERSДобавить номера
GET_NUMBERПолучить информацию про номер обзвона
GET_NUMBERSПолучить информацию про номера обзвона
GET_CALLS_HISTORYПолучить информацию про звонки обзвона
REMOVE_NUMBERSУдалить номера из обзвона
REMOVE_ALL_NUMBERSУдалить все номера из обзвона

Поскольку данный метод имеет множество вариаций использования и разнообразных параметров, рекомендуется настроить несколько обзвонов в личном кабинете и ознакомиться с их функционалом визуально, прежде чем изучать данную инструкцию.

Возможные ошибки:

Action is nullЦелевое действие не указано
Invalid actionНеверно указано целевое действие

Получение списка обзвонов
Сopied

JSON запроса:

{ 
  "action": "GET_LIST" 
}

Пример ответа в случае успеха:

[
  {
    "id": 111, // Уникальный идентификатор обзвона
    "name": "Sample_name", // Название обзвона
    "type": "AUTODIAL" // Тип обзвона
  },
  ...
]

Существующие типы обзвонов приведены в соответствующем словаре.

Получение полной информации про обзвоны с дополнительными данными
Сopied

Действие «Получить список обзвонов с дополнительными данными» позволяет получить детальную информацию о текущей конфигурации обзвонов проекта в массиве tasks. Кроме того дополнительно передаются словари, параметры и списки, которые могут понадобиться для интерпретации и изменения конфигураций обзвонов.

Перечень дополнительных списков:
· audios — массив аудиозаписей проекта из раздела «Автообзвоны»
· moh — массив аудиозаписей проекта из раздела «Мелодии ожидания на линии и очередей»
· groups — массив групп внутренних линий проекта
· scenarios — массив входящих сценариев проекта
· outScenarios — массив исходящих сценариев проекта
· ttsSettings — массив профилей настроек синтеза речи проекта
· voiceSecretaries — массив голосовых секретарей проекта
· Массивы triggerActionEventsData и triggerActionEventsAndTriggerActions предоставляют такую информацию о событиях обзвонов как порядковый номер и список доступных обработчиков

Перечень дополнительных словарей:
· triggerActionEventsпрейти к словарю
· taskStatusesперейти к словарю
· Параметры autodialNumberStatesInfo и statesInfo содержат информацию соответствующую словарю callState в различных представлениях
· autodialerTypesперейти к словарю
· autodialerModesперейти к словарю
· audioSynthesisDynamicValuesперейти к словарю
· withdrawalCategories

Перечень дополнительных параметров:
· triggerActionsPresent — указывает на наличие в проекте обработчиков событий
· maxAddNumbersCount — максимальное количество номеров, которое можно добавить за одно действие
· maxRemoveNumbersCount — максимальное количество номеров, которое можно удалить за одно действие
· multiAudiosLimit — максимальное количество элементов в списке compositeAudio
· minMultiAudioSilenceMillis — минимальное количество миллисекунд в элементе silenceMillis массива compositeAudio
· maxMultiAudioSilenceMillis — максимальное количество миллисекунд в элементе silenceMillis массива compositeAudio

JSON запроса:

{ 
  "action": "GET_WITH_DATA" 
}

Пример ответа в случае успеха:

{
  "audios": { // Массив аудио
    "1234": "Sample_audio_name", // "ID": "Название"
    ...
  },
  "moh": { // Массив мелодий ожидания на линии
    "2345": "Sample_moh_name", // "ID": "Название"
    ...
  },
  "groups": { // Массив групп внутренних линий
    "3456": "Sample_group_name", // "ID": "Название"
    ...
  },
  "scenarios": { // Массив входящих сценариев
    "4567": "Main with IVR", // "ID": "Название"
    ...
  },
  "outScenarios": { // Массив исходящих сценариев
    "5678": "From a fixed number", // "ID": "Название"
    ...
  },
  "ttsSettings": { // Массив профилей настроек синтеза речи
    "12": "Pretty woman voice", // "ID": "Название"
    ...
  },
  "voiceSecretaries": { // Массив голосовых секретарей
    "97": "Sample_voice_secretary_name", // "ID": "Название"
    ...
  },
  "triggerActionEvents": { // Массив событий для обзвона
    "AUTODIAL_FINISH": "Обзвон завершен", // "Событие": "Название"
    ...
  },
  "triggerActionEventsData": [ // Информация о событиях обзвонов
    {
      "event": "AUTODIAL_FINISH", // Событие
      "title": "Обзвон завершен", // Название события
      "order": 200 // Порядковый номер
    },
    ...
  ],
  "triggerActionEventsAndTriggerActions": { // Списки доступных обработчиков для каждого из событий
    "AUTODIAL_FINISH": { // "Событие": {Список доступных обработчиков}
      "123": "[Telegram] Personal notification", // "ID": "Название"
      ...
    },
    ...
  },
  "triggerActionsPresent": true, // Признак наличия в проекте обработчиков событий
  "autodialNumberStatesInfo": { // Информация о состояниях номеров обзвонов
    "lang": { // Язык проекта
      "locale": "ru",
      "shortLocaleCode": "ru",
      "code": "RU"
    },
    "orderedStates": [ // Упорядоченный список состояний на основании порядкового номера
      "NEW",
      ...
    ],
    "statesAndTitles": { // Массив состояний с названиями
      "DIALING": "В процессе обзвона",
      ...
    },
    "repeatableStates": [ // Список состояний доступных для автоматического повторного прозвона
      "BUSY",
      ...
    ],
    "refreshableStates": [ // Список состояний доступных для метода REFRESH
      "FAIL", 
      ...
    ],
    "warningStates": [ // Список состояний свидетельствующих о возможных проблемах в настройках обзвона или телефонии
      "AUDIO_ERR",
      ...
    ],
    "doneStates": [ // Список состояний соответствующих завершенным звонкам
      "ANSWER",
      ...
    ]
  },
  "taskStatuses": { // Массив состояний обзвона
    "IN_PROGRESS": "В процессе обзвона",
    ...
  },
  "autodialerTypes": { // Массив типов обзвонов
    "AUTODIAL": "Autodialer",
    "GUARANTEED_DIAL": "Guaranteed autodialer",
    "VOICE_ROBOT": "Voice robot"
  }
  "autodialerModes": { // Массив режимов обзвонов
    "FIXED": "By number of threads",
    "FREE": "By free operators",
    "SMART": "Smart selection"
  },
  "maxAddNumbersCount": 100000, // Максимальное количество номеров, которое можно добавить за одно действие
  "maxRemoveNumbersCount": 10000, // Максимальное количество номеров, которое можно удалить за одно действие
  "multiAudiosLimit": 20, // Максимальное количество элементов в списке compositeAudio
  "minMultiAudioSilenceMillis": 1, // Минимальное количество миллисекунд в элементе silenceMillis массива compositeAudio
  "maxMultiAudioSilenceMillis": 10000, // Максимальное количество миллисекунд в элементе silenceMillis массива compositeAudio
  "audioSynthesisDynamicValues": { // Массив динамических значений
    "NA": "Autodialer number: name",
    "NO": "Autodialer number: note",
    "LI": "Autodialer number: data for Web Dialer",
    "P1": "Autodialer number: parameter #1",
    "P2": "Autodialer number: parameter #2",
    "P3": "Autodialer number: parameter #3",
    "P4": "Autodialer number: parameter #4",
    "P5": "Autodialer number: parameter #5",
    "P6": "Autodialer number: parameter #6",
    "P7": "Autodialer number: parameter #7",
    "P8": "Autodialer number: parameter #8",
    "P9": "Autodialer number: parameter #9",
    "P10": "Autodialer number: parameter #10"
  },
  "withdrawalCategories": { // Массив категорий списаний обзвонов
    "CALL": "Совершение звонков",
    "AUTODIALER": "Обзвон",
    "VOICE_SECRETARY": "Голосовой секретарь",
    "TEXT_TO_SPEECH": "Синтез речи",
    "SPEECH_RECOGNITION": "Распознавание речи",
    "VOICE_ANALYTICS": "Речевая аналитика",
    "ANSWERING_MACHINE_DETECTION": "Распознавание автоответчика",
    "MESSAGE_SERVICE_MESSAGE": "Отправка сообщений"
  },
  "tasks": [ // Массив всех обзвонов
    { 
      "id": 12345, // ID обзвона
      "name": "Обзвон окна", // Название обзвона
      "autodialerType": "AUTODIAL", // Тип обзвона
      "autodialerMode": "FIXED", // Режим обзвона
      "statistics": { // Статистика номеров обзвона
        "totalCount": 10, // Всего номеров
        "doneCount": 6, // Обработано номеров 
        "repeatCount": 2 // Повторных звонков
        "callsDoneCount": // Количество завершенных звонков
        "statesCount": { // Статистика номеров по статусам 
          "NEW": 3, // "ID": Количество
          ...
        }  
      },
      "finishedDate": "2020-04-21", // Дата завершения обзвона. Присутствует в обзвона с состоянием FINISHED 
      "threadCount": 1, // Количество параллельных звонков. Присутствует в обзвонах с режимом FIXED 
      "delay": 2, // Пауза между концом воспроизведения аудиозаписи и запуском сценария в секундах. Присутствует в обзвонах с типом AUTODIAL
      "smartSpeed": 0, // Регулятор скорости обзвона. Присутствует в обзвонах с режимом SMART
      "coldBaseStartCallsMultiplier": null, // Если не null, изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом. Присутствует в обзвонах с режимами FREE и SMART
      "callDelay": 0, // Пауза между звонками в секундах. Присутствует в обзвонах с режимом FIXED и учитывается только при количестве потоков - 1
      "callDelayOnlyAnswered": true, // Пауза между звонками будет срабатывать только после звонков отвеченных оператором. Присутствует в обзвонах с режимом FIXED
      "compositeAudio": {  // Содержит информацию о комбинированном аудио, которое будет воспроизведено при ответе клиентом на звонок. Присутствует в обзвонах с типом AUTODIAL
        "multiAudios": [ // Список частей аудио
          {
            "silenceMillis": 500 // Длительность тишины в миллисекундах
          },
          {
            "id": 46615  // ID аудиозаписи проекта
          },
          {
            "synthesisFromDynamicValue": { // Данные для синтеза речи
              "dynamicValue": "NO", // Динамическое значение, значение которого будет синтезировано
              "settingsId": 117 // ID профиля настройки синтеза аудио, который будет использоваться вместо указанного в настройках обзвона. Может быть null
            }
          }
        ]
      },
      "moh": 53, // ID аудио, которое клиент будет слышать ожидая соединение с оператором. Может быть null. Присутствует в обзвонах с типом GUARANTEED_DIAL
      "startDate": "2020-03-15", // Дата начала периода проведения обзвона (включительно) 
      "endDate": "2020-05-15", // Дата окончания периода проведения обзвона (включительно)
      "timeFrom": [ // Время начала обзвона по дням недели в формате "HH:mm"
        "09:00", // Понедельник 
        "11:00", // Вторник 
        "11:00", // Среда 
        "11:00", // Четверг 
        "11:00", // Пятница 
        null,    // Суббота, null - обзвон в этот день не работает 
        "14:00"  // Воскресенье 
      ], 
      "timeTo": [ // Время окончания обзвона по дням недели 
        "19:00", 
        "19:00", 
        "19:00", 
        "19:00", 
        "19:00", 
        null, 
        "17:00" 
      ],
      "voiceSecretaryId": 25 // ID голосового секретаря. Присутствует в обзвонах с типом VOICE_ROBOT
      "groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона. Присутствует в обзвонах с типом GUARANTEED_DIAL или режимами FREE и SMART
      "scenarioId": null, // ID входящего сценария, который будет активирован, если клиент останется на линии после завершения аудио. Может быть null. Присутствует в обзвонах с типом AUTODIAL 
      "outScenarioId": null, // ID исходящего сценария, который будет использован для звонков обзвона. Может быть null. 
      "pauseOperatorNoAnswerLimit": 5, // Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу. Может быть null. Присутствует в обзвонах с режимами FREE и SMART
      "ttsSettingsId": 18, // ID профиля настроек синтеза речи. Может быть null. Присутствует в обзвонах с типами AUTODIAL и GUARANTEED_DIAL
      "useTaskAudioIfAudioError": false, // При ошибке аудио: true - “Использовать аудио обзвона”, false - “Завершить звонок с ошибкой”. Присутствует в обзвонах с типами AUTODIAL и GUARANTEED_DIAL
      "repeatCallAttempts": 3, // Количество повторных прозвонов. Значения 0 и null означают, что повторный прозвон отключен
 	    "repeatCallIntervalMinutes": 30, // Минимальный интервал повторных прозвонов в минутах
      "repeatCallHighPriority": false, // Значение true указывает на необходимость внесения повторных прозвонов в приоритетную очередь
      "repeatCallStates": [ // Список статусов звонков, которые будут повторно прозваниваться. Если пустой или null - повторный прозвон отключён
        "NOANSWER",
        ...
      ],
      "callerIdPrefix": null, // Префикс, который будет отображаться в SIP клиенте перед номером телефона. Может быть null
      "crmMode": "DONT_SEND", // Определяет какие звонки будут отправлены в CRM
      "clientCalledMode": "NEVER", // Указывает на необходимость игнорировать номера абонентов, от которых поступали звонки
      "displayName": false, // Указывает на необходимость показывать имя закрепленное за номером в SIP клиенте
      "displayNote": false, // Указывает на необходимость показывать примечание к номеру в SIP клиенте
      "removeAfterFinish": false, // Указывает на необходимость удалить обзвон после завершения
      "markAsBusySeconds": 60, // Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Присутствует в обзвонах с режимами FREE и SMART
      "markAsBusyMinSecondsTalk": 15, // Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах. Присутствует в обзвонах с режимами FREE и SMART
      "reservedSipsBusyOnlyForAutodials": true, // Указывает на доступность внутренних линий для звонков, поступающих по входящим сценариям. Присутствует в обзвонах с режимами FREE и SMART
      "triggerActions": { // Список событий и обработчиков за ними закрепленными
        "AUTODIAL_NOANSWER": [ // Событие
          2, // ID обработчика событий
          ...
        ],
        ...
      },
      "withdrawalStatistics": { // Массив с информацией про общие траты обзвона
        "total": "12.47", // Сумма списаний по всем категориям
        "byCategories": { // Массив сумм списаний по категориям
          "CALL": "0.60",
          ...
        }
      },
      "taskStatusInfo": { // Информация о статусе обзвона
        "millis": 1631828328839,
        "status": "FINISHED",
        "dateForDescription": "2021-09-08",
        "durationMillis": 36253180657
      }
    },
    ...
  ],
  "statesInfo": [ // Информация о статусах звонков обзвона
    {
      "state": "NEW", // ID статуса
      "order": 10, // Порядковый номер
      "title": "Не обработано", // Название статуса
      "repeatable": false, // Доступен для автоматического повторного прозвона (поле repeatCallStates)
      "refreshable": false, // Доступен для метода REFRESH
      "warning": false // Свидетельствует о возможных проблемах в настройках обзвона или телефонии
    },
    ...
  ]
}

Создание и изменение обзвонов
Сopied

Действия «Создать» и «Изменить» позволяют конфигурировать новый или существующий обзвоны соответственно. Часть параметров является общей для всех типов и режимов обзвонов. Создание и изменение обзвонов будет рассмотрено на примере одного запроса, поскольку различия незначительны:
· id — Уникальный идентификатор изменяемого обзвона не учитывается при создании
· autodialerType — Тип обзвона не учитывается при изменении
· При создании обзвона можно опционально передать перечень номеров для обработки в параметре numbers и указать необходимость их обработки в приоритетной очереди в параметре highPriority. Номера в массиве numbers необходимо указывать в международном формате, все сторонние символы будут предварительно удалены. Для добавления номеров в существующий обзвон используйте действие ADD_NUMBERS.

crmMode определяет информация о каких звонках будет передана в CRM. Доступные значения:
· DONT_SEND — Никакие
· SEND_ANSWERED — Отвеченные абонентом
· SEND_SUCCESS — Отвеченные абонентом и оператором
· ALL_CALLS — Все

clientCalledMode указывает на необходимость игнорировать номера абонентов, от которых поступали звонки. Доступные значения:
· NEVER — Никогда
· ANSWERED_CALLS — Только если звонок отвечен
· ALL_CALLS — Всегда

Пример общей части JSON запроса:

{
  "action": "ADD", // Или "UPDATE"
  "task": {
     "id": 0, // ID существующего обзвона для "UPDATE". При "ADD" не учитывается
     "name": "Обзвон", // Должно быть уникальным
     "autodialerType": "AUTODIAL", // Тип обзвона. При "UPDATE" не учитывается
     "autodialerMode": "FIXED", // Режим обзвона
     "startDate": "2020-03-15", // Дата начала периода проведения обзвона (включительно) 
     "endDate": "2020-05-15", // Дата окончания периода проведения обзвона (включительно)
     "timeFrom": [ // Время начала обзвона по дням недели в формате "HH:mm". Может быть null
       "09:00", // Понедельник 
       "11:00", // Вторник 
       "11:00", // Среда 
       "11:00", // Четверг 
       "11:00", // Пятница 
       null,    // Суббота, null - обзвон в этот день не работает 
       "14:00"  // Воскресенье 
     ], 
     "timeTo": [ // Время окончания обзвона по дням недели 
       "19:00", 
       "19:00", 
       "19:00", 
       "19:00", 
       "19:00", 
       null, 
       "17:00" 
     ],
     "outScenarioId": 567, // ID исходящего сценария, который будет использован для звонков обзвона. Может быть null
     "triggerActions": { // Список событий и обработчиков за ними закрепленными. К одному событию можно прикрепить максимум 5 обработчиков
       "AUTODIAL_NOANSWER": [ // Событие
         2, // ID обработчика событий
         ...
       ],
       ...
     },
     "callerIdPrefix": "pref", // Префикс, который будет отображаться в SIP клиенте перед номером телефона. Может быть null
     "crmMode": "DONT_SEND", // Определяет какие звонки будут отправлены в CRM
     "clientCalledMode": "NEVER", // Указывает на необходимость игнорировать номера абонентов, от которых поступали звонки
     "repeatCallAttempts": 3, // Количество повторных прозвонов. Доступны значения от 0 до 10. Значения 0 и null отключают повторный прозвон
     "repeatCallIntervalMinutes": 10, // Минимальный интервал повторных прозвонов в минутах. Доступны значения от 5 до 1500
     "repeatCallHighPriority": false, // Значение true указывает на необходимость внесения повторных прозвонов в приоритетную очередь
     "repeatCallStates": [ // Список статусов звонков, которые будут повторно прозваниваться. Может быть пустым или null, если repeatCallAttempts равно 0 или null
       "NOANSWER",
       ...
     ],
     "displayName": true, // Показывать имя закрепленное за номером в SIP клиенте
     "displayNote": false, // Показывать примечание к номеру в SIP клиенте
     "removeAfterFinish": false, // Удалить обзвон после завершения
     "numbers":[ // Массив номеров для обзвона. При "UPDATE" не учитывается. Может быть null
       "+38(097)11-11 111",
       ...
     ],
     "highPriority": true // Указывает на необходимость добавления номеров с высоким приоритетом. Такие номера обзваниваются в первую очередь. При "UPDATE" не учитывается
     ...
   }
}


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

Для обзвонов с типом AUTODIAL обязательно наличие одного из параметров compositeAudio и scenarioId. Параметр compositeAudio должен содержать объект multiAudios который представляет собой массив, который используется для указания аудио. Каждый элемент массива multiAudios представляет собой ссылку аудиозапись в проекте (id), тишину (silenceMillis) или синтез аудио (synthesisFromDynamicValue). Синтез аудио должен содержать параметр dynamicValue, значение которого — соответствует одному из ключей соответствующего словаря. Порядок расположения аудио в массиве соответствует порядку воспроизведения. Для корректного синтеза аудио обязательно наличие одного из параметров settingsId части синтеза и ttsSettingsId обзвона.

Пример специфической для типа обзвона AUTODIAL части JSON запроса:

     ...
     "scenarioId": 70, // ID входящего сценария, который будет активирован, если клиент останется на линии после завершения аудио
     "compositeAudio": {  // Содержит информацию о комбинированном аудио, которое будет воспроизведено при ответе клиентом на звонок
       "multiAudios": [ // Список частей аудио
         {
           "silenceMillis": 500 // Длительность тишины в миллисекундах
         },
         {
           "id": 46615  // ID аудиозаписи проекта
         },
         {
           "synthesisFromDynamicValue": { // Данные для синтеза речи
             "dynamicValue": "NO", // Динамическое значение, значение которого будет синтезировано
             "settingsId": 117 // ID профиля настройки синтеза аудио, который будет использоваться вместо указанного в настройках обзвона. Может быть null
           }
         }
       ]
     },
     "ttsSettingsId": 18, // ID профиля настроек синтеза речи для обзвона. Может быть null
     "useTaskAudioIfAudioError": true, // При ошибке аудио: true - “Использовать аудио обзвона”, false - “Завершить звонок с ошибкой”
     "delay": 2, // Пауза между концом воспроизведения аудио обзвона и запуском входящего сценария в секундах. Может быть 0
     ...

Для обзвонов с типом GUARANTEED_DIAL обязательно указание группы внутренних линий в параметре groupId.

Пример специфической для типа обзвона GUARANTEED_DIAL части JSON запроса:

     ...
     "moh": 255, // ID аудио, которое клиент будет слышать ожидая соединение с оператором. Может быть null
     "groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона
     "ttsSettingsId": 18, // ID профиля настроек синтеза речи для обзвона. Может быть null
     "useTaskAudioIfAudioError": true, // При ошибке аудио: true - “Использовать аудио обзвона”, false - “Завершить звонок с ошибкой”
     ...

Для обзвонов с типом VOICE_ROBOT обязательно указание голосового секретаря в параметре voiceSecretaryId.

Пример специфической для типа обзвона VOICE_ROBOT части JSON запроса:

     ...
     "voiceSecretaryId": 25 // ID голосового секретаря
     ...


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

Для обзвонов с режимом FIXED обязательно указание количества параллельных звонков (потоков) в параметре threadCount.

Пример специфической для режима обзвона FIXED части JSON запроса:

     ...
     "threadCount": 1, // Количество параллельных звонков
     "callDelay": 30, // Пауза между звонками в секундах. Учитывается только при количестве параллельных звонков - 1
     "callDelayOnlyAnswered": true, // Пауза между звонками будет срабатывать только после звонков отвеченных оператором
     ...

Для обзвонов с режимом FREE обязательно указание группы внутренних линий в параметре groupId. Кроме того доступны дополнительные параметры:
· coldBaseStartCallsMultiplier — Изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом. Доступны значения от 0.1 до 1.5
· pauseOperatorNoAnswerLimit — Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу
· markAsBusySeconds — Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Доступны значения от 0 до 3600
· markAsBusyMinSecondsTalk — Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах. Доступны значения от 0 до 3600
· reservedSipsBusyOnlyForAutodials — Определяет будут ли внутренние линии из закрепленной группы обзвона доступны для звонков, поступающих по входящим сценариям

Пример специфической для режима обзвона FREE части JSON запроса:

     ...
     "groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона
     "coldBaseStartCallsMultiplier": null, // Изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом
     "pauseOperatorNoAnswerLimit": 5, // Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу
     "markAsBusySeconds":60, // Количество секунд на которое SIP линия отмечается занятой после успешного звонка
     "markAsBusyMinSecondsTalk":15, // Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах
     "reservedSipsBusyOnlyForAutodials": true, // Указывает на доступность внутренних линий для звонков, поступающих по входящим сценариям
     ...

Для обзвонов с режимом SMART обязательно указание группы внутренних линий в параметре groupId. Кроме того доступны дополнительны параметры:
· coldBaseStartCallsMultiplier — Изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом. Доступны значения от 0.1 до 1.5
· pauseOperatorNoAnswerLimit — Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу
· markAsBusySeconds — Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Доступны значения от 0 до 3600
· markAsBusyMinSecondsTalk — Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах. Доступны значения от 0 до 3600
· reservedSipsBusyOnlyForAutodials — Определяет будут ли внутренние линии из закрепленной группы обзвона доступны для звонков, поступающих по входящим сценариям
· smartSpeed — Допустимые значения от -10 до 10 пропорционально влияют на скорость обзвона

Пример специфической для режима обзвона SMART части JSON запроса:

     ...
     "groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона
     "coldBaseStartCallsMultiplier": null, // Изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом
     "pauseOperatorNoAnswerLimit": 5, // Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу
     "markAsBusySeconds":60, // Количество секунд на которое SIP линия отмечается занятой после успешного звонка
     "markAsBusyMinSecondsTalk":15, // Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах
     "reservedSipsBusyOnlyForAutodials": true, // Указывает на доступность внутренних линий для звонков, поступающих по входящим сценариям
     "smartSpeed": 5, // Допустимые значения от -10 до 10 пропорционально влияют на скорость обзвона
     ...

Пример ответа в случае успеха:

{"status": "Success", "data": 12345}

При выполнении действия ADD в поле data передается id созданного обзвона.
Возможные ошибки:

task is nullПоле task не указано в запросе
Please confirm phone numberНеподтвержденные проекты не могут создавать обзвоны
Billing not allowНа данном тарифе обзвон недоступен, либо тариф не оплачен
Task not foundОбзвон не найден по id при UPDATE
groupId is nullТип обзвона GUARANTEED_DIAL или режим FREE или SMART, но поле groupId не указано в запросе
Group not foundТип обзвона GUARANTEED_DIAL или режим FREE или SMART, но группа операторов с указанным id не найдена
Wrong group typeТип обзвона GUARANTEED_DIAL или режим FREE или SMART, но указанная группа не является группой внутренних линий
Moh not foundТип обзвона GUARANTEED_DIAL, но аудио мелодии ожидания не найдено по указанному id
Wrong audio type: mohТип обзвона GUARANTEED_DIAL, но по указанному id найдено аудио другой категории
In scenario not foundТип обзвона AUTODIAL, но входящий сценарий по указанному id не найдено
Not found in scenario and audioТип обзвона AUTODIAL, но ни аудио, ни входящий сценарий не указаны в запросе
voiceSecretaryId is nullТип обзвона VOICE_ROBOT, но голосовой секретарь не указан в запросе
Voice secretary not foundТип обзвона VOICE_ROBOT, но голосовой секретарь по указанному id не найдено
compositeAudioОшибка при указании комбинированного аудио в обзвонах типа AUTODIAL. Возможные причины:
· too many audio parts — в комбинированном аудио указано более 20 частей
· audio not found — аудио не найдено по указанному id
· audio type is not AUTODIAL — по указанному id найдено аудио другой категории
· synthesis dynamicValue is null — в элементе синтеза речи не указан параметр dynamicValue
· speech synthesis settings not found — по указанному settingsId не найден профиль настроек синтеза аудио
· invalid silenceMillis — Значение silenceMillis не в диапазоне от 1 до 10 000
Wrong nameНазвание не может быть пустым или длиннее 45 символов
Name already presentОбзвон с таким названием уже существует в проекте
Not found out scenarioПо указанному id не найден исходящий сценарий
Wrong datesДаты обзвона не указаны, или дата старта обзвона превышает дату окончания
Wrong time rangesВ массиве timeFrom или timeTo не 7 элементов, в какой либо паре timeFrom позже чем timeTo или все элементы null
Prefix is too longПрефикс не должен превышать 20 символов
Handler is busy, try again laterОдин проект одновременно может удалять или добавлять номера только в одном обзвоне.
В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров.
Повторите попытку позже, когда предыдущая операция завершится.
Может возникнуть только если указан параметр numbers при действии ADD
Wrong numbersВ массиве numbers присутствуют некорректные номера. В поле data будет указан массив элементов numbers, которые не прошли валидацию
Repeat call states is emptyrepeatCallAttempts указывает на необходимость автоматического прозвона номеров, но repeatCallStates пустой или null
Repeat call state is not allowedВ массиве repeatCallStates был передан недопустимый callState
Not found text to speech settingsПо указанному id не найден профиль настройки синтеза аудио
Wrong trigger action eventВ массиве triggerActions передан недопустимый triggerActionEvent или null
triggerActionIds is nullВ массиве triggerActions у одного из triggerActionEvent недопустимое значение null
Too many trigger actionsВ массиве triggerActions для одного из triggerActionEvent передан массив с более чем 5 обработчиками
Trigger action not foundПо одному из указанных в triggerActions id не найден обработчик
Few trigger actions with same typeВ массиве triggerActions для одного из triggerActionEvent указано 2 обработчика событий с одинаковым типом действия
Not compatible trigger actionВ массиве triggerActions для одного из triggerActionEvent указан id обработчика событий, который несовместим с этим triggerActionEvent
crmMode is nullПоле crmMode не указано в запросе
clientCalledMode is nullПоле clientCalledMode не указано в запросе
Tasks limit exceededПревышено максимальное количество обзвонов в проекте

Удаление обзвона
Сopied

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

{
  "id": 1307, // ID целевого обзвона
  "action": "REMOVE"
}

Ответ в случае успеха:

{"status": "Success", "message": "Removed"}

Возможные ошибки:

Task not foundОбзвон не найден по указанному id
Handler is busy, try again laterОдин проект одновременно может удалять или добавлять номера только в одном обзвоне.
В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров.
Повторите попытку позже, когда предыдущая операция завершится

Прозвонить повторно
Сopied

Действие «Прозвонить повторно» позволяет перезапустить обработку номеров находящихся в указанных статусах. Перечень статусов допустимых для использования в данном действии приведен в соответствующем словаре.

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

{
  "id": 1307, // ID целевого обзвона
  "action": "REFRESH",
  "callStates": [ // Массив статусов, номера в которых будут прозвонены повторно
    "NOANSWER",
    ...
  ]
}

Ответ в случае успеха:

{"status": "Success"}

Успешное выполнение данного действия изменит статус выбранных номеров на NEW.

Возможные ошибки:

Task not foundОбзвон не найден по указанному id
states is null or emptyМассив callStates пустой или null
state is not allowedВ массиве callStates указан недопустимый для REFRESH статус
Try again laterПредыдущее выполнение действия для указанного обзвона произошло менее минуты назад
Numbers not found by statesНе найдено ни одного номера с указанными статусами

Отмена обзвона
Сopied

Действие «Отменить обзвон» позволяет остановить обзвон, находящийся в статусе WAITING, IN_PROGRESS или PAUSED. Применение этого действия к обзвонам в статусах FINISHED и CANCELED приведет к ошибке. Применение к NEW — не приведет к каким-либо изменениям.

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

{
  "id": 1307, // ID целевого обзвона
  "action": "CANCEL"
}

Ответ в случае успеха:

{"status": "Success", "message": "Cancelled"}

Успешная отмена изменит статус на CANCELED (пока в обзвоне будут незавершенные звонки), впоследствии статус изменится на FINISHED

Возможные ошибки:

Task not foundОбзвон не найден по указанному id
Task is finishedНевозможно отменить обзвон со статусом FINISHED
Task is canceledНевозможно отменить обзвон со статусом CANCELED

Постановка на паузу
Сopied

Действие «Поставить на паузу» позволяет приостановить обзвон, находящийся в статусе WAITING или IN_PROGRESS. Применение этого действия к обзвонам в статусах FINISHED и CANCELED приведет к ошибке. Применение к NEW или PAUSED — не приведет к каким-либо изменениям.

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

{
  "id": 1307, // ID целевого обзвона
  "action": "PAUSE"
}

Ответ в случае успеха:

{"status": "Success"}

Успешная постановка на паузу изменит статус с WAITING или IN_PROGRESS на PAUSED.

Возможные ошибки:

Task not foundОбзвон не найден по указанному id
Task is finishedНевозможно поставить на паузу обзвон со статусом FINISHED
Task is canceledНевозможно поставить на паузу обзвон со статусом CANCELED

Снятие с паузы
Сopied

Действие «Cнять с паузы» позволяет продолжить обзвон, находящийся в статусе PAUSED. Применение этого действия к обзвонам в статусах FINISHED и CANCELED приведет к ошибке. Применение к NEW, WAITING или IN_PROGRESS — не приведет к каким-либо изменениям.

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

{
  "id": 1307, // ID целевого обзвона
  "action": "UNPAUSE"
}

Ответ в случае успеха:

{"status": "Success"}

Успешное снятие с паузы изменит статус с PAUSED на WAITING или IN_PROGRESS.

Возможные ошибки:

Task not foundОбзвон не найден по указанному id
Task is finishedНевозможно снять с паузы обзвон со статусом FINISHED
Task is canceledНевозможно снять с паузы обзвон со статусом CANCELED

Добавление номеров
Сopied

Действие «Добавить номера» позволяет добавить номера в обзвон двумя способами: указав только номера в массиве numbers или номера с дополнительной информацией в массиве numbersWithData. В случае если указаны оба, будут добавлены номера из обоих массивов. За один запрос возможно добавить до 100 000 номеров, но не более 1 000 000 номеров на один обзвон.

В запросе должен присутствовать один из параметров numbers и numbersWithData. Номера в массиве numbers или параметре phone необходимо указывать в международном формате, все сторонние символы будут предварительно удалены. Массив numbersWithData позволяет передавать номера в виде элементов с дополнительными параметрами, единственным обязательным параметром является phone.

Параметр audios представляет собой массив, который используется для указания аудио, которые будут воспроизведены вместо основного аудио обзвона. Каждый элемент массива audios представляет собой ссылку на аудиозапись в проекте (id) или синтез аудио (tts). В элементе должен присутствовать один из параметров id и tts, если указаны оба будет использован id. Порядок расположения аудио в массиве соответствует порядку воспроизведения. Для типа обзвона AUTODIAL максимум элементов — 5 (из которых 2 синтеза аудио), для GUARANTEED_DIAL — 1, для VOICE_ROBOT параметр игнорируется.

Для типа обзвона AUTODIAL id должен указывать на аудиозапись из раздела «Автообзвоны», для GUARANTEED_DIAL — «Мелодии ожидания». В элементе tts должен присутствовать один из параметров text и ssml, если указаны оба будет использован ssml, максимальное количество символов — 2500. Параметр ssml должен начинаться и заканчиваться тегом speak. Процесс озвучивания происходит перед стартом звонка. Синтезированные аудио хранятся до 7 дней по завершению обзвона, не более 3 месяцев с момента создания и в списке аудиозаписей проекта не отображаются. В случае, если синтезированный текст и профиль настроек совпадают — используется ранее синтезированное аудио.

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

{
  "id": 1307,  // ID целевого обзвона
  "action": "ADD_NUMBERS",
  "refreshDuplicates": true,  // Указывает на необходимость повторно обработать номера, которые уже присутствуют в обзвоне
  "highPriority": true,  // Указывает на необходимость обрабатывать добавляемые номера в первую очередь
  "numbers": [ // Массив номеров, которые необходимо добавить
    "380970000001",
    ...
  ],
  "numbersWithData": [ // Массив номеров с дополнительной информацией, которые необходимо добавить
    {
      "phone": "380670000002",
      "name": "sample_name", // Имя. Учитываются первые 100 символов. Может быть null
      "note": "sample_note", // Примечание. Учитываются первые 500 символов. Может быть null
      "link": "https://...", // Данные для Web Dialer. Учитываются первые 500 символов. Может быть null
      "params": { // Параметры которые будут закреплены за номером в обзвоне. Может быть null
        "1": "sample_value", // Номер параметра (1-10): Значение параметра. Учитываются первые 500 символов. Может быть null
        ...
      },
      "audios": [ // Массив аудиозаписей и синтеза аудио, которые будут проиграны при звонке на номер вместо основного аудио обзвона. Может быть null
            {
                "id": 4953, // ID целевой аудиозаписи
            },
            {
                "tts": { // Данные для синтеза аудио
                    "text": "sample_text", // Текст который будет озвучен
                    "ssml": "<speak>sample_text</speak>",  // Текст который будет озвучен в формате ssml
                    "settingsId": 18 // ID профиля настройки синтеза аудио, который будет использоваться вместо указанного в настройках обзвона. Может быть null
                }
            },
            ...
        ]
    },
    ...
  ]
}

Пример ответа в случае успеха:

{"status": "Success", "message": "Numbers added"}

Успешное добавление номеров в завершенный обзвон (FINISHED) изменит статус на WAITING или IN_PROGRESS.

Возможные ошибки:

Task not foundОбзвон не найден по указанному id
Numbers is null or emptynumbers и numbersWithData пустые или null
Too many numbersПревышен лимит в 100 000 номеров за одно действие
Numbers limit exceededПревышен лимит в 1 000 000 номеров в обзвоне
Handler is busy, try again laterОдин проект одновременно может удалять или добавлять номера только в одном обзвоне.
В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров.
Повторите попытку позже, когда предыдущая операция завершится
Wrong numbersВ массиве numbers присутствуют некорректные номера. В поле data будет указан массив элементов numbers, которые не прошли валидацию
Numbers not addedНе было сохранено ни одного номера
Wrong audiosВ массиве numbersWithData присутствуют номера с некорректным audios.
В поле data будет указан массив номеров с соответствующей ошибкой аудио.
Возможные причины ошибки:
· Too many audios — слишком много элементов
· Too many text to speech — слишком много элементов с синтезом аудио
· Audio is null — присутствуют элементы со значением null
· Audio not found by id — присутствуют id по которым не найдена аудиозапись
· Wrong type of audio — присутствуют id который указывает аудиозапись недопустимого раздела
· Text to speech ‘text’ and ‘ssml’ is null — присутствуют tts в которых оба text и ssml пустые
· Text to speech ‘text’ not valid — присутствуют tts в которых text превышает 2500 символов
· Text to speech ‘ssml’ not valid — присутствуют tts в которых ssml превышает 2500 символов или не начинается и заканчивается тегом speak
· Text to speech settings not found by id — присутствуют tts в которых по указанному settingsId не найден профиль настроек синтеза аудио
· Audio is empty — присутствуют элементы в которых оба tts и id имеют значение null
Too many paramsВ params передано более 10 параметров
Wrong parameter keyВ params передан ключ, который не является числом из диапазона от 1 до 10

Получение информации про номер обзвона
Сopied

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

{ 
  "id": 1307, // ID целевого обзвона
  "action": "GET_NUMBER", 
  "number": "380971234567" // Номер телефона
}

Пример ответа в случае успеха:

{
    "id": 110232, // ID номера обзвона
    "taskId": 18700, // ID обзвона
    "phone": "380441234567", // Номер телефона
    "state": "ANSWER", // Статус последнего звонка обзвона по этому номеру
    "stateDateTime": "2020-09-10 05:47:15" // Дата завершения последнего звонка обзвона по этому номеру
    "calledCount": 0, // Количество звонков на этот номер с последнего запуска обзвона
    "realCalledCount": 0, // Количество звонков на этот номер в обзвоне
    "highPriority": false, // Указывает находиться ли номер в приоритетной очереди
    "name": null, // Имя закрепленное за номером в обзвоне
    "note": "9049", // Заметка закрепленная за номером в обзвоне
    "link": "https://...", // Данные для Web Dialer закрепленные за номером в обзвоне
    "params": { // Параметры закрепленные за номером в обзвоне
        "1": "sample_value", // Номер параметра (1-10): Значение параметра
        ...
    },
    "audios": [ // Аудио закрепленные за номером в обзвоне
        {
            "id": 46644 // ID аудиозаписи
        },
        {
            "tts": { // Параметры синтеза речи
                "text": "sample_text",
                "settingsId": 107
            }
        }
    ]
}

Возможные ошибки:

Task not foundОбзвон не найден по указанному id
Wrong phone numberНомер телефона некорректный
Call not foundНомер не найден в обзвоне

Получение информации про все номера обзвона
Сopied

Для получения информации про все номера обзвона необходимо указать id целевого обзвона. Количество записей, которые будут получены при этом не превышает значение параметра limit. По умолчанию limit равен 1000, максимальное значение — 5000. Для получения следующей группы записей, необходимо в параметре offest указать сдвиг относительно начала списка. Кроме того, записи можно предварительно отфильтровать по целевым статусам номеров, перечень которых приведен в соответствующем словаре.

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

{
  "id": 1307, // ID целевого обзвона
  "action": "GET_NUMBERS",
  "limit": 2000, // Максимальное количество номеров, которые будут возвращены в ответе
  "offset": 4000, // Сдвиг возвращаемых записей относительно начала списка
  "callStates": [ // Фильтр по callState. Может быть null или пустой
    "NOANSWER",
    ...
  ]
}

Пример ответа в случае успеха:

[ // Массив номеров обзвона с дополнительной информацией
  {
    "id": 110232, // ID номера обзвона
    "taskId": 18700, // ID обзвона
    "phone": "380441234567", // Номер телефона
    "state": "ANSWER", // Статус последнего звонка обзвона по этому номеру
    "stateDateTime": "2020-09-10 05:47:15" // Дата завершения последнего звонка обзвона по этому номеру
    "calledCount": 0, // Количество звонков на этот номер с последнего запуска обзвона
    "realCalledCount": 0, // Количество звонков на этот номер в обзвоне
    "highPriority": false, // Указывает находиться ли номер в приоритетной очереди
    "name": null, // Имя закрепленное за номером в обзвоне
    "note": "9049", // Заметка закрепленная за номером в обзвоне
    "link": "https://...", // Данные для Web Dialer закрепленные за номером в обзвоне
    "params": { // Параметры закрепленные за номером в обзвоне
      "1": "sample_value", // ID: Значение параметра
      ...
    },
    "audios": [ // Аудио закрепленные за номером в обзвоне
      {
        "id": 46644 // ID аудиозаписи
      },
      {
        "tts": { // Параметры синтеза речи
          "text": "sample_text",
          "settingsId": 107
        }
      }
    ]
  },
  ...
]

Возможные ошибки:

Task not foundОбзвон не найден по указанному id
Limit range is 1-5000Значение limit не в диапазоне от 1 до 5000
Offset cannot be negativeЗначение offset должно быть положительным

Получение информации про звонки обзвона
Сopied

Для получения информации про звонки обзвона необходимо, кроме действия, указать параметр callHistoryRequest. callHistoryRequest не может быть null, но может быть пустым. Записи возвращаются в порядке убывания id.

Количество записей, которые будут получены при этом не превышает значение параметра limit. По умолчанию limit равен 50, максимальное значение — 1000. Для получения следующей группы записей можно воспользоваться одним из двух способов:
· В параметре offest указать сдвиг относительно начала списка;
· В параметре maxId указать максимальный (включительно) id записи, которая будет возвращена.

Записи звонков можно предварительно отфильтровать параметрами:
· dateFrom — минимальная дата и время звонка (включительно) в формате “yyyy-MM-dd HH:mm:ss”;
· dateTo — максимальная дата и время звонка (невключительно) в формате “yyyy-MM-dd HH:mm:ss”.

Кроме того, записи можно предварительно отфильтровать в параметре filter по:
· states — массив статусов звонков обзвонов. Перечень приведен в соответствующем словаре;
· taskIds — массив id обзвонов;
· phone — часть номера абонента. Все сторонние символы будут предварительно удалены;
· operatorNumber — точный номер оператора. Все сторонние символы будут предварительно удалены;
· name — часть имени, закрепленного за номером обзвона на момент звонка;
· note — часть заметки, закрепленной за номером обзвона на момент звонка;
· link — часть данных для Web Dialer, закрепленных за номером обзвона на момент звонка;
· param — часть любого из параметров, закрепленных за номером обзвона на момент звонка;
· voiceSecretaryIds — массив id голосовых секретарей, которые были использованы в звонке;
· voiceSecretaryEndReasons — массив причин завершения голосового секретаря, который был использован в звонке. Перечень приведен в соответствующем словаре;
· voiceSecretaryEndNodeTypes — массив типов конечного узла голосового секретаря, который был использован в звонке. Перечень приведен в соответствующем словаре.

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

{
  "action": "GET_CALLS_HISTORY",
  "callHistoryRequest": { // Обязательный параметр. Все внутренние параметры могут быть null
    "dateFrom": "2023-10-24 00:00:00", // Минимальная дата и время звонка
    "dateTo": "2023-10-25 00:00:00", // Максимальная дата и время звонка
    "offset": 0, // Сдвиг относительно начала выборки
    "limit": 50, // Максимальное количество звонков, которые будут возвращены в ответе
    "maxId": 150, // Максимальный идентификатор звонка
    "filter": { // Массив дополнительных фильтров. Все внутренние параметры могут быть null
      "states": [ // Массив целевых статусов звонков
        "ANSWER",
        ...
      ],
      "taskIds": [ // Массив идентификаторов целевых обзвонов
        "300",
        ...
      ],
      "phone": "38097", // Часть номеров
      "operatorNumber": "2045", // Номер линии целевого оператора
      "name": "part of name", // Часть имени
      "note": "part of note", // Часть заметки
      "link": "part of data for webdialer ", // Часть данных для WebDialer
      "param": "part of param", // Часть одного из параметров
      "voiceSecretaryIds": [ // Массив идентификаторов целевых голосовых секретарей
        "118",
        ...
      ],
      "voiceSecretaryEndNodeTypes": [ // Массив целевых типов конечных узлов голосового секретаря
        "END_SUCCESS",
        ...
      ],
      "voiceSecretaryEndReasons": [ // Массив целевых причин завершения голосового секретаря
        "NORMAL",
        ...
      ]
    }
  }
}

Пример ответа в случае успеха:

{
  "count": 140, // Количество соответствующих результатов
  "offset": 0, // Использованный сдвиг
  "limit": 50, // Использованный лимит
  "items": [ // Массив звонков обзвонов
    {
      "id": 158, // Идентификатор звонка
      "taskId": 300, // Идентификатор обзвона
      "phone": "380681234567", // Номер телефона
      "state": "ANSWER", // Статус завершения звонка
      "callEndTime": "2023-10-24 16:15:43", // Дата и время завершения звонка
      "operatorNumber": "2045", // Номер оператора. Может быть null
      "userId": 15, // Идентификатор оператора. Может быть null
      "calledCount": 1, // Количество дозвонов
      "realCalledCount": 2, // Всего дозвонов
      "seconds": 3, // Тарифицируемое время звонка. Может быть null
      "secondsClientWaitOperator": 5, // Время ожидания оператора. Может быть null
      "secondsOperatorWaitCall": 15, // Время ожидания звонка. Может быть null
      "secondsForOperatorAnswered": 2, // Время до ответа оператора. Может быть null
      "secondsTalk": 10, // Время разговора. Может быть null
      "rid": 1052434886, // Случайный идентификатор звонка
      "name": "some name", // Имя к номеру обзвона на момент звонка. Может быть null
      "note": "some note", // Заметка к номеру обзвона на момент звонка. Может быть null
      "link": "some data for web dialer", // Данные для WebDialer к номеру обзвона на момент звонка. Может быть null
      "params": { // Массив параметров к номеру на момент звонка. Может быть null
        "1": "param 1 value", // "Номер": "Значение"
        ...
      },
      "withdrawTotal": "0.65", // Суммарная стоимость звонка. Может быть null
      "withdrawByCategories": { // Массив списаний за звонок по категориям. Может быть null
        "SPEECH_RECOGNITION": "0.10", // Распознавание речи
        "TEXT_TO_SPEECH": "0.01", // Синтез речи
        "CALL": "0.50", // Совершение звонка
        "VOICE_SECRETARY": "0.02", // Голосовой секретарь
        "AUTODIALER": "0.02", // Доп. стоимость за обзвон
        "ANSWERING_MACHINE_DETECTION": "0.25" // Распознавание автоответчика
        "MESSAGE_SERVICE_MESSAGE": "1" // Отправка сообщений
      },
      "executedTriggerActionIds": [ // Массив идентификаторов выполненных по звонку обработчиков. Может быть null
        11,
        ...
      ],
      "sendFirstMessageToClientSuccess": true, // Признак успешности отправки первого сообщения по звонку
      "secretary": { // Массив данных о прохождении голосового секретаря. Может быть null
        "id": 118, // Идентификатор
        "duration": 3, // Длительность
        "endNodeType": "INTERMEDIATE", // Тип конечного узла
        "endReason": "USER_REJECT", // Причина завершения
        "endNodeId": 1, // Идентификатор конечного узла
        "endNodeTitle": "Action #1", // Название конечного узла
        "endVoiceSecretaryId": 118, // Идентификатор секретаря завершения (может отличаться, если завершение произошло в фоновом)
        "steps": [ // Массив информации о шагах секретаря
          {
            "nodeId": 1, // Идентификатор узла
            "actionTitle": "Action #1", // Название узла
            "recognizedText": "Some text", // Распознанный текст. Может быть null
            "recognizedDates": [ // Массив распознанных дат. Может быть null
              "2023-10-24",
              ...
            ],
            "alternativeAudioIndex": "1", // Индекс альтернативного аудио, которое прослушал абонент. Может быть null
            "jumpToNode": false, // Признак перехода на узел действием "Перейти на другой узел"
            "startBackgroundSecretaryId": null, // Идентификатор секретаря на который был произведен переход. Может быть null
            "endBackgroundSecretaryId": null // Идентификатор фонового секретаря из которого вышли. Может быть null
          },
          ...
        ]
      }
    },
    ...
  ]
}

Возможные ошибки:

Limit range is 1-5000Значение limit не в диапазоне от 1 до 5000
Offset is less than 0Значение offset должно быть положительным
callHistoryRequest is nullНе указан параметр callHistoryRequest
Invalid date fromНекорректная дата и время «от» в фильтрах
Invalid date toНекорректная дата и время «до» в фильтрах

Удаление номеров
Сopied

Действие «Удалить номера» позволяет удалить номера из обзвона двумя способами: указав номера или статусы номеров на удаление. Перечень необходимых номеров указывается в параметре запроса numbers и может содержать максимум 10 000 номеров. Номера необходимо указывать в международном формате, все сторонние символы будут предварительно удалены. Статусы номеров указываются в параметре запроса callStates и приведены в соответствующем словаре. В запросе должно присутствовать одно из полей callStates и numbers, в случае когда указаны оба — используется numbers.

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

{
   "action": "REMOVE_NUMBERS",
   "id": 1307,  // ID целевого обзвона
   "callStates": [ // Массив статусов номера в которых будут удалены
       "NOANSWER", 
       ...
   ],
   "numbers": [ // Массив номеров которые будут удалены
       "380970000001", 
       ...
   ]
}

Пример ответа в случае успеха:

{
    "status": "Success",
    "data": [ // Массив некорректных номеров
        "389833883838383838383838",
        ...
    ]
}

В случае успешного удаления хотя бы одного номера с использованием массива numbers ответ будет содержать массив некорректных номеров в поле data.
Возможные ошибки:

Task not foundОбзвон не найден по указанному id
numbers and states is nullОба поля numbers и callStates null или пустые
Too many numbersВ массиве numbers передано более 10 000 номеров
Phones not foundnumbers не содержит ни одного номера
Numbers not foundНи один из номеров массива numbers не найден в обзвоне
Numbers not found by statesПо статусам из массива callStates не найдено ни одного номера в обзвоне
Handler is busy, try again laterОдин проект одновременно может удалять или добавлять номера только в одном обзвоне.
В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров.
Повторите попытку позже, когда предыдущая операция завершится

Удаление всех номеров
Сopied

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

{
  "action": "REMOVE_ALL_NUMBERS",
  "id": 1307 // ID целевого обзвона
}

Ответ в случае успеха:

{"status": "Success", "message": "Removed"}

Возможные ошибки:

Task not foundОбзвон не найден по указанному id
Numbers not foundВ указанном обзвоне отсутствуют номера
Handler is busy, try again laterОдин проект одновременно может удалять или добавлять номера только в одном обзвоне.
В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров.
Повторите попытку позже, когда предыдущая операция завершится

Словари
Сopied

autodialerType
Сopied

Типы обзвонов:

AUTODIALАвтообзвон. Используется преимущественно для информирования клиентов или проведения опросов. Звонки автообзвонов проходят в соответствии с указанным входящим сценарием
GUARANTEED_DIALГарантированный дозвон. Используется преимущественно для оптимизации рабочего времени операторов. Звонки гарантированных дозвонов распределяются напрямую на операторов указанной группы внутренних линий
VOICE_ROBOTГолосовой робот. Используется преимущественно для информирования клиентов или проведения опросов. При звонках голосовых роботов воспроизводиться указанный голосовой секретарь

autodialerMode
Сopied

Режимы обзвонов:

FIXEDПо количеству потоков
FREEПо свободным операторам
SMARTУмный подбор

taskStatus
Сopied

Статусы обзвонов:

NO_NUMBERSНомера не добавлены
IN_PROGRESSВ процессе обзвона
WAITINGВ ожидании начала обзвона
WAITING_OPERATORSОжидание свободных операторов
WAITING_REPEATОжидание срабатывания настройки «Повторный звонок»
PAUSEDНа паузе
CANCELEDОтменен, но еще не успел завершиться (часть номеров обзвона находятся в статусе DIALING)
FINISHEDЗавершен

audioSynthesisDynamicValues
Сopied

Динамические значения для синтеза аудио:

NAНомер обзвона: имя
NOНомер обзвона: заметка
LIНомер обзвона: данные для Web Dialer
P1Номер обзвона: параметр #1
P2Номер обзвона: параметр #2
P3Номер обзвона: параметр #3
P4Номер обзвона: параметр #4
P5Номер обзвона: параметр #5
P6Номер обзвона: параметр #6
P7Номер обзвона: параметр #7
P8Номер обзвона: параметр #8
P9Номер обзвона: параметр #9
P10Номер обзвона: параметр #10

callState
Сopied

Состояния номера обзвона:

СтатусНазвание статусаДоступен для автоматического повторного прозвона (поле repeatCallStates)Доступен для метода REFRESHСвидетельствует о возможных проблемах в настройках обзвона или телефонииЯвляется статусом звонка
NEWНе обработано
DIALINGВ процессе обзвона
ANSWERОтвечено абонентом и оператором++
ANSW_RJCTОтвечено абонентом и не было звонка операторам+++
NOANSWERНе отвечено+++
BUSYЗанято или сброс+++
FAILСбой соединения+++
BLOCKEDЗаблокирован+
TALKINGАвтоответчик: абонент разговаривает+++
UNREACHABLEАвтоответчик: абонент недоступен+++
NOT_EXISTАвтоответчик: номер не существует+++
VOICE_MAILАвтоответчик: голосовая почта+++
CLIENT_CALLEDАбонент позвонил сам или был исходящий+
CANCELОтменено+
ANSW_NF_OPОтвечено абонентом и не было свободных операторов++++
ANSW_OP_NAОтвечено абонентом и операторы не приняли звонок++++
BUSYOUTНедостаточно линий++++
AUDIO_ERRОшибка аудио+++
WRONG_DIRНеверное направление+++
AUTOCANCELОтменено автоматически++

triggerActionEvent
Сopied

События обзвонов и звонков обзвонов:

AUTODIAL_ANSWERЗвонок завершен — отвечено абонентом и оператором
AUTODIAL_ANSW_RJCTЗвонок завершен — отвечено абонентом и не было звонка операторам
AUTODIAL_ANSW_NF_OPЗвонок завершен — отвечено абонентом и не было свободных операторов
AUTODIAL_ANSW_OP_NAЗвонок завершен — отвечено абонентом и операторы не приняли звонок
AUTODIAL_NOANSWERЗвонок завершен — не отвечено
AUTODIAL_BUSYЗвонок завершен — занято или сброс
AUTODIAL_CALL_FAILЗвонок завершен — сбой соединения
AUTODIAL_TALKINGЗвонок завершен — абонент разговаривает
AUTODIAL_UNREACHABLEЗвонок завершен — вне зоны или отключён
AUTODIAL_NOT_EXISTЗвонок завершен — номер не существует
AUTODIAL_BUSYOUTЗвонок завершен — недостаточно линий
AUTODIAL_WRONG_DIRЗвонок завершен — неверное направление
AUTODIAL_AUDIO_ERRЗвонок завершен — ошибка аудио
AUTODIAL_NUMBER_BLOCKEDНомер заблокирован настройками проекта
AUTODIAL_REPEAT_ATTEMPTS_ENDEDЗвонок завершен неуспешно и закончились попытки повторного прозвона
AUTODIAL_CLIENT_CALLEDАбонент позвонил сам или был исходящий
AUTODIAL_USER_PAUSEDПользователь поставлен на паузу обзвоном. Доступно только для гарантированного дозвона
AUTODIAL_STATUS_CHANGEDСтатус обзвона изменён
AUTODIAL_CANCELОбзвон отменен
AUTODIAL_AUTOCANCELОбзвон отменен автоматически
AUTODIAL_FINISHОбзвон завершен

voiceSecretaryEndNodeTypes
Сopied

Типы конечных узлов голосовых секретарей:

INTERMEDIATEПромежуточный
END_SUCCESSУспешный
END_FAILНеуспешный
BACKGROUNDФоновый
BACKGROUND_DEFERФоновый — перенос звонка

voiceSecretaryEndReasons
Сopied

Причины завершения голосовых секретарей:

NORMALЗакончился нормально
USER_REJECTАбонент завершил разговор
GREETING_SILENCEАбонент молчал во время приветствия
ANSWERING_MACHINEРаспознан автоответчик
RECOGNITION_ERRORРаспознавание речи прервалось по техническим причинам
JUMP_LIMITПревышен лимит выполненных действий «Перейти на другой узел»
NODE_LIMITПревышен лимит пересеченных узлов
FAILНеизвестная ошибка

Управление звонками
Сopied

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

Прямой вызов SIP -> GSM
Сopied

Для инициации звонка с внутренней линии необходимо указать номер внутренней линии в параметре sip и мобильный номер, на который необходимо совершить звонок, в международном формате в параметре number. Этот метод позволяет инициировать звонок без ввода номера оператором и широко применяется в интеграционных целях.

Относительный путь: /phones/directCall
Режим: POST
Content-Type: application/x-www-form-urlencoded (Также можно отправлять запрос передавая параметры в качестве параметров url, без тела)

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

/phones/directCall?sip=2023&number=380123456789&meta=sample.id.0001

Ответ в случае успеха:

{"status": "Success","message": "Called"}

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

Возможные ошибки:

Sip not foundУказанная линия не найдена в проекте
Sip not readyУказанная линия не может принять звонок
Wrong phoneНомер клиента указан некорректно
Meta info is too bigmeta больше 1000 символов

Информирующий звонок
Сopied

Для инициации информирующего звонка, который будет исполнен без участия оператора, необходимо указать мобильный номер, на который необходимо совершить звонок, в международном формате в параметре number. Опционально в параметре outerLine может быть указана внешняя линия в международном формате с которой будет совершен звонок, в противном случае будет использован текущий исходящий сценарий. Кроме того, запрос должен содержать как минимум один из параметров, указывающих что будет воспроизведено клиенту при ответе на звонок:

audios — Массив, который используется для указания аудио. Аудио воспроизводиться до голосового меню и секретаря. Каждый элемент массива представляет собой:
· id — Загруженное аудио в проекте из раздела «API звонки», которые можно загрузить на странице личного кабинета «Аудио файлы»;
· tts — Синтезированное аудио;
В каждом элементе audios должен присутствовать один из параметров id и tts если указаны оба будет использован id. Порядок расположения аудио в массиве соответствует порядку воспроизведения, максимум элементов — 5 (из которых 2 синтеза аудио).
В элементе tts должен присутствовать параметр settingsId один из параметров text и ssml. Если указаны оба text и ssml будет использован ssml, максимальное количество символов — 2500. Параметр ssml должен начинаться и заканчиваться тегом speak. Процесс озвучивания происходит перед стартом звонка. Синтезированные аудио хранятся до 7 дней по завершению звонка, не более 3 месяцев с момента создания и в списке аудиозаписей проекта не отображаются. В случае, если синтезированный текст и профиль настроек совпадают — используется ранее синтезированное аудио.

ivrIdid голосовое меню. В голосовом меню разрешаются только действия:
· Перевод звонка на внутреннюю линию;
· Перевод звонка на группу номеров (SIP);
· Воспроизведение голосового сообщения.

voiceSecretaryIdid голосового секретаря. В голосовом секретаре не разрешаются действия:
· Перевод звонка на GSM номер;
· Активация сценария;
· Активация голосового меню;
· Перевод звонка на отдел (GSM).

Относительный путь: /calls/originateNew
Режим: POST
Content-Type: application/json
Пример JSON запроса:

{
  "phone": "380123456789", // Номер клиента  
  "outerLine": "380441234567", // Внешняя линия 
  "audios": [ // Массив аудиозаписей и синтеза аудио, которые будут проиграны при звонке на номер
    {
      "id": 1234 // ID целевой аудиозаписи
    },
    {
      "tts": { // Данные для синтеза аудио
        "text": "sample_text", // Текст который будет озвучен
        "ssml": "<speak>sample_text</speak>",  // Текст который будет озвучен в формате ssml
        "settingsId": 18 // ID профиля настройки синтеза аудио
      }
    },
    ...
  ],
  "ivrId": 123, // id голосового меню
  "voiceSecretaryId": 123, // id голосового секретаря
  "meta": "sample.id.0001"
}

Ответ в случае успеха:

{"status": "Success"}

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

Возможные ошибки:

Call already in progressПредыдущий звонок этому абоненту еще не завершился
Outer line not foundУказанная внешняя линия не найдена в проекте
Outer line is trackedУказанная внешняя линия участвует в трекинге. С неё нельзя совершать исходящие
No audio and IVRНе указаны ни один из параметров audiosivrId и voiceSecretaryId
IVR can be used for SIPs onlyВ указанном голосовом меню присутствуют неразрешенные действия
Service not paidОшибка оплаты. Возможные причины:
· Тариф проекта не активен
· На счету проекта нет средств
· В тарифе проекта нет API звонков
Limit of Simultaneously calls has reachedДостигнут предел в 20 одновременных звонков
audiosОшибка указания массива audios. Возможные причины ошибки:
· Too many audios — слишком много элементов
· Too many text to speech — слишком много элементов с синтезом аудио
· Audio is null — присутствуют элементы со значением null
· Audio not found by id — присутствуют id по которым не найдена аудиозапись
· Wrong type of audio — присутствуют id который указывает аудиозапись недопустимого раздела
· Text to speech ‘text’ and ‘ssml’ is null — присутствуют tts в которых оба text и ssml пустые
· Text to speech ‘text’ not valid — присутствуют tts в которых text превышает 2500 символов
· Text to speech ‘ssml’ not valid — присутствуют tts в которых ssml превышает 2500 символов или не начинается и заканчивается тегом speak
· Text to speech settings not found by id — присутствуют tts в которых по указанному settingsId не найден профиль настроек синтеза аудио
· Audio is empty — присутствуют элементы в которых оба tts и id имеют значение null
· Text to speech failed — ошибка при синтезе аудио из текста
Wrong phoneНомер клиента указан некорректно
Meta info is too bigmeta больше 1000 символов

Независимый Сlick to call
Сopied

Для инициации звонка, аналогичного по принципу работы с Click to call без необходимости предварительного создания сайта и добавления кнопки обратного звонка, необходимо указать номер клиента в международном формате в параметре clientNumber и массив шагов переадресаций звонка на операторов в параметре steps.

Относительный путь: /calls/originateC2c
Метод: POST
Content-Type: application/json

Метод применяется, когда информация о необходимости обратного звонка, номерах клиента и операторов содержится/создается в сторонней системе. Такие звонки не будут видны в заявках и CRM системах, но будут в истории звонков и вебхуках.

Каждый элемент массива шагов переадресаций должен содержать следующие обязательные параметры:
· type — Тип переадресации. Доступные значения: GSM (Мобильный номер), SIP (Внутренняя линия) и GROUP (Группа внутренних линий);
· to — Номер оператора. Зависит от указанного в параметре type типа переадресации: GSM — Номер в международном формате, SIP — номер внутренней линии, GROUPid группы внутренних линий;
· awaitingTime — Количество времени на одну переадресацию в секундах. Доступные значения: от 5 до 300.

Порядок расположения шагов в массиве соответствует порядку переадресаций.

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

{
  "clientNumber": "380123456789", // Номер клиента
  "steps": [ // Массив шагов переадресаций
    {
      "type": "GSM", // Тип переадресации
      "to": "380987654321", // Номер оператора
      "awaitingTime": 20 // Время на шаг
    },
    {
      "type": "SIP",
      "to": "2023", // Номер внутренней линии
      "awaitingTime": 20
    },
    {
      "type": "GROUP",
      "to": "123", // Номер группы внутренних линий
      "awaitingTime": 60
    },
    ...
  ],
  "meta": "sample.id.0001"
}

Ответ в случае успеха:

{"status": "Success", "message": "Called"}

Возможные ошибки:

Call to XXXXXXXXX is already in progressЗвонок клиенту уже в процессе
Steps is emptyНе указаны шаги переадресации в steps 
Wrong client numberclientNumber указан не в международном формате
Client number blocked in project settingsclientNumber заблокирован в настройках проекта
To number incorrectНомер не является ни внутренней линией, ни мобильным номером
Step type not setТип распределения не указан в поле type
Group id is incorrectГруппа, указанная в to не найдена
Meta info is too bigmeta больше 1000 символов

Сброс звонка
Сopied

Для сброса активного звонка необходимо указать как минимум один из обязательных параметров:
· id — Уникальный идентификатор звонка. Может быть получен из истории или в вебхуках;
· number — Номер внутренней или внешней линии. Будут сброшены все найденные звонки с участием указанного номера.

Относительный путь: /calls/hangup
Режим: POST
Content-Type: application/json

Примеры JSON запросов:

{
  "number": 380123456789
}
{
  "id": 1234567890
}

Пример ответа в случае успеха:

{"status": "Success","message": "Found: 1"}

Возможные ошибки:

Empty requestНе указан ни id, ни number

Вызов суфлера
Сopied

Для инициации подключения суфлера необходимо указать два обязательных параметра:
· target — Номер внутренней линии в звонке, к которой будет подключен суфлер;
· source — Номер внутренней линии, которая будет подключена суфлером к активному звонку.

Относительный путь: /calls/connectAsPrompter
Режим: POST
Content-Type: application/json

Права на вызов суфлера пользователями соответствующих внутренних линий не учитываются при выполнении запроса

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

{
  "target":"1111",
  "source":"2222"
}

Ответ в случае успеха:

{"status": "Success"}

Возможные ошибки:

Target not foundЦелевая линия не найдена в проекте
Target is not in callЦелевая линия не находиться в звонке
Source not foundЛиния суфлера не найдена
Source is offlineЛиния суфлера не в сети

Речевая аналитика
Сopied

Для активации речевой аналитики по звонку необходимо указать два обязательных параметра:
· callId — Идентификатор звонка. Может быть получен по API из истории звонков или в вебхуках по звонкам;
· profileId — Идентификатор профиля аналитики. Может быть получен на странице личного кабинета «Речевая аналитика» в шапке целевого профиля.

Относительный путь: /calls/analytics/create
Режим: POST
Content-Type: application/json

Запуск аналитики возможен только по тем звонкам, для которых были сохранены раздельные записи.
Ответ на запрос будет отправлен после окончания обработки звонка, следовательно рекомендуется значительно повысить время ожидания ответа для запросов к данному методу.
Максимально одновременных звонков в обработке — 50.

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

{
  "callId":"12345678",
  "profileId":"123"
}

Пример ответа в случае успеха:

{
  "profileId": 123, // Идентификатор использованного профиля речевой аналитики
  "profileName": "Sample Name", // Название использованного профиля речевой аналитики
  "operatorTag": "Operator", // Действующее лицо, которое считается оператором
  "plainTranscription": "Operator: Hello! This is sample speech", // Транскрипция диалога
  "transcription": "00:00:00,000-->00:00:15,000\nOperator: Hello! This is sample speech", // Экранированная транскрипция диалога
  "sentimentAnalysis": "The dialogue consisted only of a greeting from the operator. The operator looks cheerful and interested in communication, the client’s mood is unknown", // Описание настроения диалога
  "operatorSentimentAnalysis": "The operator looks cheerful and interested in communication", // Описание настроения оператора
  "clientSentimentAnalysis": "The client’s mood is unknown", // Описание настроения клиента
  "dialogTopic": "None", // Тема диалога
  "summarizedPoints": [ // Массив ключевых моментов диалога
    "The dialogue consisted only of a greeting from the operator", // Один из ключевых моментов диалога
    ...
  ],
  "keywords": [ // Массив ключевых слов диалога
    "Hello", // Одно из ключевых слов диалога
    ...
  ],
  "dialogQualityScore": 70, // Общая оценка диалога от 0 до 100
  "operatorProfessionalismScore": 9.5, // Оценка профессионализма оператора от 0 до 10
  "communicationClarity": 8.0, // Оценка четкости коммуникации оператора от 0 до 10
  "problemIdentification": 8.5, // Оценка качества определения проблемы оператором от 0 до 10
  "issueResolutionEfficiency": 8.0, // Оценка эффективности решения проблемы оператором от 0 до 10
  "empathyLevel": 7.5, // Оценка уровня эмпатии оператора от 0 до 10
  "engagementLevel": 8.0, // Оценка вовлеченности оператора от 0 до 10
  "adaptability": 7.5, // Оценка способности адаптироваться оператора от 0 до 10
  "personalizationInteraction": 8.0, // Оценка персонализации подхода оператором от 0 до 10
  "overallSatisfactionRating": 8.5, // Оценка удовлетворенности клиента от 0 до 10
  "obsceneWords": [], // Массив использованной нецензурной лексики
  "fillerWords": [], // Массив использованных слов-паразитов
  "furtherSteps": "Contact again later", // Предложения по дальнейшим шагам в коммуникации
  "operatorMistakes": "None", // Ошибки оператора
  "needsAttention": false, // Признак необходимости обратить внимание на звонок
  "stopWords": [ // Массив стоп-слов
    {
      "sourcePhrase": "We can't", // Стоп-слово
      "translatedPhrase": "We can't", // Перевод стоп-слова на язык аналитики
      "said": false // Признак присутствия стоп-слова в диалоге
    },
    ...
  ],
  "requiredPhrases": [ // Массив обязательных слов
    {
      "sourcePhrase": "Hello", // Обязательное слово
      "translatedPhrase": "Hello", // Перевод обязательного слова на язык аналитики
      "said": false // Признак присутствия обязательного слова в диалоге
    }
  ]
}

Параметр ответа transcription содержит строки транскрипции диалога в формате:
· *Время начала промежутка реплики*—>*Время окончания промежутка реплики* — Например «00:00:00,000—>00:00:15,000»;
· *Действующее лицо*: *Транскрипция реплики* — Например «Operator: Hello! This is sample speech»;
· Следующая реплика в аналогичном форматировании;
· Временные промежутки и транскрипции реплик разделены между собой управляющими символами переноса строки («\n»);
· В параметре transcription в отличии от plainTranscription управляющие символы экранированы («\\n»), кроме того plainTranscription не содержит временных промежутков реплик.

Возможные ошибки:

Only 50 concurrent requests are allowedПревышен лимит одновременно обрабатываемых звонков
Call does not existПо указанному callId не найден звонок
Profile does not existПо указанному profileId не найден профиль речевой аналитики
Analytics is not available for this callФормирование речевой аналитики невозможно, т.к. для указанного звонка отсутствуют разделённые записи
Voice analytics is already in progressОбработка речевой аналитики по указанному звонку уже запущена
Voice analytics is not availableУслуга речевой аналитики недоступна
Insufficient fundsНа балансе проекта недостаточно средств

Аудио
Сopied

Добавление аудио файлов в проект
Сopied

Для добавления аудио в проект в multipart запросе необходимо указать следующие параметры:
· name (String) — Название аудио файла, который будет добавлен. Должно быть уникальным в рамках одного раздела. Максимум 200 символов;
· type (String) — Указатель раздела, в который будет добавлен аудио файл. Доступные значения: GENERAL (Сценарии), IVR (Голосовые меню), MELODY (Мелодии ожидания на линии и очередей), AUTODIAL (Автообзвоны), VOICE_SECRETARY (Голосовые секретари), VOICE_QUEUE (Очереди звонков с голосовым сопровождением) и API (API звонки);
· file (File) — Аудио или видео файл любого формата. Максимальный размер — 15 мб. Дорожка аудио из файла будет конвертирована и нормализирована. Максимальная длительность итогового аудио будет обрезана в соответствии с типом: IVR — до 90 сек., AUTODIAL, MELODY и API — до 300 сек., GENERAL — до 30 сек.

Относительный путь: /audio/upload
Режим: POST
Content-Type: multipart/form-data

Опционально к запросу можно добавить параметр temp (Boolean), значение true которого будет указывать на необходимость отметить файл как временный и удалить в 04:00.

Пример ответа в случае успеха:

{"status": "Success","message": "123"}

Параметр ответа message будет содержать id добавленного аудио файла.

Синтез аудио
Сopied

Для добавления в проект синтезированных аудио необходимо указать массив данных для синтеза в параметре data. Максимальная длинна массива — 5 элементов. Каждый элемент должен содержать следующие параметры:
· name — Название аудио файла, который будет добавлен. Должно быть уникальным в рамках одного раздела. Максимум 200 символов;
· type — Указатель раздела, в который будет добавлен аудио файл. Доступные значения: GENERAL (Сценарии), IVR (Голосовые меню), MELODY (Мелодии ожидания на линии и очередей), AUTODIAL (Автообзвоны), VOICE_SECRETARY (Голосовые секретари), VOICE_QUEUE (Очереди звонков с голосовым сопровождением) и API (API звонки);
· tts — Данные для синтеза аудио. В элементе tts должен присутствовать параметр settingsId один из параметров text и ssml. Если указаны оба text и ssml будет использован ssml, максимальное количество символов — 2500. Параметр ssml должен начинаться и заканчиваться тегом speak.

Относительный путь: /audio/tts
Режим: POST
Content-Type: application/json

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

{
  "data": [ // Массив данных для синтеза аудио
    {
      "name": "sample_name", // Название с которым аудио будет добавлено в проект
      "type": "AUTODIAL", // Раздел аудио в который будет добавлена аудиозапись
      "tts": { // Данные для синтеза аудио
        "text": "sample_text", // Текст который будет озвучен
        "ssml": "<speak>sample_text</speak>",  // Текст который будет озвучен в формате ssml
        "settingsId": 18 // ID профиля настройки синтеза аудио
      }
    },
    ...
  ]
}

Пример ответа:

{
  "status": "Success",
  "message": "Success",
  "data": [ // Массив результатов синтеза 
    { // Пример успешного синтеза (присутствует id, error - null)
      "name": "sample_name", // Название аудио
      "id": 4962 // id с которым аудио было добавлено в проект
    },
    { // Пример неудачного синтеза (присутствует error, id - null)
      "name": "sample_name",
      "error": "Same name already present"
    }
  ]
}

Возможные ошибки синтеза отдельных аудио (error):

type is nullНе указан раздел добавляемого аудио
name is emptyНазвание добавляемого аудио не указано или пустое
name length more than 200 charsДлина названия добавляемого аудио превышает 200 символов
Same name already presentАудио с таким именем уже присутствует в указанном разделе
tts is nullПараметр tts не указан
Text to speech ‘text’ and ‘ssml’ is nullВ tts не указано ни text, ни ssml
Text to speech ‘text’ not validПараметр text превышает 2500 символов
Text to speech ‘ssml’ not validПараметр ssml превышает 2500 символов или не начинается и заканчивается тегом speak
Text to speech ‘settingsId’ is nullВ tts не указан профиль настроек синтеза аудио в параметре settingsId
Text to speech settings not found by idВ tts по указанному settingsId не найден профиль настроек синтеза аудио
Text to speech failedОшибка при синтезе аудио из текста

Возможные ошибки:

Allowed only one simultaneous text to speech request per projectОдин и тот же проект не может вызывать этот метод одновременно несколько раз. Подождите пока завершится предыдущий запрос.
data is nullВ запросе отсутствует параметр data
data is emptyВ параметре data нет элементов
Too many elements in dataКоличество элементов в параметре data превышает 5
Service not paidОшибка оплаты. Возможные причины:
· Тариф проекта не активен
· На счету проекта нет средств

Списки
Сopied

Работа с списками осуществляется с помощью действий, метод:

Относительный путь: /lists
Режим: POST
Content-Type: application/json

Целевой список указывается в теле запроса в обязательном параметре list. Перечень существующих списков:
· BLOCKED_PHONES — Список заблокированных номеров в международном формате, взаимодействие с которыми отклоняется;
· BLOCKED_FOR_AUTODIAL_PHONES — Список номеров в международном формате, которые нельзя добавить в обзвоны.
Действия указываются в теле запроса в обязательном параметре operation. Перечень существующих действий:
· GET — Получение текущего списка;
· ADD — Добавление элементов в список;
· REMOVE — Удаление элементов из списка.
Для действий ADD и REMOVE обязательно указание массива элементов которые будут добавлены или удалены в параметре items. Максимальное количество элементов в массиве items — 100.

Заблокированные номера
Сopied

Список заблокированных номеров в международном формате, взаимодействие с которыми отклоняется. Для работы с списком заблокированных номеров в обязательном параметре list необходимо указать «BLOCKED_PHONES». Для действий ADD и REMOVE параметр items должен представлять собой массив номеров в международном формате.

Пример JSON GET запроса:

{
  "list": "BLOCKED_PHONES"
  "operation": "GET"
}

Пример ответа:

["380123456789", ...]

Пример JSON ADD запроса:

{
  "list": "BLOCKED_PHONES",
  "operation": "ADD",
  "items": ["380123456789", ...]
}

Пример JSON REMOVE запроса:

{
  "list": "BLOCKED_PHONES",
  "operation": "REMOVE",
  "items": ["380123456789", ...]
}

Ответ для ADD и REMOVE запросов:

{"status": "Success"}

Исключенные из обзвонов номера
Сopied

Список номеров в международном формате, которые нельзя добавить в обзвоны. Для работы с списком номеров, которые нельзя добавить в обзвоны, в обязательном параметре list необходимо указать «BLOCKED_FOR_AUTODIAL_PHONES». Для действий ADD и REMOVE параметр items должен представлять собой массив номеров в международном формате.

Пример JSON GET запроса:

{
  "list": "BLOCKED_FOR_AUTODIAL_PHONES",
  "operation": "GET"
}

Пример ответа:

["380123456789", ...]

Пример JSON ADD запроса:

{
  "list": "BLOCKED_FOR_AUTODIAL_PHONES",
  "operation": "ADD",
  "items": ["380123456789", ...]
}

Пример JSON REMOVE запроса:

{
  "list": "BLOCKED_FOR_AUTODIAL_PHONES",
  "operation": "REMOVE",
  "items": ["380123456789", ...]
}

Ответ для ADD и REMOVE запросов:

{"status": "Success"}

Пользователи
Сopied

Список
Сopied

POST  /users/list

Возвращает список пользователей.

[
    {
        "email": "example@gmail.com",
        "firstName": "Александр",
        "lastName": "Александрович",
        "middleName": "Александров",
        "phone": "380501234567",
        "role": "ADMIN",
        "id": 12579,
        "workStatus": "WORK"
    },
    {
        "email": "example@unitalk.cloud",
        "firstName": "Владимир",
        "lastName": "Владимирович",
        "middleName": "null",
        "phone": "380935551133",
        "role": "OWNER",
        "id": 5701,
        "workStatus": "WORK"
    }
]
API references

Данные о пользователях
Сopied

/users/getStatus
Выдаёт список всех пользователей с указанием их внутренней или мобильной линии и состоянием работы.

[
    {
        "firstName": "Василий",
        "middleName": "Александрович",
        "lastName": "Иванов",
        "phone": "4035",
        "workStatus": "WORK"
    }
]

workStatus  может быть:
WORK (работает),
PAUS (на паузе),
STOP (работа окончена/еще не начал работать)

у пользователей без расширенного функционала, workStatus всегда WORK

API references

Изменение состояния работы
Сopied

/phones/inner/setStatus
Режим: POST
Передавать параметры
number — номер линии оператора
status — новое состояние (WORK, PAUS, STOP)
Пример: /phones/inner/setStatus?number=9999&status=WORK

В случае успеха ответ:

{"status": "Success", "message": "Success"}
API references

Внутренние линии
Сopied

Для получения списка внутренних линий и текущего их статуса необходимо отправить пустой запрос. В ответе будет возвращен ассоциативный массив, где ключ — номер внутренней линии, а значение — её текущий статус. Возможные статусы: online (линия в сети и не занята), busy (линия в сети и занята звонком) и offline (линия не в сети).

Относительный путь: /phones/inner
Режим: POST
Content-Type: —

Пример ответа:

{
  "2022": "offline"
  "2023": "busy",
  "2024": "online",
  ... 
}

Отделы
Сopied

Получение групп
Сopied

POST /groups/action
Пример body JSON запроса:

{
  "action": "GET"
}

Ответ:

{ 
  "status": "Success", 
  "data": [ 
    { 
      "id": 455, // id группы 
      "name": "Отдел продаж", // имя группы 
      "phones": [ // массив номеров которые содержит группа      
        { 
          "number": "4030",  // номер   
          "firstName": "Александр", // имя пользователя, если он есть 
          "lastName": "Максимов"  // фамилия пользователя, если он есть 
        } 
      ] 
    } 
  ] 
}
API references

Удаление номера из группы
Сopied

POST /groups/action
Пример body JSON запроса:

{ 
  "action": "REMOVE_NUMBER", 
  "groupId": 141, // id группы
  "number": "2561" // номер, который необходимо удалить
}

Успех:

{"status": "Success"}

Возможные ошибки:

Group not foundуказанная группа не найдена
Cant delete the last number from groupнельзя удалить последний номер из группы
The group does not contain specified numberгруппа не содержит указанный номер
API references

Статистика по операторам
Сopied

Для получения статистики по операторам проекта необходимо указать начало и конец интересующего периода в параметрах dateFrom и dateTo соответственно, в формате “yyyy-MM-dd HH:mm:ss”.

Относительный путь: /operator/statistic
Режим: POST
Content-Type: application/json

Кроме того, записи можно предварительно отфильтровать в опциональном параметре filter по:
· callTypes — Список типов звонков, по которым будет сформирована статистика. Перечень допустимых значений приведен в соответствующем словаре;
· innerPhones — Список номеров внутренних линий, по которым будет сформирована статистика;
· minTimeSeconds — Минимальная длительность разговора в секундах;
· minTimeAwaitingSeconds — Минимальная длительность ожидания в секундах;
· maxTimeAwaitingSeconds — Максимальная длительность ожидания в секундах.

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

{
  "from": "2024-01-30 00:00:00",
  "to": "2024-02-05 23:59:59",
  "filter": {
    "callTypes": [
      "REGULAR",
      ...
    ],
    "innerPhones": [
      "1234",
      ...
    ],
    "minTimeSeconds": 1,
    "minTimeAwaitingSeconds": 1,
    "maxTimeAwaitingSeconds": 60
  }
}

Пример ответа в случае успеха:

[
  {
    "operatorName": "1234 (Sample Name)", // Общая статистика: Оператор
    "operatorPhone": "1234", // Номер оператора
    "totalCount": 123, // Общая статистика: Звонков
    "inCount": 123, // Общая статистика: Входящих
    "outCount": 123, // Общая статистика: Исходящих
    "totalDuration": "59:59", // Общая статистика: Длительность разговоров
    "inUniqueCount": 123, // Общая статистика: Уникальных входящих
    "answOpNaCount": 0, // Общая статистика: Пропущенных неотвеченных
    "outAnsweredCount": 123, // По исходящим: Успешных
    "outAnsweredPercentage": "100.0%", // По исходящим: Процент отвеченных звонков
    "outMissedCount": 0, // По исходящим: Количество неуспешных звонков
    "outUniqueCount": 123, // По исходящим: На уникальные номера
    "outUniqueAnsweredCount": 123, // По исходящим: Количество успешных звонков на уникальные номера
    "outUniqueAnsweredPercentage": "100.0%", // По исходящим: Процент успешных звонков на уникальные номера от общего кол-во исходящих
    "outDuration": "59:59", // По исходящим: Длительность разговоров
    "outAverageDuration": "05:30", // По исходящим: Среднее время разговора
    "inAnsweredCount": 123, // По входящим: Отвеченных
    "inAnsweredPercentage": "100.0%", // По входящим: Процент отвеченных звонков
    "inMissedCount": 0, // По входящим: Пропущенных неотвеченных
    "inUniqueAnsweredCount": 123, // По входящим: Отвеченных звонков с уникальных номеров
    "inUniqueAnsweredPercentage": "100.0%", // По входящим: Процент отвеченных звонков с уникальных номеров
    "inAnsweredNewLeadCount": 123, // По входящим: Отвеченных от новых клиентов
    "inLostCount": 0, // По входящим: Потерянных
    "inAverageAwaitingTime": "00:15", // По входящим: Среднее время ожидания при ответе
    "inTotalAwaitingTime": "02:30", // По входящим: Общее время ожидания при ответе
    "inDuration": "59:59", // По входящим: Длительность разговоров
    "inAverageDuration": "05:30", // По входящим: Среднее время разговора
    "inUniqueRegularCount": 123, // По уникальным: Прямой звонок
    "inUniqueTrackingCount": 123, // По уникальным: Call tracking
    "inUniqueC2cButtonCount": 123, // По уникальным: Click to call
    "inUniqueC2cFormCount": 123, // По уникальным: Форма
    "inUniqueC2cApiCount": 123, // По уникальным: Click to call API
    "inUniqueAutodialCount": 123, // По уникальным: Обзвон
    "inUniqueCallbackCount": 123, // По уникальным: Callback
    "inUniqueAutoCallbackCount": 123, // По уникальным: Автоперезвон
    "inUniqueApiCount": 123, // По уникальным: API звонок
    "inRegularCount": 123, // По источникам: Прямой звонок
    "inTrackingCount": 123, // По источникам: Call tracking
    "inC2cButtonCount": 123, // По источникам: Click to call
    "inC2cFormCount": 123, // По источникам: Форма
    "inC2cApiCount": 123, // По источникам: Click to call API
    "inAutodialCount": 123, // По источникам: Обзвон
    "inCallbackCount": 123, // По источникам: Callback
    "inAutoCallbackCount": 123, // По источникам: Автоперезвон
    "inApiCount": 123, // По источникам: API звонок
    "inMissedAnsweredCount": 0, // По пропущенным: Пропущенных отвеченных
    "inMissedNewLeadCount": 0, // По пропущенным: Пропущенных от новых клиентов
    "inMissedPercentage": "0.0%", // По пропущенным: Процент пропущенных звонков от всего звонков
    "inMissedAverageAwaitingTime": "00:00", // По пропущенным: Среднее время ожидание ответа оператора
    "logInTime": "2024-01-30 08:40:00", // Логин
    "logOutTime": "2024-02-05 18:30:00", // Логаут
    "availableNotInWorkTime": "02:30:00", // Общий Available
    "pauseTime": "05:30:00", // Пауза
    "wrapUpTime": "", // Общий Wrap-up Time 
    "compoundTime": 123 // Общий Compound Time
  },
  ...
]

Статистика представляет собой список объектов информации о всех операторах и о каждом в отдельности, соответствующей табличной выгрузке на странице личного кабинета «По операторам» раздела «Статистика« с аналогичными критериями поиска.

Возможные ошибки:

Wrong FROM dateНе указаны или некорректны дата и время начала целевого периода
Wrong TO dateНе указаны или некорректны дата и время конца целевого периода

callType
Сopied

Типы источников звонков:

AUTO_CBАвтоперезвон
AUTODIALОбзвон
REGULARПрямой звонок
C2C_FORMФорма обратного звонка
APIAPI звонок
TRACKINGCall Tracking
CALLBACKCallback
C2C_BUTTONКнопка обратного звонка
C2C_APIAPI обратный звонок

История звонков
Сopied

Для получения истории звонков проекта необходимо указать начало и конец интересующего периода в параметрах dateFrom и dateTo соответственно, в формате “yyyy-MM-dd HH:mm:ss”. Записи возвращаются в порядке убывания id. Количество записей, которые будут получены при этом не превышает значение обязательного параметра limit. Допустимый диапазон limit — от 1 до 1000. Для получения следующей группы записей необходимо в параметре offest указать сдвиг относительно начала списка.

Относительный путь: /history/get
Режим: POST
Content-Type: application/json

Кроме того, записи можно предварительно отфильтровать в опциональном параметре filter по:
· direction — Направление звонков. Допустимые значения: IN — входящие, OUT — исходящие, INNER — внутренние;
· minDuration — Минимальная длительность разговора в секундах;
· calledFrom — Массив частей номеров с которых звонили;
· calledTo — Массив частей номеров на которые звонили;
· outerNum — Массив номеров внешних линий на которые поступали или через которые осуществлялись звонки;
· exactPhone — Массив полных номеров, которые осуществляли или принимали звонки;
· newLead — Признак первого звонка по номеру клиента. Допустимые значения: true — только первые, false — только не первые;
· answered — Признак отвеченного звонка. Допустимые значения: true — только отвеченные, false — только не отвеченные;
· lost — Признак потерянного звонка (пропущенного, на которые не перезвонили). Допустимые значения: true — только потерянные, false — только не потерянные;
· voiceMessage — Признак оставленного голосового сообщения в звонке. Допустимые значения: true — только с голосовым сообщением, false — только без.

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

{  
  "dateFrom": "2023-12-12 00:00:00",  
  "dateTo": "2024-01-01 00:00:00",  
  "limit": 50,  
  "offset": 0,  
  "filter": {
    "direction": "IN",
    "minDuration": 10,
    "calledFrom": ["3809533"],
    "calledTo": ["33"],
    "outerNum": ["380800123123"],
    "exactPhone": ["3333", "380955555555"],
    "newLead": false,
    "answered": true,
    "lost": false,
    "voiceMessage": false
  }  
}

Пример ответа в случае успеха:

{ 
  "count": 100, // Количество звонков по указанным критериям
  "calls": [ // Массив звонков
    { 
      "id": 19990701, // Случайный id звонка
      "dbid": 603, // id звонка в проекте
      "date": "2023-12-20 15:28:00", // Дата и время звонка
      "source": "REGULAR", // Источник звонка
      "direction": "IN", // Направление звонка
      "from": "380955555555", // Номер звонившего
      "to": ["3333"], // Массив номеров на которые поступил звонок
      "lastGroupName": "Sales managers", // Название последней группы внутренних линий, на которую был переведен звонок
      "secondsFullTime": 300, // Полная длительность звонка
      "secondsTalk": 285, // Длительность разговора
      "link": "https://api.unitalk.cloud:8443/tracking/rec/1531144732.920/2023-12-20", // Ссылка на запись звонка
      "comment": "That one was successful!", // Комментарий
      "state": "ANSWER", // Состояние звонка
      "cause": 16, // Код причины завершения
      "callback": false, // Признак автоперезвона
      "utmSource": "google", // Метка аналитики
      "utmMedium": "search", // Метка аналитики
      "utmCampaign": "web", // Метка аналитики
      "utmTerm": "best+product", // Метка аналитики
      "utmContent": "content", // Метка аналитики
      "outerNumber": "site.ua", // Метка аналитики
      "googleId": "1182768620.1182768620", // Метка аналитики
      "facebookClientId": "fb.1.1234567890", // Метка аналитики
      "referer": "google.com" // Метка аналитики
    },
    ...
  ] 
}

Возможные ошибки:

Wrong FROM dateНе указаны или некорректны дата и время начала целевого периода
Wrong TO dateНе указаны или некорректны дата и время конца целевого периода
Limit range is 1-1000Не указан или некорректный параметр limit

Вебхуки
Сopied

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

Движение по балансу
Сopied

api_balance_webhook_url_ru

Вебхук «Движение по балансу» предоставляет информацию по каждой операции изменения баланса проекта и не может быть конфигурирован, поскольку события данной категории обрабатываются системой автоматически. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному на странице личного кабинета «API» URL.

Есть всего 5 типов операций:

MAIN_REFILLПополнение основного счёта
BONUS_REFILLПополнение бонусного счёта
CALLСписание за платный звонок
SMSСписание за отправку SMS
SERVICESСписание за услуги

Пример отправляемого JSON:

{
  "date": "2022-11-12 19:12:50", // Время проведения операции
  "type": "MAIN_REFILL", // Тип операции
  "sum": 500000, // Сумма операции. 1000 соответствует единице валюты проекта
  "sumV2": 500000000, // Сумма операции. 1000,000 соответствует единице валюты проекта
  "mainBalance": 15500000, // Основной баланс по завершению операции. 1000 соответствует единице валюты проекта
  "mainBalanceV2": 15500000000, // Основной баланс по завершению операции. 1000,000 соответствует единице валюты проекта
  "bonusBalance": 350000, // Бонусный баланс по завершению операции. 1000 соответствует единице валюты проекта
  "description": "Пополнение баланса на 500.00 UAH через LiqPay" // Описание операции
}

Обработка событий
Сopied

Отправка вебхука может быть выбрана в качестве типа действия при создании или редактировании действий на странице личного кабинета «Обработка событий». При конфигурации действия данного типа можно указать:
1) URL на который будет отправлен вебхук;
2) HTTP метод, который будет использован;
3) Заголовки HTTP;
4) URL параметры;
5) Тип тела запроса (Для POST, PUT, PATCH);
6) Содержимое тела запроса (Для типов «Указанный JSON» и «Форма (urlencoded)»).
События, за которыми можно закрепить действия, существуют 4 типов:
Типы событий

События в обзвонах номеровНастраиваются для каждого отдельного обзвона номеров при создании или редактировании через API или в соответствующем разделе личного кабинета, например, “Обзвон завершен”.
События в голосовых менюНастраиваются для каждого отдельного голосового меню при создании или редактировании на странице личного кабинета «Голосовое меню», например, нажатие клиентом клавиши “1
События звонковНастраиваются на странице личного кабинета «API», например “Завершение звонка”. Обратите внимание, действие закрепляется за событием звонка вне зависимости от внешней линии, которая при этом задействована
Событие очереди с голосовым сопровождениемДоступно при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на “Очередь с сопровождением” и активации опции “Специальное действие

Более подробно с процессом обработки событий можно ознакомиться в инструкции по обработке событий.
Отправка вебхука с типом тела «Стандартный JSON» подразумевает формирование тела запроса на основании типа события, по которому был отправлен вебхук:
Стандартный JSON для событий звонков:

{
  "event": "CALL_END", // Событие, по которому был отправлен вебхук
  "call": { // Массив данных о звонке
    "id": 1091944, // Случайно генерируемый id звонка для связи его с другими событиями звонков
    "dbid": 275, // id под которым этот звонок был сохранён в базу данных. Впоследствии звонок обладает именно эти id
    "from": "380505557182", // Номер с которого был совершен звонок
    "to": [ // Массив номеров, на которые был переадресован звонок
      "2000"
    ],
    "lastGroupName": "Sales managers", // Название последней группы внутренних линий, на которую был переведен звонок
    "outerNumber": "site.ua", // Внешняя линия, которая была использована для совершения или получения звонка. Содержит название сайта в случае обратного звонка
    "direction": "IN", // Направление звонка: "IN" - входящий, "OUT" - исходящий, "INNER" - внутренний
    "date": "2018-07-09 16:58:52", // Дата и время принятия звонка
    "secondsFullTime": 19, // Полное время звонка. Известно только в событии CALL_END
    "secondsTalk": 9, // Время общения. Известно только в событии CALL_END
    "utmSource": "google", // Метка аналитики. Может быть null
    "utmMedium": "search", // Метка аналитики. Может быть null
    "utmCampaign": "web", // Метка аналитики. Может быть null
    "utmTerm": "ковры", // Метка аналитики. Может быть null
    "utmContent": "content", // Метка аналитики. Может быть null
    "googleId": "1182768620.1530916891", // Метка аналитики. Может быть null
    "facebookClientId": "fb.1.1234567890", // Метка аналитики. Может быть null
    "referer": "google.com", // Метка аналитики. Может быть null
    "callback": true, // Указывает является ли этот звонок обратным. Устарело. Используйте поле "source"
    "comment": "комментарий к звонку",
    "state": "ANSWER", // Состояние звонка. Для событий CALL_NEW и CALL_REDIRECT - null
    "source": "REGULAR", // Источник звонка
    "link": "https://api.unitalk.cloud:8443/tracking/rec/1531144732.920/2018-07-09", // Ссылка на запись звонка. Присутствует только в случае поле state - "ANSWER"
    "meta": "some info", // Дополнительная информация, которая может быть задана при инициации звонка через API
    "cause": 16 // Код завершения звонка
  }
}

Массив «to»

При событии CALL_NEW входящего звонкаВсегда пуст
При событии CALL_REDIRECTСодержит один или более номеров
При событии CALL_ANSWERСодержит один номер
При событии CALL_ENDМожет быть пуст или содержать номера операторов, которым поступил звонок
Для API звонковМожет отсутствовать, если звонок не был ни на кого перенаправлен

Поле «state»

ANSWERЗвонок был принят
BUSYЛиния была занята
FAILСбой
NOANSWERЗвонок не был принят
CHANUNAVAILВызываемый номер был недоступен
NOMONEYНедостаточно средств для совершения звонка
BUSYOUTВо время совершения звонка все внешние линии были заняты
WRONGDIRНеверное направление звонка
BLOCKEDЗвонок был заблокирован согласно настройкам проекта
DIALINGИдет вызов
UNREACHABLEАбонент недоступен или находится вне зоны действия сети
NOT_EXISTВызываемый номер не существует

Поле «source»

REGULARОбычный прямой звонок
TRACKINGЗвонок коллтрекинга
CLICK2CALLОбратный звонок с кнопки
LEAD_CATCHERОбратный звонок с попапа
FORMОбратный звонок с формы
CALLBACKЗвонок по признаку callback на внешнем номере
AUTO_CBАвтоматический обратный звонок на пропущенный вызов
AUTODIALЗвонок из обзвона номеров
API_CALLЗвонок инициированный через API
C2C_APIс2с звонок инициированный через API

Стандартный JSON для событий голосовых меню:

{ 
    "ivrName":"Распределение по отделам", // Название голосового меню
    "from":"380971234567", // Номер телефона абонента
    "outerNumber":"380441234567", // Внешняя линия, которая была использована для совершения или получения звонка. Содержит название сайта в случае обратного звонка
    "pressedDigit":2, // Цифра на которую нажал абонент. Может быть null 
    "actionType": "MAIN", // Тип действия. "MAIN" - основное действие, "NO_CHOICE" - действие отсутствия выбора, "WRONG_DIGIT" - действие неправильного выбора
    "projectName": "myproject", // Название проекта
    "utmCampaign": "sale2021", // Метка аналитики. Может быть null
    "utmSource": "google", // Метка аналитики. Может быть null
    "utmMedium": "email", // Метка аналитики. Может быть null
    "utmTerm": "term", // Метка аналитики. Может быть null
    "utmContent": "content", // Метка аналитики. Может быть null
    "googleId": "11111.11111", // Метка аналитики. Может быть null
    "facebookClientId": "fb.1.1234567890" // Метка аналитики. Может быть null
}

Стандартный JSON для событий завершения звонков обзвонов номеров:

{
    "from": "380971234567", // Номер телефона абонента
    "operatorNumber": "2040", // Внутренняя линия оператора. Может быть null
    "callName": "Владимир", // Имя закрепленное за номером обзвона
    "callNote": "покупал окна", // Заметка к номеру обзвона
    "calledCount": 1, // Количество звонков на данный номер в обзвоне
    "callState": "ANSWER", // Статус завершения звонка. Детальнее в разделе "Обзвон номеров" - "Общие сведенья"
    "dialName": "обзвон-окна", // Название обзвона
    "totalCount": 2000, // Количество номеров в обзвоне
    "doneCount": 537, // Количество обработанных номеров обзвона
    "projectName": "myproject" // Название проекта
}

Стандартный JSON для событий обзвона, не связанных со звонками

{}

Стандартный JSON для события очереди с голосовым сопровождением

{ 
    "from":"380971234567", // Номер телефона абонента
    "projectName":"my-project", // Название проекта
    "utmCampaign": "sale2021", // Метка аналитики. Может быть null
    "utmSource": "google", // Метка аналитики. Может быть null
    "utmMedium": "email", // Метка аналитики. Может быть null
    "utmTerm": "term", // Метка аналитики. Может быть null
    "utmContent": "content", // Метка аналитики. Может быть null
    "googleId": "11111.11111", // Метка аналитики. Может быть null
    "facebookClientId": "fb.1.1234567890", // Метка аналитики. Может быть null
    "gclid": "gclid..." // Метка аналитики. Может быть null
    "cdid": "cdid...", // Метка аналитики. Может быть null
    "referer": "https://unitalk.cloud", // Метка аналитики. Может быть null
    "ip": "111.111.111.111" // !
}

Входящие вебхуки
Сopied

UniTalk может принимать вебхуки с определенной структурой и выполнять по ним действия.
Доступные на данный момент действия:
1) «AUTODIAL_ADD» — Добавление номера телефона в обзвон номеров;
2) «AUTODIAL_REMOVE» — Удаление номера телефона из обзвона номеров.
Для использования входящих вебхуков на странице личного кабинета «API« необходимо:
1) Сгенерировать токен:

api_inbound_webhook_token_ru


2) Нажать кнопку «Сгенерировать ссылку«:

api_link_gen_ru


3) Выбрать действие, обзвон к которому оно применится, указать дополнительные опции и нажать кнопку «Сгенерировать«:

API references


4) Заполнить параметры ссылки и отправить на неё POST запрос.
Параметры, которые заполняются при генерации автоматически:

tokenТокен для входящих вебхуков
actionТип действия вебхука
idid обзвона номеров

Добавить номера в обзвон
Сopied

Пример сгенерированной ссылки:
https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=&note=&link=&phones=
Параметры, которые необходимо заполнить:

phonesНомер телефона или список номеров телефона через запятую которые необходимо добавить в обзвон
nameИмя, которое будет закреплено за добавляемыми номерами. Максимум 100 символов. Не обязательное поле
noteЗаметка, которая будет закреплена за добавляемыми номерами. Максимум 500 символов. Не обязательное поле
linkДанные для Web Dialer, которые будут закреплены за добавляемыми номерами. Максимум 500 символов. Не обязательное поле

Пример заполненной ссылки:
https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=vasya&note=okna&phones=380971234567
При отправке POST запроса по этой ссылке, в обзвон с id «20461» будет добавлен номер телефона «380971234567», с именем «vasya» и заметкой «okna».
В случае успеха:

{"status": "Success"}

Возможные ошибки:

Token not foundПереданный токен не найден в UniTalk
Action not foundОтсутствует параметр action в ссылке
Id is nullОтсутствует параметр id в ссылке
Autodial not foundНе найден обзвон по id
Empty phonesПараметр phones не указан или пустой
Phones not foundПараметр phones не пустой, но в нем не найден хотя бы один корректный номер телефона
Phones not addedНе получилось добавить номера в обзвон. Возможно номера уже были добавлены в обзвон

Удалить номера с обзвона
Сopied

Пример сгенерированной ссылки:
https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_REMOVE&id=20461&phones=
Параметры, которые необходимо заполнить:

phonesНомер телефона или список номеров телефона через запятую которые необходимо добавить в обзвон

Пример заполненной ссылки:
https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_REMOVE&id=20461&phones=380971234567,380670001000
При отправке POST запроса по этой ссылке, из обзвона с id «20461» будут удалены номера «380971234567» и «380670001000».
В случае успеха:

{"status": "Success"}

Возможные ошибки:

Token not foundПереданный токен не найден в UniTalk
Action not foundОтсутствует параметр action в ссылке
Id is nullОтсутствует параметр id в ссылке
Autodial not foundНе найден обзвон по id
Empty phonesПараметр phones не указан или пустой
Phones not foundПараметр phones не пустой, но в нем не найден хотя бы один корректный номер телефона
Calls not foundНе получилось удалить ни один номер. Возможно в обзвоне не было ни одного из указанных номеров

Перевод звонка на ответственного оператора
Сopied

api_operator_webhook_url_ru

Вебхук «Перевод звонка на ответственного оператора» позволяет получить информацию о звонке для последующего выбора ответственного оператора Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на «На ответственного менеджера» и активации опции «Запрос в Ваш API» URL.

При выполнении данного перенаправления, на указанный URL будет отправлен запрос с следующим содержимым:

{  
  "event": "ROUTE",  
  "call": {  
    "from": "380505557182" // Номер звонящего абонента  
  }  
}

В ответ Ваше приложение должно отправить JSON следующей структуры:

{  
  "operatorNumber": "2048", // Номер телефона ответственного оператора. Можно указать SIP или GSM. Может быть null
  "callerName": "Александр",  // Имя абонента, которое будет отображено в SIP клиенте
  "ivrId": 487 // id голосового меню, которое необходимо воспроизвести абоненту. Может быть null
}

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

Управление очередью с голосовым сопровождением
Сopied

Вебхук «Управление очередью с голосовым сопровождением» позволяет получить информацию о звонке для последующей приоритезации обработки клиентов Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на «Очередь с сопровождением» и активации опции «Вебхук для управления» URL.

api_queue_webhook_url_ru


При выполнении данного перенаправления, на указанный URL отправлен будет запрос с следующим содержимым:

{
  "outerNumber": "380440000001", // Внешняя линия, на которую поступил звонок
  "from": "380501234567", // Номер абонента
  "utmSource": null, // Метка аналитики. Может быть null
  "utmMedium": null, // Метка аналитики. Может быть null
  "utmCampaign": null, // Метка аналитики. Может быть null
  "utmTerm": null, // Метка аналитики. Может быть null
  "utmContent": null, // Метка аналитики. Может быть null
  "googleId": null, // Метка аналитики. Может быть null
  "facebookClientId": null, // Метка аналитики. Может быть null
  "gclid": null, // Метка аналитики. Может быть null
  "cdid": null, // Метка аналитики. Может быть null
  "referer": null // Метка аналитики. Может быть null
}

Очередь с приоритетом состоит из 10 очередей, которые обрабатываются в порядке уменьшения номера. По умолчанию, UniTalk определяет все звонки в очередь с номером 5.
Ваше приложение может изменить номер очереди, отправив в ответ JSON следующей структуры:

{
  "setPriority": 7 // Номер очереди от 1 до 10
}

Сообщения
Сopied

Для отправки сообщений через SMS и Viber на странице личного кабинета «Сервис отправки сообщений» раздела «Интеграция» должна быть подключена интеграция с сервисом отправки сообщений. Доступность типов сообщений и направлений зависит от настройки этой интеграции. Максимальная длинна текста для Viber — 1000 символов, для SMS — зависит от сервиса отправки сообщений.

Отправка сообщения
Сopied

Относительный путь: /message/send
Режим: POST
Content-Type: application/json

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

{
  "messageType" : "SMS", // Тип сообщения. "SMS" или "VIBER"
  "to" : "380971234567", // Номер телефона получателя в международном формате
  "text" : "Lorem ipsum dolor sit amet, consectetuer adipiscing elit." // Текст сообщения
}

Пример ответа в случае успеха:

{"status": "Success", "data": 12345}

Идентификатор сообщения, возвращаемый в data, может быть использован для последующего получения информации о статусе отправки сообщения.

Возможные ошибки:

Message service not connectedНе подключен сервис отправки сообщений
Validation errorОшибки валидации. Возможные причины:
· Неправильный номер телефона получателя
· Отправка сообщений по данному направлению не разрешена настройками интеграции с сервисом отправки сообщений
· Не выбран тип сообщения
· Отправка SMS отключена в настройках сервиса отправки сообщений
· Отправка сообщений в Viber отключена в настройках сервиса отправки сообщений
· Сообщение не может быть пустым
· Сообщение слишком длинное
· Сообщение содержит недопустимые символы
UniTalk did not allow sendingUniTalk не разрешил отправку. Возможные причины:
· Недоступное направление для отправки
· На балансе недостаточно средств
· Проект не активен
Service responseОтвет сервиса. Возможные причины:
· Неверные данные авторизации
· Недостаточно средств на балансе
· Превышен лимит запросов
· Дубль сообщения
· IP адрес не разрешен в сервисе отправки сообщений
· Имя отправителя заблокировано получателем
· Недоступная страна получателя
· Номер получателя заблокирован
· Недопустимое имя отправителя
· Имя отправителя на модерации
· Недопустимый номер получателя
· Недопустимый текст
· Отправка сообщений в Viber недоступна
· Данные некорректны
· Сервис отправки сообщений временно недоступен
Unknown errorНеизвестная ошибка

Массовая отправка сообщений
Сopied

Для отправки нескольких сообщений одним запросом может быть использована массовая отправка сообщений. Максимальное количество сообщений — 100. Запрос может быть осуществлен в двух вариантах:
· С указанием общего текста сообщений в параметре text и списка номеров телефонов получателей в международном формате в параметре recipients;
· С указанием номеров телефонов получателей в международном формате и соответствующих текстов сообщений парами в массиве messages, где ключ — номер телефона, а значение — текст сообщения.
Если в запросе одновременно указаны параметры обоих способов, будет использован параметр messages.

Относительный путь: /message/sendBulk
Режим: POST
Content-Type: application/json

Примеры JSON запросов:

{
  "messagesType": "SMS", // Тип сообщений. "SMS" или "VIBER"
  "recipients": [  // Номера телефонов получателей в международном формате
    "380971234567",
    "380981234567",
    ...
  ],
  "text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit." // Текст сообщений
}
{
  "messagesType": "SMS", // Тип сообщений. "SMS" или "VIBER"
  "messages": { // Массив сообщений
    "380971234567": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 1", // "Номер телефона": "Текст сообщения"
    "380981234567": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 2", // "Номер телефона": "Текст сообщения"
    ...
  }
}

Пример ответа в случае успеха:

{
  "status": "Success",
  "data": {
    "380971234567": { // Отправлено
      "id": 123451, // Идентификатор сообщения
      "error": null // Текст ошибки отправки сообщения
    },
    "380981234567": { // Не отправлено
      "id": 123452, // Идентификатор сообщения
      "error": "Sample error text" // Текст ошибки отправки сообщения
    },
    ...
  }
}

Массив, возвращаемый в data, содержит идентификатор и текст ошибки каждого из оправляемых сообщений. Идентификатор может быть использован для последующего получения информации о статусе отправки сообщения.

Возможные ошибки:

Message service not connectedНе подключен сервис отправки сообщений
messagesType is nullНе выбран тип сообщений
Messages not specifiedВ запросе не указано ни параметр messages, ни recipients
Too many messagesМассив messages содержит более 100 пар
messages is emptyМассив messages пустой
messages contains null keyВ массиве messages присутствует пустой ключ
messages contains null valueВ массиве messages присутствует пустое значение
Too many recipientsСписок recipients содержит более 100 номеров
recipients is emptyСписок recipients пустой
recipients contains nullВ списке recipients присутствует пустое значение
text is null or emptyДля отправки используется список recipients, но текст не указан

Получение статуса отправки сообщения
Сopied

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

Относительный путь: /message/getStatus
Режим: POST
Content-Type: application/x-www-form-urlencoded (Также можно отправлять запрос передавая параметры в качестве параметров url, без тела)

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

/message/getStatus?id=12345

Пример ответа в случае успеха:

{
  "status": "Success",
  "data": {
    "messageStatus": "ERROR", // Статус отправки сообщения
    "errorText": "Service response: invalid authorization data" // Текст ошибки. Если статус не ERROR - null
  }
}

Массив, возвращаемый в data, содержит статус отправки сообщения и текст ошибки отправки, если статус отправки — ERROR.

Статусы отправки:
· SENT — Отправлено. Информация о доставке отсутствует;
· DELIVERED — Доставлено;
· NOT_DELIVERED — Не доставлено;
· ERROR — Ошибка отправки.

Возможные ошибки:

Invalid idПараметр id отсутствует или некорректный
Message not foundПо указанному id не найдено сообщение

Получение списка расссылок
Сopied

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

Относительный путь: /messageDistribution/getAll
Режим: POST
Content-Type: —

Пример ответа:

[
  {
    "id": 123, // Идентификатор рассылки
    "name": "Sample_name", // Название
    "messageType": "SMS", // Тип сообщений. "SMS" или "VIBER"
    "text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Текст рассылки
    "startTime": "2024-07-07 12:00:00", // Время запуска. Если запущена сразу - null
    "paused": false, // Признак паузы. "true" - на паузе, "false" - нет
    "totalNumbersCount": 10, // Количество номеров в рассылке
    "currentNumbersCount": 10, // Количество необработанных номеров
    "status": "WAITING_START_TIME" // Статус рассылки
  },
  ...
]

Статусы рассылок:
· COMPLETED — Рассылка завершена;
· PAUSED — На паузе;
· WAITING_START_TIME — Ожидание времени запуска;
· IN_PROGRESS — В процессе рассылки;
· MESSAGE_SERVICE_NOT_CONNECTED — Не подключен сервис отправки сообщений.

Создание рассылки
Сopied

Для создания рассылки в запросе необходимо указать обязательные параметры:
· name — Уникальное название новой рассылки. Максимальная длинна — 45 символов;
· messageType — Тип сообщений. «SMS» или «VIBER«;
· numbers — Список номеров телефонов получателей в международном формате. Максимальное количество номеров — 10000;
· text — Текст рассылки. Ограничения зависят от типа сообщений и сервиса отправки сообщений.
Опционально в параметре startTime можно указать дату и время отложенного запуска в формате “yyyy-MM-dd HH:mm:ss”.

Относительный путь: /messageDistribution/create
Режим: POST
Content-Type: application/json

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

{
  "name": "Sample_name", // Название
  "messageType": "SMS", // Тип сообщений. "SMS" или "VIBER"
  "numbers": [ // Номера телефонов получателей в международном формате
    "380971234567",
    "380671234567",
    ...
  ],
  "text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Текст рассылки
  "startTime": "2024-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу
}

Пример ответа в случае успеха:

{"status": "Success", "data": 1234}

Идентификатор рассылки, возвращаемый в data, может быть использован для последующего взаимодействия с ней.

Возможные ошибки:

The project does not have a messaging service connectedНе подключен сервис отправки сообщений
The name cannot be empty or contain more than 45 charactersНазвание рассылки не указано или превышает 45 символов
The name already existsРассылка с таким называнием уже существует
No customer numbers are listedНомера в списке numbers не указаны
There can be no more than 10000 numbers in the message distributionКоличество номеров в списке numbers превышает 10000
Wrong numbersВ списке numbers присутствуют некорректные номера.
В параметре ответа data будет возвращен список некорректных номеров
Incorrect time formatНекорректный формат параметра startTime
Validation errorОшибки валидации. Возможные причины:
· Не выбран тип сообщения
· Отправка SMS отключена в настройках сервиса отправки сообщений
· Отправка сообщений в Viber отключена в настройках сервиса отправки сообщений
· Сообщение не может быть пустым
· Сообщение слишком длинное
· Сообщение содержит недопустимые символы

Изменение рассылки
Сopied

Для изменения рассылки в запросе необходимо указать обязательные параметры:
· id — Идентификатор рассылки;
· name — Уникальное название рассылки. Максимальная длинна — 45 символов;
· messageType — Тип сообщений. «SMS» или «VIBER«;
· text — Текст рассылки. Ограничения зависят от типа сообщений и сервиса отправки сообщений.
Опционально в параметре startTime можно указать дату и время отложенного запуска в формате “yyyy-MM-dd HH:mm:ss”.

Относительный путь: /messageDistribution/update
Режим: POST
Content-Type: application/json

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

{
  "id": 1234, // Идентификатор рассылки
  "name": "Sample_name", // Название
  "messageType": "SMS", // Тип сообщений. "SMS" или "VIBER"
  "text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Текст рассылки
  "startTime": "2024-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу
}

Ответ в случае успеха:

{"status": "Success"}

Возможные ошибки:

The project does not have a messaging service connectedНе подключен сервис отправки сообщений
id is not specifiedОбязательный параметр id не указан
Message distribution not foundРассылка не найдена по указанному id
Message distribution completedРассылка уже завершена
The name cannot be empty or contain more than 45 charactersНазвание рассылки не указано или превышает 45 символов
The name already existsРассылка с таким называнием уже существует
Incorrect time formatНекорректный формат параметра startTime
Validation errorОшибки валидации. Возможные причины:
· Не выбран тип сообщения
· Отправка SMS отключена в настройках сервиса отправки сообщений
· Отправка сообщений в Viber отключена в настройках сервиса отправки сообщений
· Сообщение не может быть пустым
· Сообщение слишком длинное
· Сообщение содержит недопустимые символы

Удаление рассылки
Сopied

Для удаления рассылки необходимо указать её идентификатор в параметре id.

Относительный путь: /messageDistribution/remove
Режим: POST
Content-Type: application/x-www-form-urlencoded (Также можно отправлять запрос передавая параметры в качестве параметров url, без тела)

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

/messageDistribution/remove?id=1234

Ответ в случае успеха:

{"status": "Success"}

Возможные ошибки:

id is not specifiedОбязательный параметр id не указан

Приостановка или возобновление рассылки
Сopied

Для приостановки или возобновления рассылки необходимо указать её идентификатор в параметре id и действие в параметре paused:
· true — Поставить на паузу;
· false — Снять с паузы.

Относительный путь: /messageDistribution/setPaused
Режим: POST
Content-Type: application/x-www-form-urlencoded (Также можно отправлять запрос передавая параметры в качестве параметров url, без тела)

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

/messageDistribution/setPaused?id=1234&id=true

Ответ в случае успеха:

{"status": "Success"}

Возможные ошибки:

id is not specifiedОбязательный параметр id не указан
Message distribution not foundРассылка не найдена по указанному id
Message distribution completedРассылка уже завершена

Web Dialer
Сopied

Для работы с виджетом Chrome (далее Web Dialer) используются методы сгруппированные по пути /widget/

Отправка уведомлений в Web Dialer
Сopied

Для отправки уведомлений в Web Dialer необходимо указать id пользователей, которым необходимо отобразить уведомление, в параметре userIds и указать как минимум один параметр объекта data.

Относительный путь: /widget/sendNotification
Режим: POST
Content-Type: application/json

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

{
  "userIds": [ // Массив id пользователей
    5701, 5800, 4560
  ],
  "data": { // Объект параметров уведомления
    "contactName": "John", // Имя контакта
    "contactLink": "https://www.example-crm.com/leads/1", // Ссылка на контакт
    "entityName": "Best deal", // Имя связанной с контактом сущности
    "entityLink": "https://www.example-crm.com/deals/1", // Ссылка на связанную сущность
    "responsible": "Manager #1" // Имя ответственного менеджера
  }
}

Пример ответа в случае успеха:

{
  "status":"Success",
  "data": {
    "notificationId": 1985837794 // id отправленного уведомления
  }
}

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

Возможные ошибки:

No users was specified for notifications sendНе было указано ни одного пользователя для отправки уведомления
Data fields is all nullНе указано значение ни одного параметра объекта data
User with id *xxxx* not foundПользователь с указанным id не был найден
No users with connected chrome extension was foundУказанные пользователи не подключили Web Dialer

Сокрытие уведомлений в Web Dialer
Сopied

Для сокрытия отправленных уведомлений в Web Dialer необходимо указать id пользователей, у которых необходимо скрыть уведомление, в параметре userIds и notificationId, полученный при отправке уведомления.

Относительный путь: /widget/hideNotification
Режим: POST
Content-Type: application/json

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

{     
  "userIds": [ // Массив id пользователей
    5701, 5800, 4560
  ],
  "notificationId": 1551593033 // id целевого уведомления
}

Ответ в случае успеха:

{"status": "Success"}

Возможные ошибки:

No users was specified for notifications hideНе было указано ни одного пользователя для скрытия уведомления
NotificationId not specifiednotificationId не указан
The specified users are not found or chrome extension not connectedУказанные пользователи не найдены или у них не подключен Web Dialer