Подключение и настройка
Требования и предварительные условия
На стороне MANGO OFFICE
Подключён API-коннектор. Для него получены код ВАТС (
vpbx_api_key) и соль — ключ для создания подписи (vpbx_api_salt).Тариф и настройки API позволяют получать уведомления об итоге вызова (
/events/summary) и о добавлении аудиозаписи в облако (/events/record/added). Доступность уведомлений зависит от тарифа, её следует уточнить у MANGO OFFICE.Запись разговоров включена для нужных линий и сотрудников, и аудиозаписи сохраняются в облачное хранилище. Если аудиозаписи только отправляются на почту, уведомление о записи не придёт, а аудиозапись нельзя будет получить по API.
Примечание
Само создание сотрудника с добавочным номером не подтверждает готовность интеграции: для тестового сотрудника или направления должна быть включена запись разговоров, а используемые настройки и услуги ВАТС должны позволять получать аудиозапись через API.
На стороне Citeck
Компонент |
Назначение |
Обязательность |
|---|---|---|
Микросервис |
Приём уведомлений, маршрут обработки |
Обязательно |
Модуль CRM |
Типы сделок, лидов и контрагентов с вычисляемым атрибутом |
Обязательно |
Модель данных с типом «Звонок» ( |
Хранение звонка, аудиозаписи и расшифровки, форма карточки звонка |
Обязательно |
Рабочее пространство |
Размещение создаваемых лидов |
Обязательно |
Брокер RabbitMQ платформы |
Очереди уведомлений и аудиозаписей |
Обязательно |
Сервис распознавания речи |
Расшифровка аудиозаписей |
Обязательно для обработки аудиозаписей |
Модуль Citeck AI (микросервис |
Построение резюме |
Необязательно |
Тип «Звонок» и аспект recording-aspect поставляет модель данных платформы (ecos-model). Модуль citeck-ai нужен только для необязательного резюме, но не для скачивания и расшифровки. Сервис citeck-stt-sidecar и модуль Citeck AI доступны в Enterprise-версии Citeck.
Кроме того, должны выполняться следующие условия:
Вычисляемое поле
phoneDigitsесть у сделок и лидов (из контактов) и у контрагентов, и его значение вычислено у существующих записей (см. Шаг 1. Проверка данных CRM). Без него поиск по номеру ничего не находит, и на каждый звонок создаётся новый лид.Брокер RabbitMQ. Используется RabbitMQ платформы (источник данных
main-rabbitmq): на настроенном стенде отдельное подключение для MANGO OFFICE создавать не нужно. Перед запуском убедитесь, что RabbitMQ доступен. Условия:соединение без TLS: с TLS маршрут не запускается;
версия RabbitMQ 3.10 или новее с включённым флагом функциональности
stream_queue;маршрут сам объявляет свои очереди и exchange, поэтому штатному подключению нужны соответствующие права;
данные брокера хранятся на постоянном томе.
Модуль Citeck AI предоставляет источник резюме звонков
ai/call-summary. Для этого в модуле включается свойствоciteck.ai.call-recording.enabled=true.
Права пользователей
Лиды и активности создаются от имени системы. У созданного лида менеджер не указан, поэтому роль «Менеджер» по матрице прав лида получает группа менеджеров CRM (GROUP_crm-manager): лид виден всей группе как неразобранный.
Администратор системы или рабочего пространства без членства в группах CRM созданные лиды не видит, поэтому проверяйте интеграцию под пользователем из группы менеджеров или администраторов CRM. Ошибка «Нет доступа» сама по себе не означает, что лид не создан: проверьте ссылку, рабочее пространство и права.
Совместимость версий
Важно
Описание сверено с ecos-integrations 2.40.0-SNAPSHOT и свойством зависимости ecos.camel.version=1.18.0-SNAPSHOT. Это проверенная поставка, а не минимальная версия всех компонентов. Для более ранней версии отдельно проверьте наличие отложенных повторов, сохранения аудио при сбое распознавания и временной обработки HTTP 404 скачивания Mango.
Интеграция работает только при согласованных версиях компонентов платформы. Перед подключением убедитесь, что установлены:
Компонент |
Проверенная версия или требование |
Что в ней нужно интеграции |
|---|---|---|
|
Проверено: 2.40.0-SNAPSHOT |
Артефакты MANGO OFFICE, подпись и вложенные пути вебхука, отложенные повторы, обработка Mango 404 |
|
Согласованная с integrations поставка; проверено свойство |
Подпись запросов к API MANGO OFFICE, формирование тела запроса, проверка загруженного ответа, маскирование учётных данных в ошибках |
|
Версия, поставляющая аспект |
Хранение аудиозаписи, расшифровки и статуса; форма карточки звонка |
CRM ( |
Версия с вычисляемым полем |
Вычисляемое поле |
|
Сборка, принимающая |
Распознавание речи |
|
Версия с источником |
Резюме разговора |
Точные номера версий для вашей инсталляции уточните в поддержке Citeck.
Сервис распознавания речи
Сервис citeck-stt-sidecar распознаёт речь локальной моделью GigaAM и разделяет текст по говорящим (диаризация). Подробнее о сервисе — в статье «Микросервис для транскрипции аудио и диаризации». Требования к развёртыванию:
Параметр |
Требование |
|---|---|
Образ |
|
Память |
Около 1,5 ГБ после загрузки модели. Лимит памяти контейнера задавайте с запасом: при лимите 2 ГБ сервис может аварийно завершаться (код 137). |
Процессор |
1–2 ядра. Распознавание нагружает процессор, и его время растёт с длительностью разговора. |
Первый запуск |
Сервис скачивает модель (около 1,5 ГБ, 3–5 минут). Чтобы не скачивать её после каждого перезапуска, подключите постоянный том для кеша моделей. |
Диаризация |
Для разделения текста по говорящим задайте токен HuggingFace в переменной окружения |
Проверка |
Запрос |
Вызов из маршрута |
|
Сетевые требования
Входящий публичный HTTPS-адрес Citeck доступен из интернета с IP-адресов MANGO OFFICE и поддерживает TLS 1.2 согласно требованиям API MANGO OFFICE. Путь вебхука доступен без авторизации пользователя.
У микросервиса
ecos-integrationsесть исходящий HTTPS-доступ кapp.mango-office.ruи к ссылкам на файлы аудиозаписей, которые выдаёт MANGO OFFICE.Микросервис
ecos-integrationsимеет сетевой доступ к сервису распознавания речи.Если в личном кабинете MANGO OFFICE включено ограничение IP-адресов для запросов внешней системы, в список добавлен исходящий IP-адрес Citeck. Иначе запросы на загрузку аудиозаписей будут отклоняться.
Ресурсы и хранилище
Ресурс |
Требование |
|---|---|
Объём хранилища |
mp3-файл каждого обработанного звонка хранится в хранилище содержимого Citeck, поэтому объём растёт пропорционально числу и длительности звонков. Фактический размер аудиозаписи виден в логе в сообщении |
Память микросервиса |
При обработке аудиозапись целиком находится в памяти |
Настройка
Интеграция поставляется набором готовых артефактов. Перед запуском нужно заполнить секрет (код ВАТС и соль) и указать адрес сервиса распознавания речи для вашей инсталляции.
Важно
Маршрут поставляется остановленным (STOPPED). Сначала настройте доступы и адреса, затем запускайте маршрут, и только после этого указывайте адрес уведомлений в MANGO OFFICE. Уведомления, пришедшие при остановленном маршруте, теряются.
Шаг 1. Проверка данных CRM
Сделку или лид интеграция ищет только по заполненному вычисляемому полю phoneDigits. После установки или обновления CRM это поле вычисляется у существующих сделок, лидов и контрагентов фоновым пересчётом. Пересчёт идёт асинхронно и на больших базах занимает заметное время.
Выберите несколько сделок, лидов и контрагентов с заполненным телефоном и убедитесь, что у них заполнено поле
phoneDigits(например, запросом Records API к этому атрибуту). Для номера+7 (900) 000-00-00значение —79000000000.Если у сделок, лидов или контрагентов с телефоном поле пусто, дождитесь окончания пересчёта. Если поле так и не заполнилось, администратор платформы запускает пересчёт вычисляемых атрибутов (групповое действие
update-calculated-atts) для сделок, лидов и контрагентов.
Пока поле не заполнено, интеграция не находит существующие сделки и лиды и на каждый звонок создаёт новый лид.
Шаг 2. Подключение API-коннектора в личном кабинете MANGO OFFICE
В личном кабинете MANGO OFFICE откройте настройки API-коннектора (в зависимости от версии кабинета — «Интеграции» → «API коннектор» или «Настройки» → «API») и подключите его.
На странице API-коннектора скопируйте уникальный код ВАТС (
vpbx_api_key) и ключ для создания подписи (vpbx_api_salt).Убедитесь, что запись разговоров включена и аудиозаписи сохраняются в облачное хранилище.
Названия разделов личного кабинета приведены по документации MANGO OFFICE VPBX API версии 1.9 и могут отличаться в текущей версии кабинета.
Шаг 3. Заполнение секрета и конечных точек
В административном разделе заполните существующие артефакты (журналы «Секреты» и «Конечные точки», Рабочее пространство «Раздел администратора» — Модель):
Артефакт |
Настройка |
|---|---|
|
Тип |
|
URL |
|
Базовый URL сервиса распознавания, доступный из процесса интеграции. В проверенной поставке для Kubernetes задан |
Адреса журналов:
«Секреты» —
v2/journals?journalId=ecos-secrets&viewMode=table&ws=admin$workspace;«Конечные точки» —
v2/journals?journalId=endpoints&viewMode=table&ws=admin$workspace.
Пока секрет не заполнен, вебхук отвечает MANGO OFFICE ошибкой, а маршрут не запускается.
Примечание
localhost внутри контейнера не означает другой контейнер или хост. Проверяйте доступность конечной точки из той же среды, где работает ecos-integrations.
После любого изменения секрета или конечной точки перезапустите маршрут (см. Смена учётных данных API-коннектора).
Шаг 4. Проверка входящего вебхука
Поставляемый integrations/in-webhook@mango-webhook уже настроен на проверку подписи MANGO OFFICE. Переводить его на token-аутентификацию или добавлять ?token= к публичному адресу не требуется. Откройте журнал «Входящие вебхуки» (Рабочее пространство «Раздел администратора» — Интеграция) и проверьте конфигурацию.
Журнал доступен по адресу: v2/journals?journalId=in-webhook-journal&viewMode=table&ws=admin$workspace
При заполнении JSON ориентируйтесь на объект из текстового примера ниже; отображение экранированной строки в редакторе на скриншоте не является образцом для копирования.
token: emodel/secret@mango-api
actionType: toEvent
authType: signature
authParameter: ""
signatureConfig:
algorithm: sha256
payloadParam: json
signatureParam: sign
components:
- secret.username
- param.json
- secret.password
«Тип аутентификации» — «Подпись»;
в поле «Токен» выбран секрет
mango-api;«Действие» — «Трансформация в Events»;
«Конфигурация подписи (JSON)» — схема MANGO OFFICE:
{
"algorithm": "sha256",
"payloadParam": "json",
"signatureParam": "sign",
"components": ["secret.username", "param.json", "secret.password"]
}
В конфигурации components задаёт, из чего и в каком порядке собирается подпись, signatureParam — поле запроса с подписью, payloadParam — поле запроса, значение которого становится телом события Citeck. Как выполняется проверка подписи, описано в разделе Приём уведомлений и проверка подлинности.
Идентификатор mango-webhook изменять нельзя: на него ссылается маршрут обработки.
Шаг 5. Запуск маршрута
Откройте журнал «Camel DSL» (Рабочее пространство «Раздел администратора» — Интеграция). Журнал доступен по адресу:
v2/journals?journalId=ecos-camel-dsl&viewMode=table&ws=admin$workspace.Найдите маршрут
mango-call-recordings-syncи выполните действие «Запустить». Действие доступно администратору.Проверьте состояние
STARTEDи наличие потребителей у очередейmango-eventsиmango-recordings.
При запуске маршрут сам объявляет обменник и очереди RabbitMQ. Схему маршрута можно посмотреть действием «Открыть в редакторе» в журнале Camel DSL.
Примечание
После обновления микросервиса ecos-integrations проверьте состояние маршрута (см. Действия после обновления ecos-integrations).
Шаг 6. Адрес и уведомления в MANGO OFFICE
В настройках API ВАТС укажите базовый адрес вебхука, включая путь до mango-webhook. Маршрутизация обратного прокси стенда должна соответствовать выбранному варианту:
https://<домен-стенда>/gateway/integrations/pub/webhook/mango-webhook
https://<публичный-домен>/pub/webhook/mango-webhook
При указании адреса:
не указывайте только домен;
к базовому адресу MANGO OFFICE добавляет путь с типом уведомления, например
/events/summaryили/events/record/added; эти суффиксы в базовое поле не добавляются;для сертификата публичного центра сертификации используйте проверку доверенного сертификата;
если существующая внешняя система используется другой интеграцией, настройте отдельную запись внешней системы для Citeck, чтобы не прервать её работу.
Перед указанием адреса проверьте его доступность из внешней сети (пример для варианта через gateway):
curl -i -X POST https://<домен-стенда>/gateway/integrations/pub/webhook/mango-webhook/events/summary -d 'json={}'
Ожидаемый ответ — HTTP 401 Webhook signature is not valid: запрос дошёл до Citeck и был отклонён проверкой подписи, потому что подписи в нём нет. Ответы 404, 403, 502 или перенаправление на страницу входа означают, что путь закрыт шлюзом или прокси.
Разрешите отправку уведомлений об итоге вызова events/summary и о готовности файла аудиозаписи events/record/added. В интерфейсе с флажками «Не отправлять…» соответствующие флажки должны быть сняты. Промежуточные уведомления events/call и уведомления о состоянии записи events/recording текущему маршруту не нужны; по ним активность не создаётся. Остальные уведомления для этого сценария не требуются (о events/record/tagged см. Доставка уведомлений и восстановление после простоя). Проверьте, что тестовые номера не исключены фильтром отправки уведомлений.
Если перед Citeck стоит обратный прокси или межсетевой экран, путь вебхука и все пути под ним должны быть доступны без авторизации пользователя и разрешены для IP-адресов MANGO OFFICE (см. IP-адреса MANGO OFFICE).
Локальный стенд через HTTPS-туннель
Если ecos-integrations запущен на хосте на порту 8082, для временной проверки можно проксировать его через установленный cloudflared:
cloudflared tunnel --protocol http2 --url http://localhost:8082
Полученный публичный домен используйте с путём /pub/webhook/mango-webhook. При смене домена обновите адрес внешней системы в MANGO OFFICE. Процесс туннеля должен работать всё время тестирования.
Для постоянной эксплуатации нужен стабильный HTTPS-адрес; временный туннель не гарантирует непрерывную доставку.
Шаг 7. Проверочный звонок
Проверяйте под пользователем из группы менеджеров или администраторов CRM (см. Права пользователей).
Выполните входящий звонок на номер ВАТС, ответьте, произнесите тестовую фразу и завершите разговор. Текущий сценарий обрабатывает входящие отвеченные звонки:
call_direction=1,entry_result=1. Активность не ожидается сразу при наборе номера.Проверьте получение
summaryи создание активности «Входящий звонок<номер>» в карточке сделки или лида. Если номер не найден среди подходящих сделок или лидов, маршрут создаёт новый лид вcrm-workspace; при необходимости удалите его после проверки. При нескольких совпадениях выбирается наиболее недавно изменённый подходящий документ и добавляется отметка[mango:ambiguous].После готовности аудиозаписи проверьте
record/addedтого жеentry_id, скачивание, расшифровку, аудиофайл и длительность в карточке. Файл может стать доступен позже завершения звонка.Убедитесь, что пользователь CRM имеет доступ к рабочему пространству и документу через предусмотренные роли.
Сверьте время звонка в карточке со временем в личном кабинете MANGO OFFICE (см. Время звонка). Если время отличается ровно на 3 часа, сообщите в поддержку Citeck до ввода в эксплуатацию: исправление требует доработки интеграции.
Проверьте отсутствие новых сообщений в
mango-events-dlqиmango-recordings-dlq. Зафиксируйтеentry_idи ссылки на лид или сделку и активность для последующей диагностики.
Ориентиры по времени:
Этап |
Когда ожидать |
|---|---|
Активность в карточке сделки или лида |
Через несколько секунд после окончания звонка |
Аудиозапись и расшифровка |
После того как MANGO OFFICE поместит аудиозапись в облако и сервис распознавания её обработает. В зависимости от процессора распознавание занимает от нескольких секунд на минуту разговора до времени, сравнимого с длительностью разговора. |
Очередь в часы пик |
Одновременно обрабатываются две аудиозаписи, остальные ждут в очереди |
Когда проверять |
С учётом отложенных повторов (48 минут ожидания) статус |
Если активность не появилась, воспользуйтесь разделом Мониторинг и диагностика.
Дополнительная настройка
Настройка интервалов повторов
Параметры разрешает Camel через JVM system properties или переменные окружения, а не через application.yml Spring. Перечень параметров и значения по умолчанию приведены в разделе Параметры маршрута.
-Dmango.recording.retryDelaysMillis=60000,120000,300000,600000,1800000
MANGO_QUEUE_REDELIVERYDELAY=60000
После изменения параметров обеспечьте пересоздание Camel-контекста; при изменении параметров запуска JVM перезапустите приложение.
Значения mango.recording.retryDelaysMillis должны быть положительными числами. Ошибка в этом параметре нарушает обработку сбоев аудиозаписей.
Примечание
Уже опубликованные сообщения остаются в очередях с прежним TTL: изменение настройки не переносит их в новые очереди. Прежние очереди mango-recordings-retry-* автоматически не удаляются — после того как они опустеют, удалите их вручную.
Правила выбора сделки или лида
Правила выбора хранятся в YAML маршрута mango-call-recordings-sync, в объекте mangoResolvePolicy. Их можно изменить под модель CRM вашей организации. Правила задаются параметрами inactiveStatuses, candidatesPageSize, ambiguousMarker, ambiguityNoteTemplate и sourceNoteTemplates; их назначение и значения по умолчанию приведены в разделе Параметры маршрута.
В шаблонах пометок доступны подстановки:
Подстановка |
Значение |
|---|---|
|
Номер звонящего |
|
Названия найденных сделок, лидов или контрагентов |
|
Выбранная сделка, лид или контрагент |
Значения inactiveStatuses и sourceNoteTemplates — JSON-словари, записанные строкой в одинарных кавычках. Ключ — идентификатор источника (emodel/deal, emodel/lead, emodel/ecos-counterparty), значение — идентификаторы статусов через запятую (для sourceNoteTemplates — текст пометки). Пример — значение inactiveStatuses по умолчанию, в котором перечислены статусы из раздела Порядок поиска:
inactiveStatuses: '{"emodel/deal":"completed,refusal,dropout,old","emodel/lead":"disqualified,deal_creation","emodel/ecos-counterparty":""}'
Вне mangoResolvePolicy в YAML маршрута задаются:
порядок источников поиска;
рабочее пространство создаваемого лида (константа
LEAD_WORKSPACEв шагеmango-create-lead-for-call);общие коды HTTP-ответов, при которых загрузка и распознавание аудиозаписи повторяются (
recordingFailurePolicy.retryHttpStatuses); HTTP 404 скачивания Mango дополнительно обрабатывается отдельной веткой маршрута;наибольший размер аудиозаписи (
mangoRecordingGuard.maxSize).
Порядок изменения
Остановите маршрут действием «Остановить» в журнале Camel DSL.
Измените YAML маршрута и сохраните его.
Запустите маршрут действием «Запустить».
Сделайте контрольный звонок.
Предупреждение
Ошибка в правилах не мешает маршруту запуститься, но ломает обработку звонков. К таким ошибкам относятся неверный JSON, нечисловое или неположительное значение candidatesPageSize, удалённые ambiguousMarker или шаблон пометки (такая ошибка проявится на первом неоднозначном совпадении). Каждое затронутое уведомление повторяется три раза, задерживая остальные уведомления до трёх с половиной минут, и уходит в mango-events-dlq. После исправления верните такие уведомления из очереди недоставленных.
Важно
Правила хранятся в содержимом поставляемого маршрута. Если при обновлении ecos-integrations изменился поставляемый маршрут, ваши правки YAML перезаписываются (см. Действия после обновления ecos-integrations). Храните копию изменённого YAML вне Citeck.
Смена учётных данных API-коннектора
После любого изменения секрета mango-api или адреса конечной точки остановите и заново запустите маршрут mango-call-recordings-sync (действия «Остановить» и «Запустить» в журнале Camel DSL). Часть значений привязывается при создании Camel-контекста, поэтому до перезапуска могут использоваться прежние адреса или учётные данные. Проверка входящих уведомлений читает секрет при каждом запросе.
Что станет со звонком, аудиозапись которого не удалось загрузить из-за такого отказа, зависит от ответа MANGO OFFICE:
ответы 401, 403, 408, 425, 429 и 5xx считаются временными: назначаются отложенные повторы. Если скачивание не удалось за весь бюджет попыток, звонок получает статус
download-failed, а сообщение попадает вmango-recordings-dlq;HTTP 404 скачивания Mango также повторяется: файл может ещё не быть доступен по API. Даже если запись действительно отсутствует или уже удалена, сначала расходуется бюджет повторов;
ответ с кодом ошибки MANGO OFFICE в JSON и HTTP-кодом 2xx, а также остальные ответы 4xx считаются окончательными: звонок сразу получает статус
download-failed, а сообщение в очередь недоставленных не попадает.
Исключение для 404 относится только к загрузке из MANGO OFFICE. HTTP 404 конечной точки STT считается постоянной ошибкой: проверьте URL сервиса распознавания. Пока сообщение уже ожидает в mango-recordings-retry-*, повторно подавать уведомление вручную не требуется.
По документации MANGO OFFICE ошибка в запросе возвращается кодом 3xxx в JSON, а ответ 401 приходит только после превышения квоты неверных запросов. Поэтому при смене учётных данных часть звонков, скорее всего, получит статус download-failed без отложенных повторов. После перезапуска маршрута верните сообщения из mango-recordings-dlq (см. Восстановление из очереди недоставленных). Затем найдите звонки со статусом download-failed за время сбоя, сообщений которых нет в очереди недоставленных, и подайте для них уведомление о записи вручную (см. Повторная загрузка аудиозаписи отдельного звонка).
Действия после обновления ecos-integrations
При обновлении микросервиса поставляемые артефакты интеграции разворачиваются заново, если в новой версии они изменились. Изменённый маршрут разворачивается с содержимым из поставки и в состоянии STOPPED, поэтому ваши правки YAML (правила выбора, retryHttpStatuses, maxSize, рабочее пространство лида) перезаписываются. После каждого обновления:
Проверьте, что маршрут
mango-call-recordings-syncзапущен (STARTED).Сверьте YAML маршрута с сохранённой копией своих изменений и при необходимости повторите их.
Проверьте адреса конечных точек
mango-officeиstt-sidecarи заполненность секретаmango-api.Сделайте контрольный звонок.
Отключение интеграции
Удалите адрес внешней системы в настройках API-коннектора в личном кабинете MANGO OFFICE.
Дождитесь, пока опустеют очереди
mango-events,mango-recordingsиmango-recordings-retry-*.Остановите маршрут
mango-call-recordings-syncдействием «Остановить» в журнале Camel DSL.
Предупреждение
Если остановить маршрут, не убрав адрес в MANGO OFFICE, вебхук продолжит отвечать кодом 200, но уведомления никто не обработает. Они теряются без следа в логе, и MANGO OFFICE их не повторит. Сообщения, уже лежащие в очередях, сохраняются и обрабатываются после запуска маршрута.