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

1 Общие требования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 Правила версионности API1.1 Правила версионности API

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

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

POST /<version>/calltracking/externalCall

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

Параметры уведомления:

1. тело уведомления должно быть в формате raw JSON (content type: application/json);
2. параметры уведомления перечислены в таблице:

Пример уведомленияПример уведомления

POST 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 Обновление записи разговора3 Обновление записи разговора

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

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

В запросе следует указать <callId> — ID звонка в системе пользователя, ранее переданный в коллтрекинг в уведомлении о звонке.

Кроме этого, запрос содержит следующий параметр:

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

PUT 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": "[описание ошибки]"
  }
}