@besales/mcp 0.48.0 → 1.0.0-beta.4

package/dist/resources/docs/platforms.md

@@ -1,519 +1,149 @@
-# 11. Платформы (каналы связи)
-
-> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/11-platforms.md` — копия для MCP doc-bridge (v1.5 Increment 6b). Синкать при изменении оригинала.
->
-> ⚠️ **MCP-контекст:** это доменная справка, написанная для людей/админ-UI. В MCP-сессии ты выполняешь те же операции **через besales_* tools**, а не через UI (drag-n-drop, клики в админке). Где текст ниже говорит «клиент/админ делает X через UI» — это «что должно получиться»; механику бери из tool (напр. загрузка файла → `besales_file_upload_request`; документ в knowledge → `besales_knowledge_document_upload`; сайт → `besales_knowledge_website_add`) + из workflow-ресурсов. Внутренние ссылки `[NN-name.md]` — относительные пути исходной доки, через MCP НЕ резолвятся: ищи `besales://docs/<slug>` или concept-resource.
-
-## 1. Назначение
-
-`Platform` — это «канал», через который бот общается с пользователями. Каждая платформа — один внешний account/bot/instance. Animaly поддерживает **13 типов** платформ (`PlatformType`): Telegram Bot, Telegram Personal, Wazzup (WhatsApp), Avito, Instagram DM, VKontakte, SmsGorod (SMS), Web Widget, Bitrix24 Bot, Salebot, **GetCourse**, Telephony и External API.
-
-> Старые цифры «10» и «11» устарели. GetCourse, Telephony и External API — самостоятельные значения `PlatformType`. Наличие типа в runtime не означает, что MCP умеет провизионировать его: актуальный поддерживаемый набор возвращает схема `besales_platform_create_init`.
-
-## 2. Общая структура `Platform`
-
-```json
-{
-  "id": "uuid",
-  "type": "TelegramBot",
-  "name": "Главный Telegram-бот",
-  "isActive": true,
-  "isAiEnabled": true,
-  "timezone": "Europe/Moscow",
-  "offMessage": "Бот временно недоступен. Пожалуйста, попробуйте позже.",
-  "workspaceId": "<workspaceId>",
-
-  // Поля, специфичные для каждого type — см. ниже
-  "config": null,
-  "botToken": "...",
-
-  "isUserFilterEnabled": false,
-  "filteredUserIds": [],
-
-  "useDynamicVariables": false,
-  "clearDynamicVarsOnHistoryClear": true,
-
-  "responsibleAssigneeStrategy": "KEEP",
-  "fixedResponsibleId": null,
-
-  "sendToCrm": false,
-  "useCrossPlatformHistory": false,
-
-  "sendStartNoteToCrm": false,
-  "sendFailedNoteToCrm": false,
-  "sendOperatorTakeoverNoteToCrm": false,
-  "sendFinishAutoNoteToCrm": false,
-
-  "finishAutoEnabled": false,
-  "finishAutoDays": 7,
-
-  "dealMarkerType": "NONE",
-  "dealMarkerValue": null
-}
-```
-
-### Общие поля (для всех платформ)
-
-| Поле | Дефолт | Описание |
-|---|---|---|
-| `type` | — | enum `PlatformType`. Определяет, как платформа подключается. |
-| `name` | null | Пользовательское название (для UI). |
-| `isActive` | false | Включён ли канал. |
-| `isAiEnabled` | true | Работает ли AI на этой платформе. Если `false` — все сообщения уходят оператору. |
-| `timezone` | `"Europe/Moscow"` | Таймзона для расписаний и `{currentTime}`. |
-| `offMessage` | `"Бот временно недоступен..."` | Что отвечать, если `isActive=false`. |
-| `useDynamicVariables` | false | Можно ли использовать `ChatUser.dynamicVariables`. |
-| `clearDynamicVarsOnHistoryClear` | true | Очищать ли динамические переменные при очистке истории. |
-| `responsibleAssigneeStrategy` | `KEEP` | Стратегия выбора ответственного. |
-| `sendToCrm` | false | Отправлять ли сообщения от бота в CRM (Bitrix24 Open Line, AmoCRM Chat API). |
-| `useCrossPlatformHistory` | false | Использовать историю из всех платформ `UnifiedCustomer`. |
-| `dealMarkerType` | `NONE` | Маркировка сделок: `NONE` / `TAG` / `CUSTOM_FIELD`. |
-| `inboundDealFilterEnabled` / `inboundDealFilterType` / `inboundDealFilterValue` / `inboundDealFilterFieldId` | `false` / `NONE` | **GetCourse only**: агент отвечает ТОЛЬКО контактам, у которых в активной сделке есть поле=значение (`CUSTOM_FIELD` + `fieldId`) или тег (`TAG`). Не прошёл → сообщение сохраняется + уходит в CRM, AI молчит (fail-closed). Включённый фильтр требует `type≠NONE` + `value` (для `CUSTOM_FIELD` ещё `fieldId`). Ставится через `crm_behavior` в `besales_platform_settings_update` (dangerous → нужен `explicit_confirmation`). |
-
-### Workspace-scoped API
-
-Legacy endpoints `GET /api/platforms` и `POST /api/platforms` берут `workspaceId` из JWT.
-Для экранов, где workspace выбран явно в UI, используется route-scoped вариант:
-
-| Endpoint | Назначение |
-|---|---|
-| `GET /api/workspace/:workspaceId/platforms` | Список платформ выбранного workspace для текущего пользователя. |
-| `POST /api/workspace/:workspaceId/platforms` | Создание платформы в выбранном workspace. |
-
-Оба endpoint проверяют права пользователя в `:workspaceId` через `PermissionsService`:
-`PLATFORM_READ` для чтения и `PLATFORM_CREATE` для создания. Это защищает сценарии, где
-access token ещё содержит старый workspace, а интерфейс уже переключился на другой.
-
-### CRM-заметки
-
-| Поле | Дефолт | Описание |
-|---|---|---|
-| `sendStartNoteToCrm` | false | Отправлять ли заметку в CRM при первом контакте. |
-| `startNoteTemplate` | null | Кастомный текст (null — дефолтный). |
-| `sendFailedNoteToCrm` | false | Заметка при ошибке отправки. |
-| `sendOperatorTakeoverNoteToCrm` | false | Заметка при вызове оператора. |
-| `sendFinishAutoNoteToCrm` | false | Заметка при `FINISH_AUTO`. |
-
-### Авто-завершение по неактивности
-
-| Поле | Дефолт | Описание |
-|---|---|---|
-| `finishAutoEnabled` | false | Включить автозакрытие после N дней молчания. |
-| `finishAutoDays` | 7 | Сколько дней молчания. |
-
-## 3. Каталог платформ по типам
-
-### 3.1. `TelegramBot` (Telegram через BotFather)
-
-```json
-{
-  "type": "TelegramBot",
-  "botToken": "<токен от @BotFather>",
-  "isActive": true,
-  "isAiEnabled": true,
-  "enableCleanupCommands": false
-}
-```
-
-| Поле | Описание |
-|---|---|
-| `botToken` | Токен от @BotFather. **Обязательное** для активации. |
-| `enableCleanupCommands` | По умолчанию `false`. Если `true` — Animaly через `setMyCommands` регистрирует у бота меню `/clean` (очистить историю чата) и `/delete` (удалить ChatUser-контакт). Используется только для **TelegramBot**-платформ; на других channel-типах backend отклоняет с 400 (typed validation). Команды реализованы через отдельный сервисный Cleanup Bot — клиент должен добавить себя как `WorkspaceTrustedIdentity` (по `telegram_user_id`/`telegram_username`) ещё ДО первого `/start`. |
-
-**Поддерживает:** медиа (фото/видео/документы/аудио/voice/video_note), кнопки (INLINE/REPLY), группы (с ограничениями), polling/webhook, Markdown.
-
-**Лимиты:** caption ≤1024, текст ≤4096, файлы ≤50MB.
-
-### 3.2. `TelegramPersonal` (личный Telegram-аккаунт через MTProto)
-
-```json
-{
-  "type": "TelegramPersonal",
-  "isActive": true,
-  "isAiEnabled": true
-}
-```
-
-Привязка через `TelegramPersonalAccount` (отдельная сущность):
-
-```json
-{
-  "phoneNumber": "+79991234567",
-  "apiId": 12345,
-  "apiHash": "<api hash>",
-  "sessionString": "<MTProto сессия>",
-  "status": "CONNECTED",
-  "dailyMessageLimit": 10,
-  "isActiveInCampaigns": true,
-  "sendingIntervalMinutes": 2,
-  "proxyId": "<Proxy.id>"
-}
-```
-
-**Поддерживает:** все медиа, voice, video_note, кнопки только REPLY (Telegram personal не поддерживает inline).
-
-**Особенности:**
-- Можно несколько аккаунтов на одну платформу (карусель для рассылок).
-- `dailyMessageLimit` — анти-бан защита (default 10).
-- `restrictionStatus` отслеживает баны Telegram.
-- `messageOpenDelay` (`AgentBehavior`) применяется только здесь.
-
-### 3.3. `Wazzup` (агрегатор каналов)
-
-```json
-{
-  "type": "Wazzup",
-  "wazzupCrmKey": "<ключ от Wazzup>",
-  "wazzupChannel": "WhatsApp",
-  "isActive": true
-}
-```
-
-| `wazzupChannel` | Канал |
-|---|---|
-| `WhatsApp` | WhatsApp Business |
-| `Avito` | Avito (через Wazzup) |
-| `Instagram` | Instagram DM (через Wazzup) |
-| `Vk` | ВКонтакте |
-| `Telegram` | Telegram (через Wazzup) |
-| `Viber` | Viber |
-| `Max` | Max (Россия) |
-| `TelegramPersonal` | Telegram Personal через Wazzup |
-
-**Поддерживает:** WhatsApp шаблоны (WABA), медиа, кнопки (для Telegram-канала). На WhatsApp — лимит 24h-окна и approved templates.
-
-### 3.4. `Avito` (Avito Messenger напрямую)
-
-```json
-{
-  "type": "Avito",
-  "config": {
-    "clientId": "<Avito Client ID>",
-    "clientSecret": "<...>",
-    "userId": "<Avito User ID>",
-    "accessToken": "<oauth token>",
-    "refreshToken": "<...>",
-    "expiresAt": "..."
-  },
-  "isActive": true
-}
-```
-
-**Подключение (OAuth):** браузерная OAuth-авторизация Avito (`clientId` / `clientSecret` → `accessToken` / `refreshToken`); с OAuth Phase 2 доступно подключение через MCP setup-flow (Setup URL), код авторизации не проходит через чат. Поддерживает: текст, картинки. **Не поддерживает:** кнопки, документы, видео.
-
-### 3.5. `Instagram` (Direct API через Facebook Graph)
-
-```json
-{
-  "type": "Instagram",
-  "instagramBusinessAccountId": "<IG account>",
-  "instagramPageId": "<Facebook Page>",
-  "instagramPageAccessToken": "<encrypted>",
-  "instagramTokenExpiresAt": "...",
-  "instagramUserAccessToken": "<encrypted>",
-  "instagramWebhookVerifyToken": "<token>",
-
-  "replyToInstagramComments": false,
-  "instagramCommentHandlingMode": "MENTIONS_ONLY",
-  "instagramCommentReplyMethod": "PRIVATE_DM",
-  "instagramCommentKeywords": null,
-  "replyToStoryMentions": false,
-
-  "isActive": true
-}
-```
-
-**Особенности:**
-- **24h-окно**: можно отвечать только в течение 24 часов после сообщения пользователя.
-- Комментарии под постами обрабатываются отдельно (`instagramCommentHandlingMode`).
-- Story Mentions/Replies — опционально.
-
-**Подключение (OAuth):** канал подключается браузерной OAuth-авторизацией через Facebook Graph API (v21). Поток: `POST /api/instagram/auth/initiate` (под JWT) возвращает `authUrl` с подписанным HMAC-`state` → клиент подтверждает доступ в диалоге Facebook → `GET /api/instagram/auth/callback` обменивает `code` на токены и сохраняет `instagramPageAccessToken` / `instagramUserAccessToken`. Токены не вводятся вручную и не проходят через чат; тот же поток используется при подключении через MCP setup-flow (OAuth Phase 2).
-
-### 3.6. `Salebot` (внешний агрегатор)
-
-```json
-{
-  "type": "Salebot",
-  "salebotApiKey": "<API key>",
-  "salebotProjectId": "<project id>",
-  "salebotGroupId": "<group/bot name>",
-  "isActive": true
-}
-```
-
-Salebot сам подключает Telegram/VK/WhatsApp/etc. Animaly через API Salebot отправляет/принимает сообщения.
-
-### 3.7. `SmsGorod` (SMS через сервис)
-
-```json
-{
-  "type": "SmsGorod",
-  "smsgorodApiKey": "<API key>",
-  "smsgorodChannel": "DIGIT",
-  "smsgorodSender": null,
-  "isActive": true
-}
-```
-
-| `smsgorodChannel` | Описание |
-|---|---|
-| `DIGIT` | Цифровой номер отправителя (sender необязателен). |
-| `CHAR` | Буквенное имя отправителя — `smsgorodSender` обязателен. |
-
-**Лимиты:**
-- Один SMS = 70 символов кириллицей или 160 латиницей.
-- Длинные сообщения разбиваются провайдером.
-- **Не поддерживает:** медиа, кнопки.
-- Рекомендуется задать `AgentChat.maxResponseSymbols` (например, 140), чтобы LLM не генерировал слишком длинно.
-
-### 3.8. `VKon` (VK сообщество)
-
-```json
-{
-  "type": "VKon",
-  "config": {
-    "groupId": "<community ID>",
-    "accessToken": "<community access token>",
-    "secret": "<callback secret>",
-    "confirmation": "<callback confirmation string>"
-  },
-  "isActive": true
-}
-```
-
-**Поддерживает:** текст, медиа (фото/видео/аудио/документы), кнопки (как REPLY-клавиатура), карусели.
-
-### 3.9. `WebWidget` (встраиваемый виджет на сайт)
-
-```json
-{
-  "type": "WebWidget",
-  "webWidgetAllowedOrigins": ["*"],
-  "webWidgetShowPageInfo": true,
-  "webWidgetRateLimitPerMinute": 20,
-  "webWidgetCustomization": {
-    "logo": "https://example.com/logo.png",
-    "colors": { "primary": "#7B61FF" },
-    "position": "bottom-right",
-    "buttonStyle": "rounded"
-  },
-  "webWidgetMarketingFieldMappings": {
-    "utm_source": "<crmFieldId>",
-    "utm_campaign": "<crmFieldId>",
-    "ymClientId": "<crmFieldId>",
-    "googleClientId": "<crmFieldId>"
-  },
-  "webWidgetEntryUrlVariableMapping": {
-    "variableName": "first_visit_url",
-    "regex": null
-  }
-}
-```
-
-**Особенности:**
-- Real-time через **Socket.IO** (не webhook).
-- `webWidgetShowPageInfo` (**default `false`**, opt-in) — добавляет в системный промпт блок
-  «Контекст страницы»: URL, заголовок и meta description страницы, на которой находится
-  посетитель. Работает **только для RAG-агентов** — у SIMPLE- и QA-шаблонов этого блока нет.
-  Вложения (файлы, скриншоты) приходят без контекста страницы. Значения санируются: пробелы
-  схлопываются, длина режется (url 512 / title 200 / description 400 символов).
-- `webWidgetMarketingFieldMappings` — UTM/yaClientId/gaClientId автоматически отправляются в CRM-поля.
-- Push-кампании **не поддерживаются** (нет инициатора со стороны бота).
-- Особая логика follow-up через `webWidgetLastSeenAt` (см. [`08-follow-up.md`](08-follow-up.md)).
-
-### 3.10. `Bitrix24Bot` (Bitrix24 Open Lines)
-
-```json
-{
-  "type": "Bitrix24Bot",
-  "bitrix24BotId": 42,
-  "bitrix24BotCode": "animaly_bot_<workspaceId>",
-  "bitrix24BotName": "BeSales AI",
-  "bitrix24OpenLineId": "5",
-  "isActive": true
-}
-```
-
-Бот регистрируется в Bitrix24 и принимает сообщения из всех каналов Open Lines (Telegram/WhatsApp/VK/Viber/Avito).
-
-**Особенности:**
-- Live-проверка колонки CRM перед отправкой follow-up (см. [`08-follow-up.md`](08-follow-up.md), раздел 4.1).
-- `hasExitedSilentMode` у `ChatUser` — лид/сделка активирована (попала в INCOMING/OUTGOING).
-
-### 3.11. `GetCourse` (LMS GetCourse)
-
-```json
-{
-  "type": "GetCourse",
-  "getcourseAccountDomain": "school.getcourse.ru",
-  "getcourseSchoolApiKey": "<encrypted>",
-  "getcourseEmployeeUserId": 42,
-  "getcourseAvailableTransports": ["Site", "Email", "Telegram"],
-  "getcourseDefaultTransport": "Site",
-  "getcourseWebhookSecret": "<random32bytes>",
-  "getcourseDepartments": [
-    { "id": 1, "label": "Отдел продаж" },
-    { "id": 2, "label": "Поддержка" }
-  ]
-}
-```
-
-**Особенности:**
-- **Single Platform** на школу с массивом активных транспортов (`Site`, `Email`, `SMS`, `Telegram`, `Facebook`, `VK`, `Chatium`, `WhatsApp`, `Viber`).
-- Каждое сообщение знает свой транспорт (`ChatUsersMessages.getcourseTransport`).
-- Reply-routing: куда написал — туда отвечаем (`ChatUser.lastGetcourseTransport`).
-- Поддерживает GetCourse как CRM (отдельные `ActionGetCourse*` — см. [`04-triggers-and-actions.md`](04-triggers-and-actions.md)).
-
-## 4. Сводная таблица возможностей
-
-| Платформа | Кнопки | Медиа | Группы | Push-кампании | 24h-окно |
-|---|---|---|---|---|---|
-| `TelegramBot` | INLINE+REPLY | Все | Да | Да | — |
-| `TelegramPersonal` | REPLY | Все | Да | Да | — |
-| `Wazzup` (WhatsApp) | Inline (WABA) | Да | Да | Через WABA шаблоны | Да |
-| `Wazzup` (Telegram) | Inline | Все | Да | Да | — |
-| `Avito` | Нет | Картинки | Нет | Ограниченно | — |
-| `Instagram` | Quick Replies | Изображения | Нет | Только в 24h-окне | Да |
-| `Salebot` | Зависит от подключённого канала | Зависит | Зависит | Да | Зависит |
-| `SmsGorod` | Нет | Нет | Нет | Да | — |
-| `VKon` | REPLY-клавиатура | Все | Да | Да | — |
-| `WebWidget` | Inline + popup | Да | Нет | **Нет** | — |
-| `Bitrix24Bot` | Зависит от Open Line | Да | Зависит | Да | — |
-| `GetCourse` | Нет (Inbox API ограничен) | Да | Нет | Да | — |
-
-## 5. Стратегии ответственного (`responsibleAssigneeStrategy`)
-
-| Значение | Поведение |
-|---|---|
-| `KEEP` | Сохранять текущего ответственного в CRM. |
-| `ALWAYS_ONE` | Всегда `fixedResponsibleId`. |
-| `RANDOM_OPERATOR` | Случайный оператор из списка `CrmOperator`. |
-
-## 6. PipelineSettings — фильтрация существующих сделок
-
-```json
-{
-  "platformId": "<platformId>",
-  "filters": [
-    {
-      "fieldId": "PHONE",
-      "valueType": "SYSTEM_VARIABLE",
-      "value": "phone",
-      "action": "LINK"
-    }
-  ]
-}
-```
-
-`PipelineSettings` определяет, что делать, если в CRM уже есть сделка с тем же телефоном/email:
-- `LINK` — привязать пользователя к существующей сделке.
-- `IGNORE` — игнорировать (создать новую, или `isBotActive=false`).
-
-## 7. Inline-пример: Telegram-бот для интернет-магазина
-
-```json
-{
-  "type": "TelegramBot",
-  "name": "Главный Telegram-бот",
-  "botToken": "<TOKEN>",
-  "isActive": true,
-  "isAiEnabled": true,
-  "timezone": "Europe/Moscow",
-
-  "useDynamicVariables": true,
-  "clearDynamicVarsOnHistoryClear": true,
-
-  "responsibleAssigneeStrategy": "RANDOM_OPERATOR",
-  "sendToCrm": false,
-
-  "sendStartNoteToCrm": true,
-  "startNoteTemplate": "Новый лид из Telegram-бота",
-
-  "sendOperatorTakeoverNoteToCrm": true,
-
-  "finishAutoEnabled": true,
-  "finishAutoDays": 14,
-  "sendFinishAutoNoteToCrm": true,
-
-  "dealMarkerType": "TAG",
-  "dealMarkerValue": "telegram-bot"
-}
-```
-
-## 8. Inline-пример: SmsGorod для отправки уведомлений
-
-```json
-{
-  "type": "SmsGorod",
-  "name": "SMS-уведомления",
-  "smsgorodApiKey": "<KEY>",
-  "smsgorodChannel": "CHAR",
-  "smsgorodSender": "MyShop",
-  "isActive": true,
-  "isAiEnabled": false,
-  "timezone": "Europe/Moscow"
-}
-```
-
-`isAiEnabled=false`: SMS-канал часто не для AI-диалога, а для исходящих уведомлений (через follow-up/кампании).
-
-## 9. Inline-пример: Web Widget с UTM-маркетингом
-
-```json
-{
-  "type": "WebWidget",
-  "name": "Виджет на сайте",
-  "isActive": true,
-  "isAiEnabled": true,
-  "timezone": "Europe/Moscow",
-
-  "webWidgetAllowedOrigins": ["https://shop.example.com", "https://example.com"],
-  "webWidgetShowPageInfo": true,
-  "webWidgetRateLimitPerMinute": 30,
-
-  "webWidgetCustomization": {
-    "colors": { "primary": "#7B61FF", "background": "#FFFFFF" },
-    "position": "bottom-right"
-  },
-
-  "webWidgetMarketingFieldMappings": {
-    "utm_source": "<crmFieldId-utm_source>",
-    "utm_campaign": "<crmFieldId-utm_campaign>",
-    "ymClientId": "<crmFieldId-yandex_client_id>"
-  },
-
-  "webWidgetEntryUrlVariableMapping": {
-    "variableName": "first_visit_url"
-  }
-}
-```
-
-## 10. Граничные случаи и валидация
-
-| Правило | Что AI-сервису помнить |
-|---|---|
-| `botToken` обязателен для TelegramBot | Без него `isActive=true` всё равно не сработает. |
-| `wazzupChannel` определяет фичи | На WhatsApp — лимит 24h, на Telegram через Wazzup — нет. |
-| Avito — без кнопок и видео | Не предлагать. |
-| Instagram — только в 24h-окне | Кампании пройдут только тем, кто писал недавно. |
-| WebWidget — нет push-кампаний | Используется только в реальном времени. |
-| SMS — `maxResponseSymbols` критично | LLM может генерировать длинные ответы; для SMS обязательно ограничить (например, 140). |
-| `useCrossPlatformHistory=true` | Требует `UnifiedCustomer`-привязки клиентов. |
-| `finishAutoEnabled=true` | Автозакрытие после `finishAutoDays` дней. Полезно для аналитики «потерянных», но не для активных воронок. |
-| `dealMarkerType=TAG` | Создаёт тег в CRM (например, для атрибуции). |
-| `inboundDealFilterEnabled=true` (GetCourse) | Платформа отвечает только «контактам в волне» (поле/тег на активной сделке). TAG-режим best-effort (скан ~1000 последних сделок); для надёжности — `CUSTOM_FIELD`. Маркер часто = move-signal поле сделки. |
-| Telegram Personal лимиты | `dailyMessageLimit`, `sendingIntervalMinutes` — иначе бан. |
-| `proxyId` для TG Personal | Желательно — Telegram быстро банит без прокси. |
-
-## 11. Связь с другими подсистемами
-
-| Подсистема | Связь |
-|---|---|
-| **Агенты** ([`01-agents.md`](01-agents.md)) | Все агенты привязаны к платформе. |
-| **Поведение** ([`10-agent-behavior.md`](10-agent-behavior.md)) | Один `AgentBehavior` на платформу. |
-| **Follow-up** ([`08-follow-up.md`](08-follow-up.md)) | WebWidget — особая логика. Bitrix24Bot — live-проверка. |
-| **Кампании** ([`09-campaigns.md`](09-campaigns.md)) | Не все платформы поддерживают; разные лимиты. |
-| **CRM** ([`12-crm-integration.md`](12-crm-integration.md)) | `sendToCrm`, `dealMarkerType`, `responsibleAssigneeStrategy`, `PlatformAmoChatConfig`. |
-| **Переменные** ([`05-variables.md`](05-variables.md)) | `useDynamicVariables`, `webWidgetEntryUrlVariableMapping`. |
-| **CustomVariable** | Привязаны к платформе через `platformId`. |
+# Каналы связи
+
+Каноническая сущность Besales — `channels`; секретная и провайдерская конфигурация хранится в
+`channel_connections`. В workspace разрешено несколько экземпляров одного типа, поэтому канал
+всегда выбирается по своему ID, а не по предположению «Telegram здесь один».
+
+## Поддерживаемые семейства
+
+Рабочая поверхность включает Telegram Bot, Telegram Personal, Wazzup, Instagram DM, Avito, VK,
+SMS, Web Widget, Bitrix24 Bot, Salebot, GetCourse, Voice и External API. Возможности различаются:
+кнопки, media caption, доставка тела собственного файла и подтверждение результата объявляются
+адаптером явно.
+
+## Подключение
+
+Секреты никогда не передаются через MCP или LLM. Инициализация возвращает короткоживущую setup
+ссылку, пользователь вводит credentials в браузере, а клиент опрашивает статус. OAuth-каналы
+используют тот же принцип: код авторизации завершается сервером и не появляется в чате.
+
+После подключения проверь:
+
+- соединение принадлежит нужному workspace;
+- webhook подписан и проходит дедупликацию;
+- канал готов принимать входящие события;
+- capability-профиль заполнен без умолчаний для обязательных свойств;
+- агент и пространства знаний привязаны именно к этому экземпляру.
+
+## Настройки канала через мост
+
+`besales_platform_settings_update` принимает страну разбора телефона в
+`general_settings.phone_parsing_country`: строка передаётся API для проверки по его реестру,
+`null` снимает настройку. От страны зависит, получит ли агент инструмент сохранения телефона;
+`UZ` означает, что девятизначный номер трактуется как узбекский; `RU` выдаёт инструмент без
+разбора девяти цифр — российский номер разбирается по своей длине, девятизначный отклоняется.
+
+В `crm_behavior` доступны семь связанных настроек:
+
+- `create_deal_on_first_outbound`;
+- `finish_auto_enabled`;
+- `finish_auto_days` — целое число от 1 до защитного потолка 36 500 дней;
+- `send_finish_auto_note_to_crm`;
+- `finish_auto_note_template` — строка либо `null`, который снимает шаблон даже на свежем канале
+  без сохранённых `crm_behavior` и `auto_finish`;
+- `getcourse_create_deal_payment_tracking_enabled`;
+- `getcourse_status_deal_fallback_enabled`.
+
+Если `crm_behavior` ещё не сохранён, единственное активное CRM-подключение требуется для
+`send_to_crm`, создания сделки по первой исходящей, стратегии и фиксированного ответственного,
+четырёх флагов отправки заметок, трёх полей маркера сделки, четырёх шаблонов заметок и обоих
+GetCourse-флагов. Ноль или несколько подключений дают 422 `CRM_CONNECTION_UNRESOLVED`. При уже
+сохранённом `crm_behavior` подключение этим маршрутом повторно не проверяется.
+
+Опасные изменения `create_deal_on_first_outbound`, `send_finish_auto_note_to_crm` и
+`getcourse_create_deal_payment_tracking_enabled` требуют `explicit_confirmation=true`. Последний
+флаг по умолчанию включён: при отсутствующем сохранённом ключе `false` требует
+подтверждения, а `true` проходит как неизменное действующее значение. Включение
+автозавершения не требует подтверждения, опасна отправка заметки.
+
+## Входящие и исходящие сообщения
+
+Webhook быстро сохраняет сырой факт, дедуплицирует его и ставит обработку в очередь. Тяжёлая
+логика и биллинг не должны задерживать ответ провайдеру. Медиа скачивается единым безопасным
+контуром, проверяется по содержимому и сохраняется в объектное хранилище.
+
+Исходящий контент проходит `OutboundDeliveryService`. Прямой вызов адаптера из бизнес-модуля
+запрещён: он обошёл бы governance, идемпотентность, журнал исхода и побочные эффекты доставки.
+
+## Имена и жизненный цикл
+
+Название и описание канала редактируются пользователем. Удаление канала не превращает его
+локальные правила маршрутизации в правила всего workspace: такие правила удаляются вместе с
+каналом. Исторические сообщения и аудит подчиняются своим правилам хранения, а не имени канала.
+
+## Прежняя форма настроек канала
+
+`besales_platform_settings_update` принимает прежние выключатели `access_control.is_active` и
+`is_ai_enabled`, а также прежние поля `widget_marketing.web_widget_*`. Мост переносит выключатели,
+список сайтов, лимит, сведения о странице и оформление в `general_settings`; две карты виджета
+остаются в `widget_marketing`. Для списка сайтов пустой объект и пустой список означают
+`['*']` — работать везде; непустой объект получает отказ с адресом поля. Непустой массив
+сохраняется. `null` тоже принимается как `['*']` для совместимости чтения, хотя прежний сервер
+не мог записать голый `null` в JSON-колонку.
+
+Во вложенных настройках мост переводит camelCase прежнего DTO в snake_case API: например
+`button.backgroundColor` → `button.background_color`, `window.userMessageGradient` →
+`window.user_message_gradient`, `window.botMessageBackgroundColor` →
+`window.bot_message_background_color` (необязательная заливка сообщений бота, цвет `#RGB` или
+`#RRGGBB`; мост значение не проверяет и не меняет, форму проверяет сервер), `utmSource` →
+`utm_source`, `targetVariableName` → `target_variable_name`, `rules[].useStrictUrlMatching` →
+`rules[].use_strict_url_matching`. Оба имени одного поля вместе дают отказ с адресом, даже если
+значения одинаковы. Голый `null` для оформления и обеих карт
+отклоняется: прежний сервер также не мог записать его в JSON-колонку; присылай изменяемые поля.
+
+`general_settings.show_page_info` включает контекст страницы посетителя Web Widget: URL,
+заголовок и meta description. Это opt-in: без включённого флага блок в ход не попадает.
+Значения санируются и ограничиваются по длине; это недоверенные данные страницы.
+Наличие семейства канала в runtime не доказывает возможность подключения через MCP — сверяй
+поддерживаемый тип со схемой `besales_platform_create_init`.
+
+## Ответы на комментарии Instagram
+
+Настройки поддерживают отдельные утверждённые личные ответы и публичные ответы на жалобы.
+Каждая из трёх групп содержит русскую, узбекскую латинскую и узбекскую кириллическую версию.
+Передаваемый объект заменяет шаблоны целиком: пропуск сохраняет, {} очищает, null убирает.
+Публичный ответ и личное сообщение имеют независимые исходы; неизвестная доставка не повторяется.
+Сначала проверьте доступность записи настроек и подключение канала. Живая проверка Meta выполняется отдельно.
+
+## Прогрев и лесенка личных номеров Telegram
+
+`besales_platform_telegram_personal_accounts` читает таблицу номеров по `channel_id`:
+`search`, `status`, `page` (от 1), `limit` (1–100). Нужен `read:channels`.
+`summary` охватывает все живые номера до отбора; `pagination` и `truncated` нельзя терять.
+`campaign` и состояние строки описывают участие и разгон; прогрев — отдельный `warmup`
+(`active`, `reason`, `label`, `until`, `optedOut`), он не блокирует рассылку.
+`restriction` показывает ограничения, последнюю проверку и жалобу; `autoAppealNotBefore`
+читай как наблюдение ядра. Автоматическая подача жалоб сейчас выключена.
+
+`besales_platform_telegram_personal_warmup` читает настройки и аналитику прогрева;
+`besales_platform_telegram_personal_warmup_update` частично меняет их (нужен `manage:channels`).
+Поля настроек передаются в snake_case, например `messages_per_day`, `images_enabled`,
+`reaction_types`, `reaction_hours_utc`; пропуск сохраняет, false, 0 и [] передаются буквально.
+Подтверждение не требуется: сообщения прогрева идут только между своими номерами.
+
+`besales_platform_telegram_personal_account_warmup` принимает `channel_id`, `account_id`
+и `is_warming_up`. false выводит номер из автоматического прогрева до ручного включения;
+true снимает ручной отказ. `besales_platform_telegram_personal_ramp` читает только
+`newAccountRampEnabled` выбранной рабочей области. Для чтения нужен `read:channels`.
+
+Лесенка: 3, 4, 5, 6, 7 с первого дня рассылки. Прогрев идёт параллельно 5 дней,
+включается сам при подключении номера, если его не выключить вручную.
+
+## Проверка ограничений личных номеров Telegram
+
+`besales_platform_telegram_personal_restriction_check` проверяет все номера канала (`all:true`)
+или список `account_ids` (1–100). Нужны `channel_id`, стабильный `idempotency_key` и право
+`manage:channels`. Обращение идёт только к @SpamBot, подтверждение не требуется.
+`besales_platform_telegram_personal_restriction_appeal` принимает тот же выбор, необязательный
+`text` (1–500 знаков после trim) и обязательное `explicit_confirmation:true` после явного
+согласия человека. Перед вызовом покажи человеку номер и свой текст, если он задан. Автоматическая подача сейчас
+выключена. Без `text` система подбирает разные английские апелляции для каждого
+номера и сохраняет выбор для повторов с тем же ключом; в ответе — `appealTemplateId`, без текста. Апелляция
+отправляется от номера, отменить её нельзя, не чаще раза в UTC-сутки на номер.
+
+В ответе читай каждый `items[].outcome`: `QUEUED/taskId` означает очередь, `FAILED` или
+`SKIPPED` содержат причину. Затем вызови `besales_platform_telegram_personal_operational_task_get`
+с `channel_id` и `task_id` (право `read:channels`). Он возвращает `state` задачи и текущий
+`restrictionStatus` номера; `SUCCEEDED` не означает отсутствие ограничений. Статус мог измениться
+после задачи; `null` означает недоступное наблюдение. При неизвестном исходе сначала прочитай
+задачу или доступность номеров; новый ключ автоматически не создавай.