Создание задания
Метод: POST
Authorization: Bearer Token
URL: https://cis.twin24.ai/cis/api/v1/telephony/autoCall
| Блок кода | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
curl --location 'https://cis.twin24.ai/cis/api/v1/telephony/autoCall' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ТОКЕН' \ --data '{ "name": "test_autocall", "defaultExectaskComment": "robotТестовое задание для демонстрации работы API", "defaultExecDatastartType": "228cc4fa-92f2-4709-94e3-7344a96a5903time", "secondExecstartMoment": "ch2023-06-02 10:00", "secondExecDatascheduleId": "48a77bd7bce7d22e-8762dde6-4e0f4427-a277b391-4ef77e36c41bebbdfda44de6", "cidTypedefaultExec": "gornumrobot", "cidDatadefaultExecData": "9a67dee5228cc4fa-398e92f2-45704709-942694e3-fbb3f067b2707344a96a5903", "startTypesecondExec": "timech", "startMomentsecondExecData": "2023-06-02 10:0048a77bd7-8762-4e0f-a277-4ef77e36c41b", "cpscidType": 1.03"gornum", "taskCommentcidData": "Тестовое задание для демонстрации работы API9a67dee5-398e-4570-9426-fbb3f067b270", "webhookUrlscallStrategy": ["STEP_2_STEP", "https://webhook.site/6f44...2aa287f", "cps": 1.03, "checkPhone": true, "phoneNormalization"https://typedwebhook.tools/webhook/4c6d9...8720ab39" ]: "RU", "additionalOptionsnormalizationErrorAction": { "IGNORE_NORMALIZATION_ERROR", "fullListMethodsendReportAfterFinish": "reject"true, "fullListTimewebhookUrls": 0,[ { "useTr": false, "allowCallTimeFromurl": 0"https://example.com", "allowCallTimeTopartialResults": 86399true, "recordCall "delay": true4, "recTrimLeftevents": 0,{ "detectRobot": true, "detectRobotModeCALL_ENDED": "back", { "providerId": null }, "redialStrategyOptionsname": { "CALL_ENDED", "redialStrategyEn": false, "busy "value": {true "redial": false}, "timeCANDIDATE_CHANGED": 1,{ "count": 1 }"name": "CANDIDATE_CHANGED", "noAnswer": { "redialvalue": false,true "time": 1}, "count "CALL_REDIRECTED": 1{ }, "answerMashname": { "CALL_REDIRECTED", "redial": false, "timevalue": 1,true "count": 1 }, }, "congestionRECALL_SCHEDULED": { "redial": false, "timename": 1"RECALL_SCHEDULED", "count": 1 }, "value": true "answerNoList": { }, "redial": false, "timeEFFICIENCY_REACHED": 1,{ "count": 1 } "name": "EFFICIENCY_REACHED", } }' | ||||||||
| Блок кода | ||||||||
| ||||||||
{ "name": "test_autocall", "defaultExec": "robot", "defaultExecDatavalue": "228cc4fa-92f2-4709-94e3-7344a96a5903", true "secondExec": "ch" }, "secondExecData": "48a77bd7-8762-4e0f-a277-4ef77e36c41b", "cidType": "gornum", "cidDataAUTOCALL_STATUS_CHANGED": "9a67dee5-398e-4570-9426-fbb3f067b270",{ "startType": "time", "startMoment": "2023-06-02 10:00", "cps": 1.03, "taskCommentname": "Тестовое задание для демонстрации работы API", "AUTOCALL_STATUS_CHANGED", "webhookUrlsvalue": [true "https://webhook.site/6f44...2aa287f", "https://typedwebhook.tools/webhook/4c6d9...8720ab39" } ], "additionalOptions": {} "fullListMethod} ], "additionalOptions": "reject",{ "fullListTimefullListMethod": 0"reject", "useTrfullListTime": false0, "allowCallTimeFrom": 0, "allowCallTimeTo": 86399, "recordCall": true, "recTrimLeft": 0, "useTr": false, "detectRobot": true, "detectRobotMode": "back", "providerIddetectRobotGreeting": null"bce7d22e-dde6-4427-b391-ebbdfda44de6", }, "redialStrategyOptionsfz230": {true }, "redialStrategyEnredialStrategyOptions": false,{ "busyredialStrategyEn": { false, "redialcandidateLimit": false,{ "timeredial": 1false, "count": 10 }, "noAnswernumberLimit": { "redial": false, "time": 1, "count": 10 }, "answerMashbusy": { "redial": false, "time": 1, "count": 1 }, "congestionnoAnswer": { "redial": false, "time": 1, "count": 1 }, "answerNoListanswerMash": { "redial": false, "time": 1, "count": 1 }, } } |
Описание полей метода:
...
Поле
...
Тип
...
Обязательно
...
Описание
...
Тип звонящего.
Всегда принимает значение robot
...
Действие, если робот запросил переадресацию.
Принимает значения:
- end (Завершить)
- ignore (Ничего не делать)
- ch (Передать вызов на канал)
...
да, если
secondExec = ch
...
uuid канала для перевода.
Параметр нужен, если предыдущий параметр в значении ch
...
Определяемый номер.
Принимает значения:
- default (По умолчанию для транка)
- gornum (Один номер)
- pool (Группа номеров)
...
да, если
cidType = gornum или pool
...
id сущности, выбранной в cidType.
Актуально для gornum и pool
...
Режим запуска задания.
Принимает значения:
- manual (Вручную)
- time (В указанное время)
...
да, если
startMoment = time
...
Дата и время начала обзвона.
Принимает значения:
ГГГГ-ММ-ДД чч:мм
*Используется часовой пояс компании
...
Интенсивность обзвона.
Вычисляется как 1+N\100, где N – желаемое число наборов номера в секунду (CPS).
Например:
Желаемое CPS = 3, тогда значение поля 1.03
...
Считать ли звонок результативным.
Всегда принимает значение reject
...
да, если
useTr = true
...
да, если
useTr = true
...
да, если
recordCall = true
...
да, если
detectRobot = true
...
Режим системы определителя.
Принимает значения:
- back (Фоновая)
- block (С блокировкой)
...
нет
...
uuid транка.
Актуально только при использовании собственного транка.
...
да, если
redial = true
...
да, если
redial = true
...
"congestion": {
"redial": false,
"time": 1,
"count": 1
},
"answerNoList": {
"redial": false,
"time": 1,
"count": 1
}
}
}' |
| Блок кода | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
{
"name": "test_autocall",
"taskComment": "Тестовое задание для демонстрации работы API",
"startType": "time",
"startMoment": "2023-06-02 10:00",
"scheduleId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"defaultExec": "robot",
"defaultExecData": "228cc4fa-92f2-4709-94e3-7344a96a5903",
"secondExec": "ch",
"secondExecData": "48a77bd7-8762-4e0f-a277-4ef77e36c41b",
"cidType": "gornum",
"cidData": "9a67dee5-398e-4570-9426-fbb3f067b270",
"callStrategy": "STEP_2_STEP",
"cps": 1.03,
"checkPhone": true,
"phoneNormalization": "RU",
"normalizationErrorAction": "IGNORE_NORMALIZATION_ERROR",
"sendReportAfterFinish": true,
"webhookUrls": [
{
"url": "https://example.com",
"partialResults": true,
"delay": 4,
"events": {
"CALL_ENDED": {
"name": "CALL_ENDED",
"value": true
},
"CANDIDATE_CHANGED": {
"name": "CANDIDATE_CHANGED",
"value": true
},
"CALL_REDIRECTED": {
"name": "CALL_REDIRECTED",
"value": true
},
"RECALL_SCHEDULED": {
"name": "RECALL_SCHEDULED",
"value": true
},
"EFFICIENCY_REACHED": {
"name": "EFFICIENCY_REACHED",
"value": true
},
"AUTOCALL_STATUS_CHANGED": {
"name": "AUTOCALL_STATUS_CHANGED",
"value": true
}
}
}
],
"additionalOptions": {
"fullListMethod": "reject",
"fullListTime": 0,
"allowCallTimeFrom": 0,
"allowCallTimeTo": 86399,
"recordCall": true,
"recTrimLeft": 0,
"useTr": false,
"detectRobot": true,
"detectRobotMode": "back",
"detectRobotGreeting": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
"fz230": true
},
"redialStrategyOptions": {
"redialStrategyEn": false,
"candidateLimit": {
"redial": false,
"count": 0
},
"numberLimit": {
"redial": false,
"count": 0
},
"busy": {
"redial": false,
"time": 1,
"count": 1
},
"noAnswer": {
"redial": false,
"time": 1,
"count": 1
},
"answerMash": {
"redial": false,
"time": 1,
"count": 1
},
"congestion": {
"redial": false,
"time": 1,
"count": 1
},
"answerNoList": {
"redial": false,
"time": 1,
"count": 1
}
}
} |
Описание полей метода:
Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| name | string | да | Имя обзвона |
| taskComment | string | нет | Комментарий к заданию |
| startType | string | да | Режим запуска задания. Принимает значения:
|
| startMoment | string | да, если startType = time | Дата и время начала обзвона. Принимает значения: ГГГГ-ММ-ДД чч:мм *Используется часовой пояс компании |
| scheduleId | string | нет | Идентификатор расписания обзвона |
| defaultExec | string | да | Тип звонящего. Всегда принимает значение robot |
| defaultExecData | string | да | uuid сценария, который будет использоваться в обзвоне ботом |
| secondExec | string | да | Действие, если робот запросил переадресацию. Принимает значения:
|
| secondExecData | string | да, если secondExec = ch | uuid канала для перевода. Параметр нужен, если предыдущий параметр в значении ch |
| cidType | string | да | Определяемый номер. Принимает значения:
|
| cidData | string | да, если cidType = gornum или pool | id сущности, выбранной в cidType. Актуально для gornum и pool |
| callStrategy | string | нет | Последовательная стратегия (STEP_2_STEP) – для кандидата с несколькими номерами сначала осуществляются все попытки перезвонить на первый номер, затем производятся все попытки звонить на следующий его номер и так далее. Параллельная стратегия (PARALLEL) – для кандидата с несколькими номерами при неуспешном дозвоне на первый номер, следующий звонок будет производиться на второй номер и так далее. После чего будет сформирована очередь перезвонов. Для корректной работы параллельной стратегии по нескольким кандидатам CPS задания должен быть больше 1. |
| cps | float | да | Интенсивность обзвона. Для N звонков в 1 секунду вычисляется как 1+N/100, где N – желаемое число наборов номера в секунду (CPS). Например: Желаемое CPS = 3, тогда значение поля 1.03 (при N=3 вычисляется 1+3/100=1.03) Для 1 звонка в N секунд вычисляется как Например: Желаемая интенсивность 1 звонок в 60 секунд, тогда значение поля 0.4 (при N=60 вычисляется 1-60/100=0.4) |
| checkPhone | boolean | нет | Проверка корректности формата номера при добавлении кандидата |
| phoneNormalization | string | нет | Определяет, активирован ли процесс нормализации. Если null, отключено, если RU — нормализация в российский формат. Подробнее о нормализации читайте ниже. |
| normalizationErrorAction | string | нет | Указывает действие при возникновении ошибки нормализации. Для этого параметра необходимо активировать нормализацию. Доступны следующие варианты:
Подробнее о нормализации читайте ниже. |
| sendReportAfterFinish | boolean | нет | Отправлять ли отчет после завершения задания на Email |
| webhookUrls | Array[Object] | нет | URL адреса и события, по которым нужно отправить webhook |
| | url | string | нет | URL адреса, куда будет отправлен webhook |
| | partialResults | boolean | нет | Отправлять ли промежуточные результаты |
| | delay | int | нет | Задержка перед отправкой webhook |
| | events | Object | нет | Список событий, по которым нужно отправить webhook |
| | | EVENT | Object | нет | Объект события.
Подробнее о webhook и событиях можно узнать в отдельных статьях: |
| | | | name | string | нет | Имя события – соответствует EVENT |
| | | | value | boolean | нет | Отправлять ли webhook по данному событию |
| additionalOptions | Object | да | Дополнительные параметры вызовов |
| | fullListMethod | string | да | Считать ли звонок результативным. Всегда принимает значение reject |
| | fullListTime | int | да | Через сколько секунд считать звонок результативным |
| | allowCallTimeFrom | int | да, если useTr = true | Начало интервала доступного для дозвона. Задается в секундах |
| | allowCallTimeTo | int | да, если useTr = true | Конец интервала доступного для дозвона. Задается в секундах |
| | recordCall | boolean | да | Записывать ли звонки |
| | recTrimLeft | int | да, если recordCall = true | На сколько обрезать начало записи. Задается в секундах |
| | useTr | boolean | нет | Учитывать ли время получателя |
| | detectRobot | boolean | нет | Включать ли систему определения человек/робот |
| | detectRobotMode | string | да, если detectRobot = true | Режим системы определителя. Принимает значения:
|
| | detectRobotGreeting | string | нет | Идентификатор файла с приветствием. Будет воспроизведен при использовании системы определения человек/робот в режиме block (С блокировкой) |
| | fz230 | boolean | нет | Включить ли соответствие стратегии обзвона ФЗ 230 |
| redialStrategyOptions | Object | да | Настройки правил перезвона |
| | redialStrategyEn | boolean | да | Использовать ли правила перезвона |
| | candidateLimit | Object | нет | Максимальное количество вызовов кандидату |
| | numberLimit | Object | нет | Максимальное количество вызовов по номеру |
| | | redial | boolean | да | Активировать ли лимит по максимальному количеству вызовов |
| | | count | int | да, если redial = true | Максимальное количество вызовов |
| | busy | Object | да | Занято |
| | noAnswer | Object | да | Нет ответа |
| | answerMash | Object | да | Ответил автоответчик |
| | congestion | Object | да | Ошибка вызова |
| | answerNoList | Object | да | Вызов нерезультативен |
| | | redial | boolean | да | Активировать ли сценарий перезвона |
| | | time | int | да, если redial = true | Промежуток перезвона. Задается в секундах |
| | | count | int | да, если redial = true | Количество перезвонов |
| Блок кода | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"id": {
"identity": "bf1fee...70dc544"
}
} |
Описание полей ответа:
Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id | Object | Да | - |
identity | string | Да | Идентификатор задания на обзвон |
Якорь normalization normalization
Нормализация
| normalization | |
| normalization |
Настройка нормализации
Нормализация номеров телефонов предназначена для облегчения добавления кандидатов в задание.
| Примечание |
|---|
| Доступно только для российских номеров. Если ваша компания базируется в другой стране, настройка нормализации не будет отображаться в интерфейсе. |
Цель нормализации
Нормализация номеров телефонов необходима для приведения разнообразных форматов, предоставленных пользователем, к единому виду. Например, мы ожидаем получить российские номера в формате 7ХХХХХХХХХХ. Однако пользователь может передать номер в различных вариантах, таких как +7ХХХХХХХХХХ (в этом случае мы уберем плюс), 8ХХХХХХХХХХ (заменим 8 на 7) или без кода страны ХХХХХХХХХХ (добавим 7).
Реакция на ошибки
Если нормализация номера невозможна, например, когда передается нечто, не являющееся телефонным номером, мы либо помечаем этот номер (устанавливаем флаг phoneNormalizationStatus:ERROR), и все равно пытаемся создать кандидата с этим номером, либо пропускаем его (т.е. пытаемся создать кандидата без номера, на котором возникла ошибка) в зависимости от выбранного действия при нормализации.
В случае ошибки Не найдены номера телефонов для обзвона. Кандидат пропущен часто причиной является передача некорректных данных в качестве телефонного номера. Если необходимо, эту защиту можно отключить в настройках задания Включить проверку номеров, разрешив добавление любых номеров, за исключением пустых.
| Блок кода | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"id": {
"identity": "bf1fee...70dc544"
}
} |
Описание полей ответа:
...
Поле
...
Тип
...
Обязательно
...
Описание
...
id
...
Object
...
Да
...
-
identitystring
Да
...