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

Скачать

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

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

⁠

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, например, как статистику или пропущенный вызов.