Как работает интеграция

Интеграция входит в микросервис ecos-integrations и собрана из штатных механизмов Citeck: входящего вебхука, секрета, конечных точек и маршрута Camel DSL mango-call-recordings-sync. Уведомления MANGO OFFICE поступают во входящий вебхук mango-webhook и обрабатываются через RabbitMQ.

Термины

Термин

Значение

ВАТС

Виртуальная АТС MANGO OFFICE.

Код ВАТС

Уникальный код ВАТС (vpbx_api_key), API-ключ, который выдаётся при подключении API-коннектора.

Соль

Ключ для создания подписи (vpbx_api_salt). Выдаётся вместе с кодом ВАТС и в запросах не передаётся.

Событие

То, что произошло в ВАТС: например, завершился звонок или аудиозапись попала в облачное хранилище.

Уведомление

POST-запрос, который MANGO OFFICE отправляет во внешнюю систему о событии в ВАТС.

Уведомление о записи

Уведомление «Запись добавлена» (/events/record/added): аудиозапись помещена в облачное хранилище. Доступность файла через API может запаздывать.

Событие Citeck

Событие платформы in-webhook-request, которое входящий вебхук создаёт из принятого уведомления.

entry_id

Идентификатор звонка в MANGO OFFICE. Общий для всех уведомлений одного звонка.

recording_id

Идентификатор аудиозаписи в MANGO OFFICE.

Очередь недоставленных сообщений (DLQ)

Очередь RabbitMQ, в которую попадают сообщения, не обработанные после всех повторов. Разбирается вручную.

Уведомления MANGO OFFICE

О каждом звонке интеграция получает от MANGO OFFICE два отдельных уведомления:

Уведомление

Адрес

Описание

Итог вызова

/events/summary

Приходит по завершении звонка. Содержит номер звонящего, направление и результат звонка.

Запись добавлена

/events/record/added

Приходит о помещении аудиозаписи разговора в облачное хранилище. Если API скачивания ещё отвечает HTTP 404, интеграция назначает отложенный повтор.

Примечание

Номера звонящего в уведомлении о записи нет, а идентификатора аудиозаписи нет в итоге вызова. Поэтому интеграция связывает оба уведомления по общему идентификатору звонка MANGO OFFICE (entry_id): итог вызова создаёт активность, а уведомление о записи дополняет её.

Жизненный цикл звонка

        sequenceDiagram
    participant M as MANGO OFFICE
    participant C as Интеграция (ecos-integrations)
    participant R as CRM Citeck
    participant S as Распознавание речи
    participant A as Citeck AI
    M->>C: Итог вызова (summary)
    C-->>M: HTTP 200
    C->>R: Поиск сделки или лида по номеру
    C->>R: Создание активности «Звонок»
    M->>C: Запись добавлена (record/added)
    C-->>M: HTTP 200
    C->>R: Статус «аудиозапись загружается»
    C->>M: Запрос аудиозаписи
    M-->>C: Файл mp3
    C->>S: Аудиозапись
    S-->>C: Текст и реплики
    C->>A: Текст разговора
    A-->>C: Резюме
    C->>R: Аудиозапись, расшифровка, резюме, статус «готово»
    
  1. Приём уведомления. MANGO OFFICE отправляет уведомление на адрес входящего вебхука Citeck. Citeck проверяет подпись запроса, сразу отвечает MANGO OFFICE и помещает уведомление в очередь уведомлений (см. Приём уведомлений и проверка подлинности).

  2. Разбор уведомления. Обработчик очереди определяет тип уведомления по его содержимому. Дальше обрабатываются только итог входящего состоявшегося звонка и уведомление о готовой аудиозаписи; остальные уведомления пропускаются, а причина выводится в лог.

  3. Поиск сделки или лида. Номер звонящего из итога вызова приводится к единому формату, после чего в CRM ищется активная сделка, а если её нет — активный лид. Если активных совпадений нет, создаётся новый лид — одним запросом вместе с активностью из шага 4 (см. Поиск сделки или лида по номеру телефона).

  4. Создание активности. К найденной или созданной сделке либо лиду привязывается активность «Звонок» в статусе «Выполнена» с темой «Входящий звонок <номер>» и датой звонка (см. Активность «Звонок» в карточке сделки или лида).

  5. Постановка аудиозаписи в работу. По уведомлению о записи интеграция находит активность этого звонка, устанавливает статус обработки аудиозаписи downloading и передаёт звонок в очередь аудиозаписей.

  6. Загрузка аудиозаписи. Обработчик очереди аудиозаписей запрашивает mp3-файл у MANGO OFFICE подписанным запросом и проверяет ответ. HTTP 404 этого запроса считается временной недоступностью записи и проходит отложенные повторы (см. Загрузка аудиозаписи разговора).

  7. Распознавание речи. Файл передаётся сервису распознавания, который возвращает полный текст, реплики с метками говорящих и длительность (см. Распознавание речи).

  8. Резюме. Если расшифровка не пустая, интеграция запрашивает у Citeck AI краткое резюме разговора. Этот шаг необязательный (см. Резюме разговора).

  9. Сохранение и статус. В активность записываются mp3-файл, расшифровка, длительность, резюме и итоговый статус completed. При окончательном отказе вместо него устанавливается download-failed или transcription-failed; во втором случае загруженный mp3-файл и длительность всё равно сохраняются (см. Статусы обработки аудиозаписи и Автоматические повторы).