3CX Call Control API

Что такое Call Control API?

3CX Call control API — это простой и мощный инструмент, который позволяет управлять вызовами программно. Используя API, вы можете интегрировать функциональность АТС в сторонние приложения. Примеры приложений включают:

  • Внешнее управление вызовами: Инициируйте, отвечайте, переводите и завершайте вызовы программно из ваших приложений.
  • Интеграция с CRM: Автоматически инициируйте вызовы из CRM-системы, регистрируйте детали вызовов и оптимизируйте взаимодействие с клиентами.
  • Исходящие кампании: Настраивайте и подключайте собственные скрипты для исходящих кампаний и сложных стратегий вызовов.
  • Интеграция с ИИ: Используйте современные языковые модели, такие как Whisper API, для работы с входящими вызовами пользователей.
  • Автоматизация службы поддержки: Управляйте входящими вызовами в службу поддержки, направляйте их соответствующим операторам и отслеживайте метрики.

Настройка API интеграции

Из консоли администрирования в веб-клиенте перейдите в "Integrations > API":

  1. Нажмите кнопку "Add", чтобы создать новое клиентское приложение.
  2. Укажите "Client ID" (DN для доступа к точке маршрутизации, который также необходим для авторизации).
  3. При использовании области Call Control, установите флажок "3CX Call Control API Access" для этого приложения.
  4. Опционально укажите номера DID для точки маршрутизации.
  5. Опционально укажите дополнительные добавочные номера, которые нужно отслеживать с помощью API.
  6. После создания нового экземпляра API вы получите ключ API для сторонних приложений. Этот ключ будет показан только один раз, поэтому обязательно сохраните его.

Вы успешно завершили настройку АТС!

Обратите внимание: У вас должна быть лицензия 8SC+ Enterprise для использования 3CX Call Control API.

Как работает API

RESTful API

Call Control API предоставляет простые и адаптируемые конечные точки для выполнения операций с вызовами. Они разработаны, чтобы быть безопасными и не нарушать работу АТС.

Для дополнительной информации см. “3CX Call Control API Endpoint Specification”

WebSocket

Интеграция WebSocket и Call Control API - надежный канал связи реального времени между внешними приложениями и сервером АТС. WebSocket реализует взаимодействие между приложением и АТС для управления вызовами на основе событий и управления состоянием.

Simultaneous Usage of WebSocket and HTTP (GET/POST)

  • Гибкая коммуникация: WebSocket не заменяет традиционные методы HTTP. Вместо этого он дополняет их, действуя как выделенный канал для доставки событий. Приложения могут использовать запросы GET и POST для получения определенных данных или выполнения действий, однако WebSocket предназначен для получения событий в реальном времени. Такая гибкость позволяет приложению выбирать лучший метод в зависимости от задачи. Например, использовать WebSocket для обновлений в реальном времени и HTTP для прямых запросов.
  • Эффективный канал для событий: WebSocket можно использовать только для доставки событий. Обеспечивается эффективная коммуникация, когда передаются только необходимые обновления в реальном времени. Учитывая ограничение WebSocket на размер сообщения, сообщения имеют небольшой размер.

Технический обзор

Коммуникация WebSocket в Call Control API следует структурированному формату запросов и ответов, обеспечивая ясность и последовательность:

Запрос приложения (WebSocketRequest):

  • Приложения отправляют запросы в реальном времени через WebSocket - сообщение WebSocketRequest.
  • Каждый запрос включает:
  • RequestID: Идентификатор, предоставляемый внешним приложением для отслеживания ответа.
  • Path: Путь API (аналогичный тому, что используется в запросах HTTP GET) такой, как /callcontrol/{dn}, or /callcontrol/{dn}/participants/{id}.
  • RequestData: Это требуется для действий по управлению вызовами, таких как makecall или divert, и является необязательным для запросов GET.

Ответ сервера (WebSocketResponse):

  • Сервер отвечает сообщением WebSocketResponse, которое включает:
  • RequestID: Идентификатор запроса, гарантирующий, что внешнее приложение может сопоставить ответ с запросом.
  • Path: Путь запроса (например, /callcontrol/100).
  • StatusCode: Код состояния HTTP, указывающий на успех или неудачу запроса.
  • Response: Содержимое ответа, которое варьируется в зависимости от пути запроса.

События WebSocket (Канал уведомлений)

В Call Control API сервер отправляет события через WebSocket. Это событие является частью системы ExtenalCallFlowEventTypes.Response, разработанной для передачи ответов внешнему приложению в структурированном и последовательном виде. Вот как это работает:

Ответ сервера с ExternalCallFlowAppHookEvent

Когда отслеживаемые состояния DN изменяются, сервер отвечает событием внешнему приложению через WebSocket. Событие имеет следующий тип:

ExternalCallFlowAppHookEvent {

    EventType=0;

    Entity=<path as was specified in the request>;

    AttachedData=<WebSocketResponse>;

}

Объяснение полей:

  • EventType=5 (ENUM): Поле EventType - перечисляемое значение (ENUM), которое указывает тип события, связанного с состоянием. Оно помогает внешнему приложению понять природу события и отреагировать соответствующим образом.

Номер ENUM

Описание

0

Upsert

Сущность либо добавлена, либо обновлена.

1

Remove

Сущность была удалена.

2

DTMFstring

DTMF, предоставленный удаленной стороной.

ПРИМЕЧАНИЕ: Событие DTMFString является частью функциональности управления медиа. Приложение может получать события DTMF, только если они принадлежат самому приложению (т.е. между DN приложения и его удаленной стороной).

4

Response

Ответ на запрос, отправленный через WebSocket.

  • Entity: представляет конкретный путь запроса, который приложение сделало изначально. Этот путь совпадает с тем, что был указан в исходном запросе WebSocket (например, /callcontrol, /callcontrol/{dn} или /callcontrol/{dn}/participants).

Это помогает внешнему приложению узнать, к какой части API относится ответ.

  • AttachedData: содержит фактический WebSocketResponse от сервера. Этот объект включает важные детали, такие как идентификатор запроса, код состояния HTTP и данные ответа.

Примеры внешних приложений

Для получения подробных инструкций по настройке внешнего приложения для управления вызовами с помощью Call Control API, см. "Getting Started with External Call Flow Application Examples". Он включает следующие разделы:

  • Конфигурация АТС: Инструкции по добавлению клиентского приложения в веб-клиент 3CX, настройке API и получению ключа API.
  • Настройка внешнего веб-приложения: Шаги по настройке внешнего приложения, включая установку Node.js, загрузку необходимых файлов, запуск примеров (IVR, исходящая кампания, дайлер) и настройку приложения в вашей локальной среде.

Документ также рассматривает базовые примеры для управления вызовами, настройку пользовательского IVR, дайлера и исходящей кампании для интеграции с 3CX.

Дополнительная информация

Версия документа

Последнее обновление документа 13 мая 2025

https://www.3cx.ru/docs/call-control-api/