Подробное описание функций
Приём уведомлений и проверка подлинности
MANGO OFFICE отправляет уведомления методом POST в формате application/x-www-form-urlencoded. В теле запроса три поля:
Поле |
Описание |
|---|---|
|
Уникальный код ВАТС (далее — код ВАТС) |
|
Данные уведомления в виде строки JSON |
|
Подпись запроса |
Подпись строится с помощью ключа для создания подписи vpbx_api_salt (далее — соль). MANGO OFFICE выдаёт соль вместе с кодом ВАТС, а в запросах её не передаёт.
Адрес уведомлений состоит из базового адреса, указанного в личном кабинете MANGO OFFICE, и добавленного к нему окончания /events/<тип>. Входящий вебхук Citeck принимает запросы и по базовому адресу, и по любому окончанию, поэтому в личном кабинете достаточно указать один адрес. Тип уведомления интеграция определяет не по окончанию адреса, а по содержимому поля json.
Подлинность запроса проверяется по подписи. Citeck вычисляет sha256(vpbx_api_key + json + vpbx_api_salt), где код ВАТС и соль берутся из секрета Citeck, и сравнивает результат с полем sign без учёта регистра. Подпись проверяется по полям формы запроса, а тело события Citeck берётся из поля json. Результат проверки:
подпись верна — Citeck отвечает HTTP 200 и публикует событие Citeck (
in-webhook-request) для обработки;подписи нет или она неверна — Citeck отвечает HTTP 401
Webhook signature is not valid, событие Citeck не создаётся;подпись есть, но нет поля
json— Citeck отвечает HTTP 401 с сообщением об отсутствующем параметре, событие Citeck не создаётся.
Полный перечень кодов ответа приведён в разделе Коды ответа вебхука.
Сразу после проверки уведомление помещается в устойчивую очередь RabbitMQ mango-events. Поиск сделки или лида, загрузка аудиозаписи и распознавание выполняются позже, в обработчиках очередей, поэтому MANGO OFFICE получает ответ без ожидания обработки.
Уведомления распознаются по содержимому:
Уведомление MANGO OFFICE |
Признак в содержимом |
Действие интеграции |
|---|---|---|
Итог вызова ( |
Есть поле |
Создание или обновление активности «Звонок» |
Запись добавлена ( |
Есть непустое поле |
Загрузка и обработка аудиозаписи |
Статус записи ( |
Есть поле |
Пропуск: загрузку запускает уведомление «Запись добавлена» |
Прочие уведомления (в том числе промежуточные |
Не совпадают ни с одним признаком |
Пропуск, причина выводится в лог; активность не создаётся |
Уведомление без идентификатора звонка (entry_id) пропускается.
Активность создаётся только по итогу входящего (call_direction = 1) состоявшегося (entry_result = 1) звонка. Исходящие, внутренние и пропущенные звонки пропускаются. Активность не появляется в момент набора номера — только после завершения разговора.
Поиск сделки или лида по номеру телефона
Нормализация номера
Номер звонящего (поле from.number итога вызова) приводится к нормализованным номерам в формате E.164 без знака «+». Правила нормализации:
строка делится на части по символам «,», «;», «#», «/», по переводу строки и по словам «доб», «доп», «вн», «ext» в любом регистре;
в каждой части остаются только цифры, поэтому номер можно записать в любом виде: с «+7» или «8», со скобками, дефисами и пробелами;
часть длиной от 10 до 15 цифр даёт нормализованный номер, остальные части отбрасываются, повторы удаляются;
к номеру из 10 цифр добавляется префикс 7;
в номере из 11 цифр ведущая 8 заменяется на 7.
Поэтому короткий добавочный номер (например, «доб. 422») отбрасывается, а второй полный номер, записанный после «/» или «доб», даёт второй нормализованный номер.
Номер в исходном виде (условный) |
Нормализованный номер |
|---|---|
|
|
|
|
|
|
Если номер скрыт или из него нельзя получить нормализованный номер (меньше 10 или больше 15 цифр, например короткий внутренний номер), сделка или лид не ищутся: активность и лид не создаются, в лог выводится сообщение.
Правила нормализации совпадают с правилами, по которым CRM вычисляет поле phoneDigits у сделок, лидов и контрагентов. Благодаря этому номер звонящего и номер в карточке совпадают, как бы номер ни был записан.
Порядок поиска
Поиск выполняется по источникам в таком порядке:
Сделки (
emodel/deal): по телефонам сделки и по телефонам её контрагента.Лиды (
emodel/lead), если активная сделка не найдена: по телефонам лида и по телефонам его контрагента.Если активных сделок и лидов нет, создаётся лид (см. Создание лида).
Приоритет у сделки безусловный: если найдена активная сделка, лиды не запрашиваются. Заранее заносить номер звонящего в CRM не обязательно.
Сделки и лиды в исключаемых статусах в выборе не участвуют:
Источник |
Исключаемые статусы |
|---|---|
Сделка |
«Завершена» ( |
Лид |
«Дисквалифицирован» ( |
Статусы по умолчанию соответствуют стандартной модели CRM Citeck. Приостановленные сделки и лиды (статус pause, «Пауза») считаются активными. Перечень статусов настраивается (см. Правила выбора сделки или лида).
Примечание
Лид в статусе «Проверка на спам» (spam_check) считается активным. Если в CRM включена AI-проверка на спам, новый лид, в том числе созданный интеграцией, попадает в этот статус, и повторный звонок с того же номера до окончания проверки привязывается к этому же лиду — второй лид не создаётся.
В каждом источнике рассматриваются не более 100 последних изменённых сделок или лидов, совпавших по номеру (о последствиях см. Ограничения). Сделки и лиды в исключаемых статусах отбрасываются уже после выборки.
Несколько совпадений
Если номеру соответствуют несколько активных сделок или несколько активных лидов, звонок привязывается к последней изменённой из них. В текст активности добавляется пометка вида:
[mango:ambiguous] Номер <номер> совпал с несколькими активными записями (<названия>). Звонок привязан к последней изменённой — <выбранная сделка или лид>.
Звонки с такой пометкой можно найти по маркеру [mango:ambiguous] и при необходимости перепривязать вручную (см. Ручная перепривязка звонка). В пометке перечислены названия найденных сделок или лидов, а ссылки на них выводятся в лог микросервиса.
Создание лида
Если активных совпадений нет, в том числе когда все совпадения находятся в исключаемых статусах, интеграция создаёт лид:
перед созданием номер ищется в справочнике контрагентов (
emodel/ecos-counterparty);если контрагент найден, он указывается в лиде, и лид получает его название;
если контрагентов с этим номером несколько, берётся последний изменённый, а в активность добавляется пометка
[mango:ambiguous] Номер … совпал с несколькими контрагентами (…). Лид создан с последним изменённым — ….;если контрагент не найден, лид называется «Входящий звонок
<номер>»;номер звонящего записывается в контакты лида как основной;
лид получает категорию обращения «Телефон» (
emodel/deal-request-category@phone);лид создаётся в рабочем пространстве
crm-workspace, ответственный менеджер не назначается (о видимости таких лидов см. Права пользователей).
Лид и активность «Звонок» передаются одним запросом на изменение записей со связью через alias, чтобы сервер создал их в общей транзакции. Перед созданием маршрут повторно ищет активность по идентификатору звонка и использует уже найденную. Это уменьшает риск частичного создания и дублей при повторе, но не гарантирует уникальность при параллельной обработке или неопределённом исходе сетевого вызова (см. Известные технические особенности).
Номер попадает в контакты лида, поэтому следующий звонок с того же номера может найти уже созданный лид. Это предполагает, что phoneDigits вычислен, лид входит в окно поиска и не переведён в исключаемый статус.
Активность «Звонок» в карточке сделки или лида
В штатном последовательном сценарии на входящий состоявшийся звонок с определённым номером создаётся одна активность типа «Звонок» (call-activity); повторные уведомления ищут её по идентификатору звонка mango://entry/<entry_id>. При конкурентной обработке возможны дубли (см. Известные технические особенности). Активность отображается в виджете активностей сделки или лида. Карточка звонка — это карточка той же активности; ссылка «Открыть карточку звонка →» на неё хранится в HTML поля text активности.
Что заполняется |
Значение |
|---|---|
Тема |
«Входящий звонок |
Дата и время |
Время звонка из уведомления MANGO OFFICE |
Статус активности |
«Выполнена» ( |
Родитель |
Найденная или созданная сделка либо лид |
Платформа звонка |
|
Идентификатор звонка |
|
Текст |
Пометка о неоднозначности (если есть) и ссылка «Открыть карточку звонка →» |
После обработки аудиозаписи в карточке звонка также видны:
аудиозапись — mp3-файл, который можно скачать;
резюме — краткое содержание разговора, если оно построено;
расшифровка — текст по репликам говорящих и полный текст;
длительность аудиозаписи в секундах;
статус обработки аудиозаписи.
Карточка звонка
В текущей версии формы типа «Звонок» карточка звонка состоит из двух колонок:
слева — «Информация о звонке»: тема, «Документ» (сделка или лид), дата, платформа звонка, длительность, статус обработки аудиозаписи, «Идентификатор звонка в телефонии» (
mango://entry/<entry_id>), «Примечание» (сюда попадают пометка о неоднозначности и ссылка на карточку), «Результат» и «Ответственный»;справа — панели «Аудиозапись», «Резюме звонка» и свёрнутая панель «Расшифровка».
Менеджер может изменить поля «Документ», «Результат» и «Ответственный». Остальные поля заполняет интеграция, они доступны только для чтения. Состав и подписи полей задаёт форма типа «Звонок» модели данных, поэтому они могут отличаться в зависимости от установленной версии.
Примечание
Блок «Работа менеджера» в форме звонка для работы интеграции не требуется.
Ручная перепривязка звонка
Чтобы перепривязать звонок к другой сделке или лиду, откройте карточку звонка, выберите нужную сделку или лид в поле «Документ» и сохраните карточку.
При повторной обработке уведомлений интеграция не перезаписывает тему, текст, статус и тип активности, а привязку к сделке или лиду не трогает, если она уже задана. Поэтому звонок, перенесённый вручную, остаётся на новом месте.
Загрузка аудиозаписи разговора
По уведомлению «Запись добавлена» интеграция находит активность звонка по идентификатору звонка и запрашивает файл у API MANGO OFFICE:
запрос
POST /vpbx/queries/recording/postподписывается так же, как уведомления (см. Приём уведомлений и проверка подлинности);MANGO OFFICE отвечает перенаправлением на временную ссылку, и интеграция автоматически скачивает файл по ней;
ссылка временная, поэтому в карточке хранится сам файл, а не ссылка.
Перед сохранением ответ проверяется:
пустые, текстовые, HTML-, JSON- и XML-ответы (даже с кодом HTTP 200), а также ответы, начинающиеся с символа
<или{, отклоняются;файл больше 50 МБ (52 428 800 байт) отклоняется;
ответ без указания типа содержимого принимается, только если он начинается как mp3-файл;
ответ с другим двоичным типом содержимого (например,
application/octet-stream) принимается без проверки формата.
Если ответ не прошёл проверку, у активности устанавливается статус download-failed, аудиозапись не сохраняется. Такая обработка завершается со статусом ошибки без попадания сообщения в очередь недоставленных.
Уведомление о записи никогда не создаёт активность само. Если активность звонка не найдена, уведомление отбрасывается (см. Доставка уведомлений и восстановление после простоя). Если аудиозапись этого звонка уже сохранена (статус completed), повторное уведомление ничего не загружает.
Файл может стать доступен через API позже самого уведомления. Поэтому HTTP 404 при скачивании из MANGO OFFICE считается временной ошибкой: звонок остаётся в обработке, а маршрут назначает отложенные повторы по расписанию 1, 2, 5, 10 и 30 минут. После исчерпания бюджета попыток устанавливается download-failed, сообщение попадает в mango-recordings-dlq. Это правило действует только для скачивания Mango: HTTP 404 сервиса распознавания считается постоянной ошибкой. Пока повтор уже ожидает в очереди, подавать то же уведомление вручную не требуется.
Распознавание речи
Загруженный файл передаётся сервису распознавания речи citeck-stt-sidecar (см. Сервис распознавания речи). Язык распознавания — русский. В активность записываются:
полный текст разговора;
текст по репликам в виде строк «
SPEAKER_00: …», «SPEAKER_01: …». Метки обозначают говорящих условно, это не имена сотрудника и клиента. Реплики разделяются по говорящим, только если в сервисе включена диаризация. Если сервис не вернул реплик, в это поле записывается полный текст;длительность в целых секундах. Если сервис не вернул корректную длительность, она вычисляется по заголовкам кадров mp3-файла; если не удалось и так, длительность не заполняется.
Ожидание ответа сервиса распознавания ограничено 30 минутами.
Если сервис окончательно отказал в распознавании (ответил ошибкой 4xx, кроме кодов 401, 403, 408, 425 и 429, или вернул ответ без текста), аудиозапись и её длительность сохраняются в карточке без текста со статусом transcription-failed. Временные сбои обрабатываются автоматическими повторами (см. Автоматические повторы).
Резюме разговора
Если расшифровка получена и не пуста, интеграция запрашивает у модуля Citeck AI (микросервис citeck-ai) краткое резюме. Резюме строит языковая модель (LLM), подключённая в Citeck AI. Ей передаются текст разговора, реплики с метками говорящих и тайм-кодами, число говорящих и длительность (о защите данных см. Безопасность и защита данных).
Резюме строится на языке разговора. Для короткого разговора это 1–2 предложения. Для содержательного — разделы «Ключевые темы», «Решения», «Задачи», «Открытые вопросы» и «Участники», если по ним есть что сказать. Разделы оформлены разметкой Markdown, а поле «Резюме звонка» показывает её как обычный текст, поэтому заголовки видны с символами «##».
Примечание
Резюме формирует языковая модель, и оно может быть неточным: в спорных случаях опирайтесь на расшифровку и аудиозапись.
Если модуль Citeck AI не установлен, выключен или ответил ошибкой, звонок сохраняется с аудиозаписью и расшифровкой, но без резюме: ошибка резюме не отменяет сохранение аудиозаписи и расшифровки. Звонки без речи и звонки без расшифровки на резюме не отправляются. Отказ при построении резюме не повторяется и не считается ошибкой обработки звонка.
Каждый звонок с непустой расшифровкой — отдельный запрос к LLM. Учитывайте это в расходах на провайдера.
Отдельного переключателя резюме для телефонии нет. Свойство citeck.ai.call-recording.enabled=false выключает резюме вместе с остальными функциями записи разговоров Citeck AI; звонки при этом сохраняются с аудиозаписью и расшифровкой.
Статусы обработки аудиозаписи
Статус обработки аудиозаписи (атрибут recording-aspect:recordingStatus) хранится отдельно от статуса самой активности. Статус активности сразу равен «Выполнена» и означает, что звонок состоялся.
Статус |
Когда устанавливается |
Что видит пользователь |
|---|---|---|
не заполнен |
Уведомление о записи ещё не поступало |
Активность без аудиозаписи и текста |
|
Уведомление о записи принято, звонок передан в очередь аудиозаписей |
Аудиозапись и текст пока отсутствуют |
|
Аудиозапись загружена и распознана, результат сохранён |
mp3-файл, расшифровка, длительность и резюме, если оно построено |
|
Аудиозапись не получена или не прошла проверку либо повторы исчерпаны до загрузки |
Аудиозапись и текст отсутствуют |
|
Аудиозапись получена, но расшифровка не получена |
mp3-файл и длительность без текста — и при окончательном отказе сервиса распознавания, и после исчерпания повторов. Только статус, без файла, — если сохранить mp3-файл не удалось |
Звонок в статусе completed повторно не загружается и не распознаётся, а отметка сбоя этот статус не перезаписывает. Исключение — одновременная обработка двух уведомлений одного звонка: результат последней обработки, в том числе transcription-failed, может заменить ранее сохранённый (см. Известные технические особенности).
Статусы download-failed и transcription-failed можно исправить: после устранения причины верните сообщение из очереди недоставленных или подайте уведомление о записи вручную (см. Восстановление из очереди недоставленных и Повторная загрузка аудиозаписи отдельного звонка). Сам MANGO OFFICE уведомления не повторяет.
Неудачная повторная попытка не стирает ранее сохранённые текст и резюме: при отметке сбоя записывается статус, а затем — полученные mp3-файл и длительность.
Важно
Статус ошибки в карточке не всегда означает наличие сообщения в очереди недоставленных. И наоборот, отсутствие статуса ошибки не гарантирует, что обработка продолжается. Проверяйте одновременно карточку, очереди и лог.
Безопасность и защита данных
Аспект |
Описание |
|---|---|
Подпись запросов |
Каждое уведомление MANGO OFFICE проверяется по подписи на основе соли. Неподписанные и подделанные запросы отклоняются с кодом 401. Исходящие запросы к MANGO OFFICE подписываются тем же способом. |
Хранение учётных данных |
Код ВАТС и соль хранятся в секрете Citeck |
Учётные данные не попадают в очереди |
В очередь уведомлений передаётся только содержимое уведомления, без кода ВАТС и подписи. Аудио и учётные данные через брокер не передаются. |
Маскирование в логе |
В сообщениях об ошибках, стеках вызовов и телах ответов значения |
Доступ к настройкам |
Просматривать и изменять вебхуки могут только администраторы и система. |
Сетевая защита |
MANGO OFFICE отправляет уведомления с фиксированного набора IP-адресов (см. IP-адреса MANGO OFFICE). Проверку IP-адресов Citeck сам не выполняет, поэтому белый список настраивается на уровне сети или шлюза. |
Повтор перехваченного запроса |
Подпись MANGO OFFICE не содержит отметки времени, поэтому перехваченный подлинный запрос можно отправить повторно. Маршрут ищет существующую активность по идентификатору звонка, но это не гарантирует отсутствие дублей при конкурентной обработке. Защитой служат HTTPS и белый список IP-адресов. |
Распознавание речи внутри контура |
Аудиозапись передаётся на настроенный endpoint |
Хранение аудиозаписей |
mp3-файл каждого обработанного звонка копируется в хранилище содержимого Citeck и хранится в активности звонка вместе с расшифровкой и резюме. Файл передаётся через временный файл ( |
Предупреждение
Передача текста разговора языковой модели. Резюме строит LLM, подключённая в модуле Citeck AI. Ей передаются полный текст разговора, реплики с метками говорящих и тайм-кодами, число говорящих и длительность. Провайдер и модель задаются свойствами Citeck AI citeck.ai.call-recording.summary.provider и citeck.ai.call-recording.summary.model; если они не заданы, используется провайдер Citeck AI по умолчанию. Если это внешний облачный сервис, тексты разговоров с персональными данными клиентов передаются за пределы вашей инфраструктуры. Перед включением резюме согласуйте это с ответственным за обработку персональных данных или подключите модель, развёрнутую внутри контура.
Аудиозаписи, расшифровки и номера телефонов относятся к персональным данным. Порядок их обработки, в том числе уведомление абонентов о записи разговора, определяет ваша организация. Не включайте API-ключи, подписи запросов и содержимое аудиозаписей в общедоступные отчёты.
Интеграция сохраняет и передаёт следующие данные:
Где |
Какие данные |
|---|---|
Активность «Звонок» |
Номер звонящего (в теме), время звонка, mp3-файл, расшифровка, длительность, резюме |
Созданный лид |
Номер звонящего в контактах, название, ссылка на контрагента |
Лог микросервиса |
Номер звонящего и ссылки на сделки, лиды и контрагентов в информационных сообщениях; содержимое уведомления (включая номер) в сообщении о потерянном уведомлении; тела ответов внешних сервисов и фрагмент ответа сервиса распознавания (до 200 символов) при ошибках |
Очереди |
Исходное содержимое уведомления MANGO OFFICE: номера звонящего и вызываемого, внутренний номер сотрудника, линия |
Очереди |
Описание звонка: номер звонящего, найденная сделка или лид, названия сделок, лидов и контрагентов из пометки о неоднозначности, ссылки на кандидатов, идентификаторы звонка и аудиозаписи |
Провайдер LLM (если включено резюме) |
Текст разговора, реплики, число говорящих, длительность |
Код ВАТС, подпись и соль не сохраняются ни в активности, ни в очередях, ни в логе. Сообщения в очередях недоставленных хранятся до ручного разбора. Срок хранения лога и этих сообщений определяется регламентом обслуживания системы и требованиями вашей организации к персональным данным.
Автоматические повторы
MANGO OFFICE не повторяет доставку уведомлений и может отправлять их параллельно, без гарантии порядка, поэтому надёжность обеспечивается очередями RabbitMQ и автоматическими повторами. В одном экземпляре маршрута очередь mango-events обрабатывается одним потребителем: более раннее полученное сообщение заканчивает обработку до следующего. Это не переставляет уведомления в нужный порядок: record/added, поступившее раньше summary, может быть отброшено (см. Доставка уведомлений и восстановление после простоя). Очередь аудиозаписей mango-recordings обрабатывается в два потока: долгое распознавание одного разговора не задерживает звонки других клиентов.
Аудиозаписи звонков
Первая попытка начинается сразу после получения сообщения из mango-recordings. При ошибке, допускающей повтор, выполняются ещё пять попыток с паузами 1, 2, 5, 10 и 30 минут между попытками. Это шесть попыток и 48 минут ожидания плюс время скачивания, расшифровки и сохранения. Время восстановления зависимостей и доставки брокером может дополнительно увеличить этот срок.
Ожидание проходит в устойчивых quorum-очередях mango-recordings-retry-<delayMillis>:
поток потребителя на время паузы освобождается;
очереди создаются при первом использовании: их отсутствие до первой ошибки нормально;
после истечения TTL RabbitMQ возвращает сообщение в
mango-recordings;номер попытки хранится в заголовке
mango-recording-retry-attempt, поэтому перезапуск приложения не сбрасывает счётчик повторов.
Исходное сообщение подтверждается только после подтверждённой публикации отложенного повтора. Если публикация не удалась, исходное сообщение остаётся необработанным для передачи в mango-recordings-dlq. Для этой схемы нужен RabbitMQ с поддержкой quorum at-least-once dead lettering (3.10+ с включённым stream_queue). Данные брокера должны храниться на постоянном томе.
Каждая новая попытка снова скачивает и расшифровывает аудиозапись. Перед повтором маршрут проверяет активность: если аудиозапись уже успешно обработана или активность удалена, повтор пропускается. При ошибке сохранения результата сначала выполняется один отдельный повтор через 5 секунд без повторной загрузки и распознавания; если он не помог, ошибка выходит на уровень обработки сообщения.
Доставка допускает дубли: сбой между подтверждением публикации повтора и подтверждением исходного сообщения может привести к повторной работе. Последствия одновременной обработки двух сообщений одного звонка описаны в разделе Известные технические особенности.
Какие ошибки повторяются
Тип ошибки |
Какие ошибки относятся и что происходит |
|---|---|
Временная |
При скачивании и вызове сервиса распознавания: сетевые ошибки ввода-вывода, тайм-ауты, HTTP 5xx и HTTP |
Постоянная |
Остальные HTTP 4xx на этих этапах, кроме отдельного правила Mango 404. HTTP |
Примечание
При 401/403 проверьте доступы и настройки интеграции: повтор сам по себе неверные настройки не исправляет.
После исчерпания отложенных повторов маршрут пытается установить download-failed или transcription-failed, а сообщение попадает в mango-recordings-dlq. Если аудиозапись была загружена, маршрут сохраняет то, что успел получить, тремя независимыми записями: mp3-файл с длительностью, резюме, текст с длительностью и статусом completed. Сбой одной записи не отменяет остальные. Если обновление активности тоже не удалось, её статус может остаться промежуточным. В очередь недоставленных и в лог передаётся исходная ошибка обработки, а не ошибка записи статуса или файла. Повреждённый JSON может попасть в очередь недоставленных без изменения активности: состояние звонка ещё не удалось прочитать.
Уведомления и первичная публикация
У mango-events отдельная политика: три повтора через 30, 60 и 120 секунд, затем mango-events-dlq. Эти короткие повторы выполняются внутри обработки уведомления, чтобы сохранить порядок уведомлений о завершении звонка и о готовности аудиозаписи. На это время остальные уведомления ждут в очереди.
При первичной публикации уведомления в очередь предусмотрены два повтора через 500 мс. Если публикация окончательно не удалась, в лог записываются ошибка is LOST и исходное уведомление для ручного восстановления.
Предупреждение
На этом пути есть окно потери: успешный HTTP-ответ вебхука не гарантирует последующую запись уведомления в RabbitMQ. Автоматического восстановления таких уведомлений маршрут не выполняет.