Создание задания

Метод: POST

Authorization: Bearer Token

URL: https://twin24.ai/cis/api/v1/telephony/autoCall

cURL

curl --location 'https://twin24.ai/cis/api/v1/telephony/autoCall' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ТОКЕН' \
--data '{
    "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
        }
    }
}'

Тело запроса в формате JSON

{
    "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	да	Режим запуска задания. Принимает значения: manual (Вручную) time (В указанное время)
startMoment	string	да, если startType = time	Дата и время начала обзвона. Принимает значения: ГГГГ-ММ-ДД чч:мм *Используется часовой пояс компании
scheduleId	string	нет	Идентификатор расписания обзвона
defaultExec	string	да	Тип звонящего. Всегда принимает значение robot
defaultExecData	string	да	uuid сценария, который будет использоваться в обзвоне ботом
secondExec	string	да	Действие, если робот запросил переадресацию. Принимает значения: end (Завершить) ignore (Ничего не делать) ch (Передать вызов на канал)
secondExecData	string	да, если secondExec = ch	uuid канала для перевода. Параметр нужен, если предыдущий параметр в значении ch
cidType	string	да	Определяемый номер. Принимает значения: default (По умолчанию для транка) gornum (Один номер) pool (Группа номеров)
cidData	string	да, если cidType = gornum или pool	id сущности, выбранной в cidType. Актуально для gornum и pool
callStrategy	string	нет	Последовательная стратегия (STEP_2_STEP) – для кандидата с несколькими номерами сначала осуществляются все попытки перезвонить на первый номер, затем производятся все попытки звонить на следующий его номер и так далее. Параллельная стратегия (PARALLEL) – для кандидата с несколькими номерами при неуспешном дозвоне на первый номер, следующий звонок будет производиться на второй номер и так далее. После чего будет сформирована очередь перезвонов. Для корректной работы параллельной стратегии по нескольким кандидатам CPS задания должен быть больше 1.
cps	float	да	Интенсивность обзвона. Может обозначаться как N звонков в секунду или как 1 звонок в N секунд. Для N звонков в 1 секунду вычисляется как 1+N/100, где N – желаемое число наборов номера в секунду (CPS). Например: Желаемое CPS = 3, тогда значение поля 1.03 (при N=3 вычисляется 1+3/100=1.03) ——————————— Для 1 звонка в N секунд вычисляется как 1-N/100, где N - 1 звонок в N секунд. Например: Желаемая интенсивность 1 звонок в 60 секунд, тогда значение поля 0.4 (при N=60 вычисляется 1-60/100=0.4)
checkPhone	boolean	нет	Проверка корректности формата номера при добавлении кандидата
phoneNormalization	string	нет	Определяет, активирован ли процесс нормализации. Если null, отключено, если RU — нормализация в российский формат. Подробнее о нормализации читайте ниже.
normalizationErrorAction	string	нет	Указывает действие при возникновении ошибки нормализации. Для этого параметра необходимо активировать нормализацию. Доступны следующие варианты: `IGNORE_NORMALIZATION_ERROR —` пропустить номер, вызвавший ошибку. `SET_NORMALIZATION_ERROR_FLAG —` добавить номер, отметив его как невозможный к нормализации. Подробнее о нормализации читайте ниже.
sendReportAfterFinish	boolean	нет	Отправлять ли отчет после завершения задания на Email
webhookUrls	Array[Object]	нет	URL адреса и события, по которым нужно отправить webhook
\| url	string	нет	URL адреса, куда будет отправлен webhook
\| partialResults	boolean	нет	Отправлять ли промежуточные результаты
\| delay	int	нет	Задержка перед отправкой webhook
\| events	Object	нет	Список событий, по которым нужно отправить webhook
\| \| EVENT	Object	нет	Объект события. Доступные события (подставляются вместо EVENT): CALL_ENDED – звонок завершен CANDIDATE_CHANGED – статус кандидата изменен CALL_REDIRECTED – звонок переведен на оператора RECALL_SCHEDULED – принудительно запланирован перезвон по кандидату EFFICIENCY_REACHED – принудительно установлен статус успешности звонка AUTOCALL_STATUS_CHANGED – статус задания на обзвон изменен Подробнее о 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	Режим системы определителя. Принимает значения: back (Фоновая) block (С блокировкой)
\| 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	Количество перезвонов

Ответ в формате JSON

{
    "id": {
        "identity": "bf1fee...70dc544"
    }
}

Описание полей ответа:

Поле	Тип	Обязательно	Описание
id	Object	Да	-
identity	string	Да	Идентификатор задания на обзвон

Нормализация

Настройка нормализации

Нормализация номеров телефонов предназначена для облегчения добавления кандидатов в задание.

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

Цель нормализации

Нормализация номеров телефонов необходима для приведения разнообразных форматов, предоставленных пользователем, к единому виду. Например, мы ожидаем получить российские номера в формате 7ХХХХХХХХХХ. Однако пользователь может передать номер в различных вариантах, таких как +7ХХХХХХХХХХ (в этом случае мы уберем плюс), 8ХХХХХХХХХХ (заменим 8 на 7) или без кода страны ХХХХХХХХХХ (добавим 7).

Реакция на ошибки

Если нормализация номера невозможна, например, когда передается нечто, не являющееся телефонным номером, мы либо помечаем этот номер (устанавливаем флаг phoneNormalizationStatus:ERROR), и все равно пытаемся создать кандидата с этим номером, либо пропускаем его (т.е. пытаемся создать кандидата без номера, на котором возникла ошибка) в зависимости от выбранного действия при нормализации.

В случае ошибки Не найдены номера телефонов для обзвона. Кандидат пропущен часто причиной является передача некорректных данных в качестве телефонного номера. Если необходимо, эту защиту можно отключить в настройках задания Включить проверку номеров, разрешив добавление любых номеров, за исключением пустых.

Быстрые ссылки

Дерево страниц

Создание задания

Нормализация

Настройка нормализации

Цель нормализации

Реакция на ошибки

Быстрые ссылки

Дерево страниц

Метод для создания задания на обзвон

Создание задания

Нормализация

Настройка нормализации

Цель нормализации

Реакция на ошибки