Скачайте полное описание API «Сервер-клиент» (pdf)
Скачать

API Сервер-клиент. Описание

Мы рекомендуем использовать это дополнительное АПИ в ситуации, когда основное API Виртуальной АТС использовать невозможно. API «Сервер-клиент» позволяет внешним приложениям взаимодействовать с Виртуальной АТС отдельным пользователям, независимо от других пользователей. Если Вам потребуются услуги по доработке API «Сервер-клиент», обращайтесь по адресу integration@mangotele.com.

⁠ ## 1 Принципы интеграции и обработка ошибок

1.1 Назначение

API «Сервер-клиент» (далее по тексту — Сервис) позволяет внешним приложениям:

  • взаимодействовать с Виртуальной АТС MANGO OFFICE (далее по тексту — ВАТС) отдельным пользователям, независимо от других пользователей, т. е. каждое клиентское приложение получает информацию только о звонках данного пользователя;
  • сохраняет информацию о звонках и событиях пользователя, если пользователь недоступен (к примеру, клиентское приложение недоступно);
  • и предоставляет сохраненную информацию для обработки клиентскому приложению.

Сервис позволяет реализовывать решения, построенные по принципу «сервер-клиент» (в отличие от API ВАТС для внешних приложений, которое построено по принципу «сервер-сервер»).

1.2 Требования совместимости и список поддерживаемых протоколов

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

  1. Подключение выполнено через API коннектор;
  2. Использование метода POST и GET для HTTP-запросов;
  3. Поддержка протокола SSL (https).

1.3 Доступ к функциям

Сервис доступен по ссылке:

https://api-client.mango-office.ru/api

Для того чтобы получить доступ к Сервису, внешняя система должна соответствовать требованиям совместимости, а также необходимо получить ключ доступа (token).

Сервис предоставляет внешней системе доступ к своим функциям без ограничений. Если внешней системе требуется разграничение доступа на уровне пользователей внешней системы, то это разграничение обеспечивает сама внешняя система.

1.4 Обработка ошибок

В случае некорректных данных или при возникновении ошибок обработки данных любой из методов Сервиса возвращает один из следующих ответов:

  • 200 — успешное выполнение
  • 4хх — неверный запрос или отсутствие в ответе данных
  • 500 — ошибка сервера

Возможные коды ошибок Сервиса являются подмножеством кодов результатов (см. «Список кодов результатов»).

2 Описание примеров использования Сервиса

2.1 Последовательность подключения Сервиса

  1. создать интеграцию, выполнив запрос создания интеграции (/integration/create), при этом получить ключ интеграции (token);

  2. для каждого пользователя внешней системы, для которого необходимо предоставить интеграцию, выполнить создать пользователя в интеграции, выполнив запрос создания пользователя в интеграции (/users/create). Потребуется указать внутренний номер из ВАТС.

Важно! Только после этого сервис интеграций начнет обрабатывать звонки для данного пользователя.

  1. когда внешней системе для конкретного пользователя необходимо начать взаимодействовать с Сервисом, тогда для этого пользователя необходимо получить ссылку на вебсокет, выполнив запрос «Получить вебсокет» (/channel/);

  2. после успешного создания/открытия вебсокета, нужно, по полученному URL вебсокета, зарегистрировать пользователя в сессии вебсокета, выполнив запрос «Начать сессию вебсокета» (/session/register/).

Важно! После успешной регистрации пользователя, начнется передача Push-сообщений по звонкам пользователя по вебсокету, не сохраняясь в пропущенных событиях.

  1. в любой момент времени проверить доступность к серверу интеграции можно выполнив запрос «Проверка статуса сервера» (/session/ping);

  2. если необходимо выполнять звонки со стороны внешней системы, то следует использовать запрос инициации звонка (/callback);

  3. если необходимо маршрутизировать звонки со стороны внешней системы, то следует использовать запрос «Перевести на сотрудника» (/route/async/), при этом результат выполнения отслеживать по событиям /route_result;

  4. для получения записей разговоров следует использовать запрос на получение записи разговора (/record);

  5. для отслеживания состояния звонков следует отслеживать события телефонии (/call);

  6. для отслеживания наличия записей разговоров в звонках следует отслеживать события записи (/record);

  7. для выполнения переводов звонка следует использовать запрос на перевод звонка (/transfer).

Важно! Завершение звонка выполняется на оконечном оборудовании/программном телефоне, и недоступно со стороны API.

2.2 Корректное завершение работы приложения пользователя

  1. клиентское приложение завершает вебсокет сессию (вкладка браузера закрывается, выход из приложения);

  2. клиентское приложение отправляет запрос завершения сессии вебсокета (/v1/session/unregister/) для конкретного пользователя ВАТС

  3. Сервис накапливает события о вызовах для конкретного пользователя ВАТС;

  4. внешнее приложение сможет в дальнейшем обработать накапливаемые события согласно разделу «Порядок получения пропущенных событий».

2.3 Порядок получения пропущенных событий

  1. пользователь не залогинен в websocket-сессии;

  2. все события, проходящие через систему, записываются для пользователя как пропущенные;

Важно! Речь идет именно о событиях, необработанных («пропущенных») внешним приложением, а не о статусе «пропущен» того или иного вызова.

  1. после успешного создания вебсокет-соединения и выполнения запроса «Начать сессию вебсокета» (/v1/session/register) пользователем:

а) выполнить запрос /v1/session/register циклически, пока Result[code]=0. Если больше пропущенных событий нет, то Result[code]=109;

б) параметр LIMIT можно варьировать. Таймаут на запрос к Сервиса равен 1 минуте;

  1. пропущенные события хранятся 2 недели до удаления из истории.

2.4 Порядок инициирования звонка callback

  1. у пользователя открыт софтфон или иное настроенное средство приема;

  2. выполняется запрос инициации звонка (/v1/callback);

  3. на средстве приема (открытого на шаге 1) появляется входящий звонок (с номера, указанного в DESTINATION_NUMBER);

  4. пользователь принимает звонок;

  5. система инициирует дозвон на указанный номер, начинают приходить события по звонку.

2.5 Порядок проигрывания записи

  1. осуществляется запись звонка более 6 секунд;

  2. после получения события записи (/record) со статусом AVAILABLE можно сохранить значение url для скачивания данной записи разговора;

  3. ВАТС формирует запись разговора, доступность записи может занимать время — более 5 минут в часы нагрузки;

  4. рекомендуется хранить ссылку на запись, а не саму запись;

  5. пользователь пытается прослушать запись — надо выполнить запрос по сохраненной ссылке.

2.6 Порядок перевода на ответственного сотрудника

  1. при получении входящего звонка на ВАТС Сервис отправляет событие телефонии (/ivr) в статусе APPEARED случайному пользователю, находящемуся в сессии вебсокет;

  2. получено событие с routeKey="/ivr";

  3. внешнее приложение осуществляет поиск ответственного по номеру телефона в своей системе хранения данных;

  4. если ответственный найден, то отправляется запрос «Перевести на сотрудника» (/v1/route) на внутренний номер ответственного;

  5. асинхронно по вебсокету приходит событие результата выполнения ВАТС перевода вызова (/route_result).

2.7 Звонки на группу

  1. происходит звонок на группу в ВАТС;

  2. один из сотрудников группы поднял трубку;

  3. остальные сотрудники получат событие телефонии (/call) с состоянием DISONNECTED и признаком is_group_disconnect=true

Получение события DISONNECTED c признаком is_group_disconnect=true означает, что звонок сотрудника был завершен по причине ответа на звонок другим сотрудником группы и не обрабатывать такой DISCONNECT, например, как статистику или пропущенный вызов.

Предыдущая
Эмулятор API Виртуальной АТС
Следующая
Описание API "Сервер-клиент"