Подробное описание функций

Приём уведомлений и проверка подлинности

MANGO OFFICE отправляет уведомления методом POST в формате application/x-www-form-urlencoded. В теле запроса три поля:

Поле

Описание

vpbx_api_key

Уникальный код ВАТС (далее — код ВАТС)

json

Данные уведомления в виде строки JSON

sign

Подпись запроса

Подпись строится с помощью ключа для создания подписи 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

Признак в содержимом

Действие интеграции

Итог вызова (/events/summary)

Есть поле call_direction или entry_result

Создание или обновление активности «Звонок»

Запись добавлена (/events/record/added)

Есть непустое поле recording_id

Загрузка и обработка аудиозаписи

Статус записи (/events/recording)

Есть поле recording_state

Пропуск: загрузку запускает уведомление «Запись добавлена»

Прочие уведомления (в том числе промежуточные /events/call)

Не совпадают ни с одним признаком

Пропуск, причина выводится в лог; активность не создаётся

Уведомление без идентификатора звонка (entry_id) пропускается.

Активность создаётся только по итогу входящего (call_direction = 1) состоявшегося (entry_result = 1) звонка. Исходящие, внутренние и пропущенные звонки пропускаются. Активность не появляется в момент набора номера — только после завершения разговора.

Активность «Звонок» в карточке сделки или лида

В штатном последовательном сценарии на входящий состоявшийся звонок с определённым номером создаётся одна активность типа «Звонок» (call-activity); повторные уведомления ищут её по идентификатору звонка mango://entry/<entry_id>. При конкурентной обработке возможны дубли (см. Известные технические особенности). Активность отображается в виджете активностей сделки или лида. Карточка звонка — это карточка той же активности; ссылка «Открыть карточку звонка →» на неё хранится в HTML поля text активности.

Что заполняется

Значение

Тема

«Входящий звонок <номер>»

Дата и время

Время звонка из уведомления MANGO OFFICE

Статус активности

«Выполнена» (completed): звонок уже состоялся и не превратится в просроченную задачу

Родитель

Найденная или созданная сделка либо лид

Платформа звонка

mango

Идентификатор звонка

mango://entry/<entry_id>

Текст

Пометка о неоднозначности (если есть) и ссылка «Открыть карточку звонка →»

После обработки аудиозаписи в карточке звонка также видны:

  • аудиозапись — 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) хранится отдельно от статуса самой активности. Статус активности сразу равен «Выполнена» и означает, что звонок состоялся.

Статус

Когда устанавливается

Что видит пользователь

не заполнен

Уведомление о записи ещё не поступало

Активность без аудиозаписи и текста

downloading

Уведомление о записи принято, звонок передан в очередь аудиозаписей

Аудиозапись и текст пока отсутствуют

completed

Аудиозапись загружена и распознана, результат сохранён

mp3-файл, расшифровка, длительность и резюме, если оно построено

download-failed

Аудиозапись не получена или не прошла проверку либо повторы исчерпаны до загрузки

Аудиозапись и текст отсутствуют

transcription-failed

Аудиозапись получена, но расшифровка не получена

mp3-файл и длительность без текста — и при окончательном отказе сервиса распознавания, и после исчерпания повторов. Только статус, без файла, — если сохранить mp3-файл не удалось

Звонок в статусе completed повторно не загружается и не распознаётся, а отметка сбоя этот статус не перезаписывает. Исключение — одновременная обработка двух уведомлений одного звонка: результат последней обработки, в том числе transcription-failed, может заменить ранее сохранённый (см. Известные технические особенности).

Статусы download-failed и transcription-failed можно исправить: после устранения причины верните сообщение из очереди недоставленных или подайте уведомление о записи вручную (см. Восстановление из очереди недоставленных и Повторная загрузка аудиозаписи отдельного звонка). Сам MANGO OFFICE уведомления не повторяет.

Неудачная повторная попытка не стирает ранее сохранённые текст и резюме: при отметке сбоя записывается статус, а затем — полученные mp3-файл и длительность.

Важно

Статус ошибки в карточке не всегда означает наличие сообщения в очереди недоставленных. И наоборот, отсутствие статуса ошибки не гарантирует, что обработка продолжается. Проверяйте одновременно карточку, очереди и лог.

Безопасность и защита данных

Аспект

Описание

Подпись запросов

Каждое уведомление MANGO OFFICE проверяется по подписи на основе соли. Неподписанные и подделанные запросы отклоняются с кодом 401. Исходящие запросы к MANGO OFFICE подписываются тем же способом.

Хранение учётных данных

Код ВАТС и соль хранятся в секрете Citeck mango-api. Один и тот же секрет служит и для проверки входящих уведомлений, и для подписи запросов к MANGO OFFICE. Соль никуда не передаётся и не записывается ни в тело, ни в заголовки запросов.

Учётные данные не попадают в очереди

В очередь уведомлений передаётся только содержимое уведомления, без кода ВАТС и подписи. Аудио и учётные данные через брокер не передаются.

Маскирование в логе

В сообщениях об ошибках, стеках вызовов и телах ответов значения vpbx_api_key и sign заменяются на ***.

Доступ к настройкам

Просматривать и изменять вебхуки могут только администраторы и система.

Сетевая защита

MANGO OFFICE отправляет уведомления с фиксированного набора IP-адресов (см. IP-адреса MANGO OFFICE). Проверку IP-адресов Citeck сам не выполняет, поэтому белый список настраивается на уровне сети или шлюза.

Повтор перехваченного запроса

Подпись MANGO OFFICE не содержит отметки времени, поэтому перехваченный подлинный запрос можно отправить повторно. Маршрут ищет существующую активность по идентификатору звонка, но это не гарантирует отсутствие дублей при конкурентной обработке. Защитой служат HTTPS и белый список IP-адресов.

Распознавание речи внутри контура

Аудиозапись передаётся на настроенный endpoint stt-sidecar. В штатной конфигурации это сервис citeck-stt-sidecar внутри инсталляции; при смене URL проверьте, куда фактически отправляется аудио. Штатный сервис работает без собственной аутентификации и не должен быть доступен извне сети Citeck.

Хранение аудиозаписей

mp3-файл каждого обработанного звонка копируется в хранилище содержимого Citeck и хранится в активности звонка вместе с расшифровкой и резюме. Файл передаётся через временный файл (emodel/temp-file), который интеграция удаляет после успешной записи; временные файлы неудачных записей остаются в хранилище (см. Ресурсы и хранилище). Аудиозаписи в активностях интеграция не удаляет автоматически, а срок хранения аудиозаписей в MANGO OFFICE на эту копию не влияет. Срок хранения аудиозаписей определите в соответствии с требованиями вашей организации к персональным данным. Требования к объёму хранилища приведены в разделе Ресурсы и хранилище.

Предупреждение

Передача текста разговора языковой модели. Резюме строит LLM, подключённая в модуле Citeck AI. Ей передаются полный текст разговора, реплики с метками говорящих и тайм-кодами, число говорящих и длительность. Провайдер и модель задаются свойствами Citeck AI citeck.ai.call-recording.summary.provider и citeck.ai.call-recording.summary.model; если они не заданы, используется провайдер Citeck AI по умолчанию. Если это внешний облачный сервис, тексты разговоров с персональными данными клиентов передаются за пределы вашей инфраструктуры. Перед включением резюме согласуйте это с ответственным за обработку персональных данных или подключите модель, развёрнутую внутри контура.

Аудиозаписи, расшифровки и номера телефонов относятся к персональным данным. Порядок их обработки, в том числе уведомление абонентов о записи разговора, определяет ваша организация. Не включайте API-ключи, подписи запросов и содержимое аудиозаписей в общедоступные отчёты.

Интеграция сохраняет и передаёт следующие данные:

Где

Какие данные

Активность «Звонок»

Номер звонящего (в теме), время звонка, mp3-файл, расшифровка, длительность, резюме

Созданный лид

Номер звонящего в контактах, название, ссылка на контрагента

Лог микросервиса

Номер звонящего и ссылки на сделки, лиды и контрагентов в информационных сообщениях; содержимое уведомления (включая номер) в сообщении о потерянном уведомлении; тела ответов внешних сервисов и фрагмент ответа сервиса распознавания (до 200 символов) при ошибках

Очереди mango-events и mango-events-dlq

Исходное содержимое уведомления MANGO OFFICE: номера звонящего и вызываемого, внутренний номер сотрудника, линия

Очереди mango-recordings и mango-recordings-dlq

Описание звонка: номер звонящего, найденная сделка или лид, названия сделок, лидов и контрагентов из пометки о неоднозначности, ссылки на кандидатов, идентификаторы звонка и аудиозаписи

Провайдер 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 401, 403, 408, 425, 429. Дополнительно повторяется HTTP 404 при скачивании из MANGO OFFICE. Назначаются отложенные повторы.

Постоянная

Остальные HTTP 4xx на этих этапах, кроме отдельного правила Mango 404. HTTP 404 сервиса распознавания остаётся постоянной ошибкой. Автоматический повтор не назначается: при ошибке скачивания фиксируется download-failed, при постоянной ошибке распознавания маршрут сохраняет аудио без расшифровки. Отбракованное содержимое скачанного файла также может завершить обработку со статусом ошибки без попадания в очередь недоставленных.

Примечание

При 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. Автоматического восстановления таких уведомлений маршрут не выполняет.