Webhooks на прием данных о звонках из внешних источников : Call-tracking

Описание интеграции кол-трекинг со сторонними системами телефонии.

Маршруты и аутентификация

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

Тип данных	Способ получения
URL	Выдается по запросу, технической службой кол-трекинг

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

Параметр	Способ получения
PROVIDER_AUTH_TOKEN	Выдается по запросу, технической службой кол-трекинг
PROVIDER_NAME	Выдается по запросу, технической службой кол-трекинг

Структура запросов

Для загрузки в кол-трекинг данных о звонках используются POST запросы трех типов на выданный URL:

call_start - для оповещения о начале вызова;
call_answer - для оповещения о начале соединения;
call_end - для оповещения о завершении соединения.

Данные передаются в формате JSON. Ниже представлено описание основных параметров, которые должны быть включены в запрос:

call_start

POST /webhooks

Параметр	Тип данных	Описание
PROVIDER_NAME	string	Имя провайдера
PROVIDER_AUTH_TOKEN	string	токен аутентификации провайдера
USER_UID	string	Уникальный идентификатор клиента в системе кол-трекинг
caller	string	номер вызывающего абонента в международном формате (пример: "+375293771330").
transfer	string	номер телефона в международном формате, использующийся как рекламный номер кол-трекинг.
receiver	string	номер принимающего абонента в международном формате.
time	datetime	ISO 8601
pbx_id	string	уникальный идентификатор звонка
event_name	string	ивент состояния, должен принимать значение "call_start"

*Все параметры являются обязательными.

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

{
"PROVIDER_NAME": "Provider",
"PROVIDER_AUTH_TOKEN": "123dflmsdvpm123",
"USER_UID": "sadlem123m593",
"caller": "+375296001122",
"transfer": "+375447708855",
"receiver": "+375293330102",
"time": "2022-09-12T16:56:26.379Z",
"pbx_id": "15642334984212",
"event_name": "call_start",
}

call_answer

POST /webhooks

Параметр	Тип данных	Описание
PROVIDER_NAME	string	Имя провайдера
PROVIDER_AUTH_TOKEN	string	токен аутентификации провайдера
USER_UID	string	Уникальный идентификатор клиента в системе кол-трекинг
caller	string	номер вызывающего абонента в международном формате (пример: "+375293771330").
transfer	string	номер телефона в международном формате, использующийся как рекламный номер кол-трекинг.
receiver	string	номер принимающего абонента в международном формате.
time	datetime	ISO 8601
pbx_id	string	уникальный идентификатор звонка
event_name	string	ивент состояния, должен принимать значение "call_answer"

*Все параметры являются обязательными.

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

{
"PROVIDER_NAME": "Provider",
"PROVIDER_AUTH_TOKEN": "123dflmsdvpm123",
"USER_UID": "sadlem123m593",
"caller": "+375296001122",
"transfer": "+375447708855",
"receiver": "+375293330102",
"time": "2022-09-12T16:56:26.379Z",
"pbx_id": "15642334984212",
"event_name": "call_answer",
}

call_end

POST /webhooks

Параметр	Тип данных	Описание
PROVIDER_NAME	string	Имя провайдера
PROVIDER_AUTH_TOKEN	string	токен аутентификации провайдера
USER_UID	string	Уникальный идентификатор клиента в системе кол-трекинг
caller	string	номер вызывающего абонента в международном формате (пример: "+375293771330").
transfer	string	номер телефона в международном формате, использующийся как рекламный номер кол-трекинг.
receiver	string	номер принимающего абонента в международном формате.
time	datetime	ISO 8601
pbx_id	string	уникальный идентификатор звонка
event_name	string	ивент состояния, должен принимать значение "call_end"
duration	int	длительность звонка в секундах
audio_path	string	ссылка на запись разговора для воспроизведения
status	string	статус завершенного звонка. Доступные значения: answer = отвеченный вызов; noanswer = пропущенный вызов (принимающий абонент не поднял трубку) busy = принимающий абонент занят cancel_caller = вызывающий абонент отменил вызов cancel_receiver = принимающий абонент отменил вызов unavailable = вызываемый абонент недоступен или в не зоны действия сети

*Все параметры являются обязательными.

Пример запроса для вызова, который был отвечен:

{
"PROVIDER_NAME": "Provider",
"PROVIDER_AUTH_TOKEN": "123dflmsdvpm123",
"USER_UID": "sadlem123m593",
"caller": "+375296001122",
"transfer": "+375447708855",
"receiver": "+375293330102",
"time": "2022-09-09T18:31:42+03",
"pbx_id": "15642334984212",
"event_name": "call_start",
"duration": 56,
"audio_path": "https://calltracking.freshdesk.com/a/solutions/articles/72000576278/edit",
"status": "answer"
}

Пример запроса для вызова, который не был отвечен:

{
"PROVIDER_NAME": "Provider",
"PROVIDER_AUTH_TOKEN": "123dflmsdvpm123",
"USER_UID": "sadlem123m593",
"caller": "+375296001122",
"transfer": "+375447708855",
"receiver": "+375293330102",
"time": "2022-09-09T18:31:42+03",
"pbx_id": "15642334984212",
"event_name": "call_start",
"duration": 0,
"audio_path": "https://calltracking.freshdesk.com/a/solutions/articles/72000576278/edit",
"status": "noanswer"
}

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

{
"PROVIDER_NAME": "Provider",
"PROVIDER_AUTH_TOKEN": "123dflmsdvpm123",
"USER_UID": "sadlem123m593",
"caller": "+375296001122",
"transfer": "+375447708855",
"receiver": "+375293330102",
"time": "2022-09-09T18:31:42+03",
"pbx_id": "15642334984212",
"event_name": "call_start",
"duration": 0,
"audio_path": "https://calltracking.freshdesk.com/a/solutions/articles/72000576278/edit",
"status": "busy"
}

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

{
"PROVIDER_NAME": "Provider",
"PROVIDER_AUTH_TOKEN": "123dflmsdvpm123",
"USER_UID": "sadlem123m593",
"caller": "+375296001122",
"transfer": "+375447708855",
"receiver": "+375293330102",
"time": "2022-09-09T18:31:42+03",
"pbx_id": "15642334984212",
"event_name": "call_start",
"duration": 0,
"audio_path": "https://calltracking.freshdesk.com/a/solutions/articles/72000576278/edit",
"status": "cancel_receiver"
}

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

call_unavailable_json = {
"PROVIDER_NAME": "Provider",
"PROVIDER_AUTH_TOKEN": "123dflmsdvpm123",
"USER_UID": "sadlem123m593",
"caller": "+375296001122",
"transfer": "+375447708855",
"receiver": "+375293330102",
"time": "2022-09-09T18:31:42+03",
"pbx_id": "15642334984212",
"event_name": "call_start",
"duration": 0,
"audio_path": "https://calltracking.freshdesk.com/a/solutions/articles/72000576278/edit",
"status": "unavailable"
}

Ограничения

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

Период действия ограничения	Максимальное количество событий
1 секунда	100
1 сутки	25000

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

Возвращаемые значения

Пример ответа в случае успешного запроса:

{
    "status_code": 200,
    "staus": "Oк",
    "message": "Ок"
}

Пример ответа в случае ошибки:

{
    "status_code": 403,
    "status": "Fail",
    "errors": "Dublicate pbx_id [15642334984212]"
}

Ответ	Код	Описание
{status: ok }	200	Событие обработано
{status: fail, errors: "Missing require params [*]"}	400	Неверный запрос, отсутствует один из параметров
{status: fail, errors: "Can’t parse params"}	400	Неверный тип данных, либо недопустимое значение в передаваемых параметрах
{status: fail, errors: "Invalid uid"}	401	Неверный user_uid
{status: fail, errors: "Invalid provider token"}	401	Неверный токен провайдера
{status: fail, errors: "Requests limit"}	403	Превышен лимит на отправку событий
{status: fail, errors: "Duplicate pbx_id [*]"}	403	Звонок с указанным pbx_id уже существует (для одинакового типа события, например: 2 cобытия call_start с одинаковым pbx_id)
{status: fail, errors: "Wrong transfer number for this uid"}	403	Указанный номер кол-трекинг не принадлежит данному пользователю

Перечень ответов и ошибок будет дополняться по мере доработки решения.

Webhooks на прием данных о звонках из внешних источников Печать

Статьи по теме