Документация пользователя

Настройка интеграции с универсальной АТС

Описание

Плагин обеспечивает интеграцию системы с любой АТС через пользовательскую прослойку (middleware). Он принимает HTTP‑запросы от middleware, обрабатывает события звонков (входящие, исходящие, смены состояний) и выполняет соответствующие действия в системе: создание/обновление записей о звонках, добавление задач, сделок, отправка всплывающих уведомлений сотрудникам.

Плагин поддерживает

• Инициацию исходящего звонка из системы
• Приём входящих событий от middleware
• Отправку результатов обработки на callback‑URL

Установка и настройка

В системе установите плагин и укажите необходимые настройки:

API endpoints

actionCall – инициация исходящего звонка

Метод: POST

Параметры (form-data):

• to – номер телефона получателя (обязательный)

Что делает:

• Получает внутренний номер текущего сотрудника через getShortNumberByUserId().
• Формирует телефонный номер.
• Отправляет на callbackUrl JSON‑команду:

    {
        "action":           "make_call",
        "to":               "+71234567890",
        "from_extension":   "101",
        "crm_user_id":      123
    }

• Ожидает от middleware ответ c полем call_id.
• Если включена настройка createRelationship, создаёт Контакт по звонку в системе.
• Отображает уведомление в системе.

Пример успешного ответа:

    {
        "unique_id":  "call_12345",
        "name":       "Название компании",
        "to":         "+71234567890",
        "from":       "101",
        "status":     "Connected",
        "toRelease":  "+71234567890",
        "pluginName": "universal_plugin_telephony"
    }

Ошибки: выбрасывается исключение (обрабатывается в системе), при этом на callbackUrl отправляется callback с ошибкой (см. раздел «Callback уведомления»).

actionInbound – приём событий от middleware

Метод: POST
Content-Type: application/json
Тело запроса: JSON‑объект с данными о событии.

Плагин читает php://input, декодирует JSON и обрабатывает событие в зависимости от состояния звонка.

Формат входящего JSON

Пример запроса:

    {
        "call_id":        "20250303_123456",
        "from_number":    "+74951234567",
        "direction":      "in",
        "call_state":     "ANSWERED",
        "user_extension": "101",
        "diversion":      "84951234567"
    }

Возвращаемый JSON при успехе:

    {
        "status": "ok",
        "call_id": "call_12345",
        "message": "Event processed"
    }

Возвращаемый JSON при ошибке:

    {
        "status": "error",
        "message": "Описание ошибки"
    }

После обработки (вне зависимости от результата) на «Ссылку для отправки результатов обработки событий» отправляется callback‑уведомление (см. раздел «Обработка событий»).

Обработка событий

RINGING (входящий звонок)

• Если определён сотрудник (через «Внутренний номер сотрудник»а или при включённом «Уведомлять только ответственного за контрагента»), этому сотруднику отправляется всплывающее уведомление о входящем звонке.
• Если сотрудник не определён, всплывающее уведомление о входящем звонке отправляется всем сотрудникам, указанным в настройках плагина.

ANSWERED (звонок принят)

• Если включена опция «Создавать контакт при звонке»:
  • Номер формируется в соответствии с правилами описанными в настройке «Международный формат номеров (E.164)»
  • Создаётся документ контакт.

HANGUP (звонок завершён)

• Формируется массив полей для обновления записи звонка:
  • ссылка на запись (call_record_url);
  • направление;
  • номера;
  • идентификаторы сотрудников.
• Если включена опция «Добавлять звонок в последнюю активную сделку контрагента» и найден контрагент, запись звонка добавляется в его последнюю активную сделку.

MISSED (пропущенный звонок)

• Если включена опция «Создавать задачу о пропущенном звонке для ответственного» и найден контрагент:
  • Создаётся задача «Пропущенный звонок».
  • Ответственным за задачу становится ответственный за контрагента (если есть) или сотрудник, на чей добавочный номер поступил звонок.

Callback уведомления

После обработки любого события (включая ошибки) плагин отправляет асинхронный POST‑запрос на «Ссылку для отправки результатов обработки событий» с телом:

    {
        "type":       "callback" | "error_callback",
        "response":   {
            "status":   "ok" | "error",
            "call_id":  "...",
            "message":  "..."
        },
        "timestamp":  1678901234
    }

• type: "callback" при успешной обработке, "error_callback" при ошибке.
• response: копия ответа, который был возвращён в синхронном ответе на событие.
• timestamp: время отправки (Unix timestamp).

Примеры интеграции

Middleware: отправка события о новом звонке

    curl -X POST https://crm.example.com/plugin/{{plugin_id}}/actionInbound \
        -H "Content-Type: application/json" \
        -d '{
            "call_id":          "ext_101_20250303_1234",
            "from_number":      "84951234567",
            "direction":        "in",
            "call_state":       "RINGING",
            "user_extension":   "101"
        }'

Middleware: ответ на команду make_call (ожидается плагином)

    {
        "call_id": "unique_call_id_from_ats"
    }