Скачайте полное описание API «Сервер-клиент» (pdf)
Скачать
API Сервер-клиент. Описание
1 Принципы интеграции и обработка ошибок
1.1 Назначение
API «Сервер-клиент» (далее по тексту — Сервис) позволяет внешним приложениям:
-
взаимодействовать с Виртуальной АТС MANGO OFFICE (далее по тексту — ВАТС) отдельным пользователям, независимо от других пользователей,
т. е. каждое клиентское приложение получает информацию только о звонках данного пользователя; -
сохраняет информацию о звонках и событиях пользователя, если пользователь недоступен (к примеру, клиентское приложение недоступно);
-
и предоставляет сохраненную информацию для обработки клиентскому приложению.
Сервис позволяет реализовывать решения, построенные по принципу «сервер-клиент» (в отличие от API ВАТС для внешних приложений, которое построено по принципу «сервер-сервер»).
1.2 Требования совместимости и список поддерживаемых протоколов
Чтобы взаимодействовать с Сервисом, внешняя система должна обеспечивать:
-
Подключение выполнено через API коннектор;
-
Использование метода POST и GET для HTTP-запросов;
-
Поддержка протокола 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). Потребуется указать внутренний номер из ВАТС.
Важно! Только после этого сервис интеграций начнет обрабатывать звонки для данного пользователя.
3) когда внешней системе для конкретного пользователя необходимо начать взаимодействовать с Сервисом, тогда для этого пользователя необходимо получить ссылку на вебсокет, выполнив запрос «Получить вебсокет» (/channel/);
4) после успешного создания/открытия вебсокета, нужно, по полученному URL вебсокета, зарегистрировать пользователя в сессии вебсокета, выполнив запрос «Начать сессию вебсокета» (/session/register/).
Важно! После успешной регистрации пользователя, начнется передача Push-сообщений по звонкам пользователя по вебсокету, не сохраняясь в пропущенных событиях.
5) в любой момент времени проверить доступность к серверу интеграции можно выполнив запрос «Проверка статуса сервера» (/session/ping);
6) если необходимо выполнять звонки со стороны внешней системы, то следует использовать запрос инициации звонка (/callback);
7) если необходимо маршрутизировать звонки со стороны внешней системы, то следует использовать запрос «Перевести на сотрудника» (/route/async/), при этом результат выполнения отслеживать по событиям /route_result;
8) для получения записей разговоров следует использовать запрос на получение записи разговора (/record);
9) для отслеживания состояния звонков следует отслеживать события телефонии (/call);
10) для отслеживания наличия записей разговоров в звонках следует отслеживать события записи (/record);
11) для выполнения переводов звонка следует использовать запрос на перевод звонка (/transfer).
Важно! Завершение звонка выполняется на оконечном оборудовании/программном телефоне, и не доступно со стороны API.
2.2 Корректное завершение работы приложения пользователя
1) клиентское приложение завершает вебсокет сессию (вкладка браузера закрывается, выход из приложения);
2) клиентское приложение отправляет запрос завершения сессии вебсокета (/v1/session/unregister/) для конкретного пользователя ВАТС
3) Сервис накапливает события о вызовах для конкретного пользователя ВАТС;
4) внешнее приложение сможет в дальнейшем обработать накапливаемые события согласно разделу «Порядок получения пропущенных событий».
2.3 Порядок получения пропущенных событий
1) пользователь не залогинен в websocket-сессии;
2) все события, проходящие через систему, записываются для пользователя как пропущенные;
Важно! Речь идет именно о событиях, необработанных («пропущенных») внешним приложением, а не о статусе «пропущен» того или иного вызова.
3) после успешного создания вебсокет-соединения и выполнения запроса «Начать сессию вебсокета» (/v1/session/register) пользователем:
а) выполнить запрос /v1/session/register циклически, пока Result[code]=0. Если больше пропущенных событий нет, то Result[code]=109;
б) параметр LIMIT можно варьировать. Таймаут на запрос к Сервиса равен 1 минуте;
4) пропущенные события хранятся 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, например, как статистику или пропущенный вызов.
Остались вопросы? Напишите нам:
Мессенджеры
Оставьте заявку
- SIP телефоны стационарные
- SIP телефоны беспроводные
- Профессиональные гарнитуры