API для сторонних АТС

1 Общие требования

API коллтрекинга позволяет проинтегрировать (связать) коллтрекинг и внешнюю сторонюю АТС. Данный API предоставляет возможность:

  • передать в коллтрекинг данные о звонке, совершенном через стороннюю АТС;
  • передать в коллтрекинг url-адрес записи разговора.

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

Чтобы взаимодействовать с API, внешняя система должна:

  1. поддерживать протокол http(s), формат raw json;
  2. использовать методы POST и PUT для HTTPs-запросов;
  3. передавать запросы в следующем формате:

https://widgets-api.mango-office.ru/<version>/<service>/<method>[.<ext>]?<params>
где:

  • <type> - http-метод GET, POST, PUT или DELETE;
  • <version> - номер текущей версии API, например v1;
  • <service> - название раздела API, в котором выполняется действие, например, calltracking;
  • <method> - url-адрес ресурса, над которым выполняется действие;
  • <ext> - необязательная часть запроса, задает формат результата, по умолчанию данные передаются в формате JSON;
  • <params> - обязательные и необязательные параметры запроса.
  1. для авторизации запроса передавать в нем token, полученный в личном кабинете. Возможны два способа указать token, либо в параметрах:
    access_token=<token>

либо в http заголовках:
Authorization: Bearer <token>

1.1 Правила версионности API

  • Изменения в рамках одной мажорной версии обладают обратной совместимостью, которая заключается в следующем:
    • названия полей, их тип и порядок не меняются;
    • новые колонки попадают в конец (особенно это касается формата CSV);
    • перечисления (enums) могут расширяться, но не уменьшаться.
  • Изменения между мажорными версиями не обязаны обладать обратной совместимостью.

2 Уведомление о звонке со сторонней АТС

POST /<version>/calltracking/externalCall

Уведомление содержит информацию о вызове и его параметрах.
Параметры уведомления:

  1. тело уведомления должно быть в формате raw JSON (content type: application/json);
  2. параметры уведомления перечислены в таблице:
Название параметра Наличие Тип данных Описание Значение по умолчанию Примечание
callId required string ID звонка в системе пользователя. Для корректной работы должно быть уникально в пределах продукта коллтрекинга (но повторы допускаются) -
dateStart required YYYY-MM-DDTHH:MM:SSZ Дата и время начала звонка -
dateEnd required YYYY-MM-DDTHH:MM:SSZ Дата и время окончания звонка -
phoneTo required phone (E164) Куда был звонок -
phoneFrom optional phone (E164) Откуда был звонок пустая строка -
recordLink optional url Ссылка на звонок пустая строка Вы можете передать url в коллтрекинг также при помощи запроса на обновление записи разговора

Пример уведомления:
<type> https://widgets-api.mango-office.ru/v1/calltracking/externalCall<br></br>     access_token=weghjui675432wertyui8675ter<br></br>     widgetId=11078<br></br>     Content-Type=application/json<br></br>        {<br></br>        "callId":"2",<br></br>        "dateStart":"2020-08-19T08:16:10Z",<br></br>        "dateEnd":"2020-08-19T08:16:20Z",<br></br>        "phoneTo":"+74958784556",<br></br>        "phoneFrom":"" ,<br></br>        "recordLink": "http://adress.net"<br></br> } <br></br>

Результат:
В ответе на запрос приходит ID-номер запроса в коллтрекинге.
Параметры ответа:

  1. тело ответа в формате JSON;
  2. параметры ответа перечислены в таблице:
Название Наличие Тип данных Описание
status required string ok или error
requestId required string ИД запроса в системе
error optional json При ошибке возвращает ее код и описание

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

  • в результате успешной обработки уведомления:
    {status: 'ok', requestId: [значение]}

  • если обработка уведомления завершилась с ошибкой, то будет выдано следующее сообщение:
    {status: 'error', requestId: [значение], error: {code: [код ошибки, 'message': [описание ошибки]]}}

3 Обновление записи разговора

PUT /<version>/calltracking/externalCall/<callId>

Команда предназначена для добавления url-адреса записи разговора к данным о звонке, ранее полученным по уведомлению. При помощи данной команды, вы можете передать в коллтрекинг url-адрес записи разговора, если этого не было сделано ранее.

В запросе следует указать <callId> - это ID звонка в системе пользователя, ранее переданный в коллтрекинг в уведомлении о звонке. Кроме этого, запрос содержит следующий параметр:

Название Наличие Тип данных Описание
recordLink required url Ссылка на звонок

Пример запроса:
<type> https://widgets-api.mango-office.ru/v1/calltracking/externalCall/call2<br></br>     access_token=weghjui675432wertyui8675ter<br></br>     widgetId=11078<br></br>     Content-Type=application/json<br></br>        {<br></br>        "recordLink": "http://adress.net"<br></br>        }

Результат.
В ответе на запрос приходит ID-номер запроса в коллтрекинге.
Параметры ответа:

  1. тело ответа в формате JSON;
  2. параметры ответа перечислены в таблице:
Название Наличие Тип данных Описание
status required string ok или error
requestId required string ИД запроса в системе
error optional json При ошибке возвращает ее код и описание

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

  • в результате успешной обработки уведомления:
    {status: 'ok', requestId: [значение]}

  • если обработка уведомления завершилась с ошибкой, то будет выдано следующее сообщение:
    {status: 'error', requestId: [значение], error: {code: [код ошибки, 'message': [описание ошибки]]}}

Предыдущая
API импорта сделок из внешней системы в ДКТ
Следующая
JavaScript API. Описание методов