Управление звонками через API: различия между версиями
Дополнительные действия
AZykov (обсуждение | вклад) |
AZykov (обсуждение | вклад) |
||
| Строка 23: | Строка 23: | ||
Последний вариант с Webhook не является штатным решением, однако может быть реализован при помощи инструментов платформы. Наиболее удобным вариантом является разработка собственных сервисов, обрабатывающих события платформы и перенаправляющих их во внешние системы. Разработке на платформе посвещен [[:Категория:Курс Разработка приложений|отдельный курс]].</blockquote>В рамках данной статьи будут рассмотрены интеграционные возможности WebSocket и Long Polling. | Последний вариант с Webhook не является штатным решением, однако может быть реализован при помощи инструментов платформы. Наиболее удобным вариантом является разработка собственных сервисов, обрабатывающих события платформы и перенаправляющих их во внешние системы. Разработке на платформе посвещен [[:Категория:Курс Разработка приложений|отдельный курс]].</blockquote>В рамках данной статьи будут рассмотрены интеграционные возможности WebSocket и Long Polling. | ||
= Интеграция с помощью Long Polling = | |||
Данный способ интеграции является односторонним, т.е. внешняя система сама запрашивает текущее состояние звонков с некоторой периодоичностью. Внешняя система обрабатывает овтеты платформы и сохраняет данные. | |||
Для реализации этого подхода, используется объект '''/rest/v1/uc/calls''' и доступ к нему через REST API. | |||
= Интеграция с помощью WebSocket = | = Интеграция с помощью WebSocket = | ||
| Строка 39: | Строка 44: | ||
* Платформа Эра отправляет подписавшейся системе события звонков | * Платформа Эра отправляет подписавшейся системе события звонков | ||
* Внешняя система получает события, обрабатывает их, отображает результат пользователю (опционально) | * Внешняя система получает события, обрабатывает их, отображает результат пользователю (опционально) | ||
* При необходимости управления звонком, внешняя система | * При необходимости управления звонком, внешняя система осуществляет вызовы REST API /rest/v1/uc/calls | ||
[[Файл:Интеграция звонков через WebSocket.png|центр|безрамки|816x816пкс]] | [[Файл:Интеграция звонков через WebSocket.png|центр|безрамки|816x816пкс]] | ||
| Строка 45: | Строка 50: | ||
=== Получение данных и событий звонков === | === Получение данных и событий звонков === | ||
Получение данных осуществляется при помощи подписки (subscr) на события '''callevents:'''<syntaxhighlight lang="json"> | Получение данных осуществляется при помощи подписки ([https://vendor.era-platform.ru/docs/era/latest/api/websocket/user/subscr.html subscr]) на события '''callevents:'''<syntaxhighlight lang="json"> | ||
[ | [ | ||
"subscribe", | "subscribe", | ||
| Строка 57: | Строка 62: | ||
] | ] | ||
</syntaxhighlight>Набор объектов (абонентов), по которым будут поступать события зависит от фильтра objects, типа используемого WebSocket API и набора прав учетной записи. | </syntaxhighlight>Набор объектов (абонентов), по которым будут поступать события зависит от фильтра objects, типа используемого WebSocket API и набора прав учетной записи. | ||
После подписки, платформа автоматически начнет присылать события, связанные с изменениями звонков - начало и окончание диалога, изменение состояния звонка, информацию о записи разговора и т.д. | |||
Описание всех событий звонков, их структуры и свойств можно найти на [https://vendor.era-platform.ru/docs/era/latest/events/event_classes/callevents/index.html ресурсе Vendor]. | Описание всех событий звонков, их структуры и свойств можно найти на [https://vendor.era-platform.ru/docs/era/latest/events/event_classes/callevents/index.html ресурсе Vendor]. | ||
Внешняя система должна получать и обрабатывать эти события. В зависимости от бизнес-целей интеграции, данные о звонках и их состояниях могут быть сохранены во внешней системе, выведены пользователю в CTI-панели и т.д. | |||
=== Управление звонком === | === Управление звонком === | ||
Для отправки запросов на управление звонком, внешняя система использует вызовы REST API /rest/v1/uc/calls, так же как в примере с Long Polling. Все данные и идентификаторы для запросов передаются в состваве сообщений WebSocket. | |||
[[Категория:Интеграция с внешними системами]] | [[Категория:Интеграция с внешними системами]] | ||
Версия от 10:31, 22 июля 2025
Общая информация
В рамках данной статьи будет рассмотрены способы интеграции управления звонками из внешней системы (CRM, SD и т.д.).
Под управлением звонками в рамках данной статьи подразумевается следующий набор функционала:
- Получение внешней системой данных о совершаемых звонках
- Возможность инициирования нового исходящего звонка
- Возможность соверешения перевода
- Возможность перевода звонка в конференцию
- Возможность постановки и снятия звонка с удержания
- Возможность отправки DTMF-сигналов
- Возможность завершения звонка
- Возможность принятия звонка
Кроме этих основных функций, также крайне полезно иметь возможность прослушивания и скачивания записи разговора из внешней системы.
В рамках платформы Эра существует три основных подхода к интеграции, позволяющие реализовать описанный функционал:
- Интеграция по WebSocket - внешняя система и платформа обмениваются сообщениями в реальном времени
- Интеграция методом REST API Long Polling - внешняя система периодически запрашивает данные платформы и отправляет команды в одностороннем порядке
- Интеграция с помощью механизма Webhook - каждая из систем вызывает сервисы другой
При этом внешняя система может использовать комбинированный подход, например получая события из WebSocket, и отправляя команды с помощью REST API. Последний вариант с Webhook не является штатным решением, однако может быть реализован при помощи инструментов платформы. Наиболее удобным вариантом является разработка собственных сервисов, обрабатывающих события платформы и перенаправляющих их во внешние системы. Разработке на платформе посвещен отдельный курс.
В рамках данной статьи будут рассмотрены интеграционные возможности WebSocket и Long Polling.
Интеграция с помощью Long Polling
Данный способ интеграции является односторонним, т.е. внешняя система сама запрашивает текущее состояние звонков с некоторой периодоичностью. Внешняя система обрабатывает овтеты платформы и сохраняет данные.
Для реализации этого подхода, используется объект /rest/v1/uc/calls и доступ к нему через REST API.
Интеграция с помощью WebSocket
Детальное описание WebSocket API можно найти на ресурсе Vendor.
Интеграция данным способом подразумевает обмен сообщениями между двумя системами.
В рамках платформы существует два подхода к использования WebSocket API:
- Token-API - для интеграции server-server. В рамках обмена сообщениями передаются события по всем пользователям
- User-API - для интеграции client-server. В рамках обмена сообщениями передаются события конкретного пользователя
Набор доступных API также отличается, однако методы и события работы со звонками доступны везде.
Общий подход интеграции выглядит таким образом:
- Внешняя система подписывается на события callevents
- Платформа Эра отправляет подписавшейся системе события звонков
- Внешняя система получает события, обрабатывает их, отображает результат пользователю (опционально)
- При необходимости управления звонком, внешняя система осуществляет вызовы REST API /rest/v1/uc/calls
Получение данных и событий звонков
Получение данных осуществляется при помощи подписки (subscr) на события callevents:
[
"subscribe",
{
"qid": 0.105938272,
"id": "bcdebcde-bcde-bcde-bcde-bcdebcdebcde",
"events": ["callevents.*"],
"objects": ["11"],
"expires": 300
}
]
Набор объектов (абонентов), по которым будут поступать события зависит от фильтра objects, типа используемого WebSocket API и набора прав учетной записи.
После подписки, платформа автоматически начнет присылать события, связанные с изменениями звонков - начало и окончание диалога, изменение состояния звонка, информацию о записи разговора и т.д.
Описание всех событий звонков, их структуры и свойств можно найти на ресурсе Vendor.
Внешняя система должна получать и обрабатывать эти события. В зависимости от бизнес-целей интеграции, данные о звонках и их состояниях могут быть сохранены во внешней системе, выведены пользователю в CTI-панели и т.д.
Управление звонком
Для отправки запросов на управление звонком, внешняя система использует вызовы REST API /rest/v1/uc/calls, так же как в примере с Long Polling. Все данные и идентификаторы для запросов передаются в состваве сообщений WebSocket.