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> - обязательные и необязательные параметры запроса.

4) для авторизации запроса передавать в нем 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) параметры уведомления перечислены в таблице:
Пример уведомления:
<type> https://widgets-api.mango-office.ru/v1/calltracking/externalCall
    access_token=weghjui675432wertyui8675ter
    widgetId=11078
    Content-Type=application/json
       {
       "callId":"2",
       "dateStart":"2020-08-19T08:16:10Z",
       "dateEnd":"2020-08-19T08:16:20Z",
       "phoneTo":"+74958784556",
       "phoneFrom":"" ,
       "recordLink": "http://adress.net"
}


Результат:
В ответе на запрос приходит ID-номер запроса в коллтрекинге.
Параметры ответа:
1) тело ответа в формате JSON;
2) параметры ответа перечислены в таблице:
Пример ответа:
- в результате успешной обработки уведомления:
{status: 'ok', requestId: [значение]}

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

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

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

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

В запросе следует указать <callId> - это ID звонка в системе пользователя, ранее переданное в коллтрекинг в уведомлении о звонке. Кроме этого, запрос содержит следующий параметр: Пример запроса:
<type> https://widgets-api.mango-office.ru/v1/calltracking/externalCall/call2
    access_token=weghjui675432wertyui8675ter
    widgetId=11078
    Content-Type=application/json
       {
       "recordLink": "http://adress.net"
       }

Результат.
В ответе на запрос приходит ID-номер запроса в коллтрекинге.
Параметры ответа:
1) тело ответа в формате JSON;
2) параметры ответа перечислены в таблице:
Пример ответа:
- в результате успешной обработки уведомления:
{status: 'ok', requestId: [значение]}

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