04. Сервисы интеграций и каналов¶

Два расширяемых сервиса-фреймворка. Ключевой принцип обоих — единый интерфейс + плагины: добавление новой системы/канала не меняет ядро.

1. Integration Service (интеграция с чем угодно)¶

Назначение¶

Связывает агента с внешними системами: CRM, календари, телефония, ERP/1С, каталоги, любые API. Именно сюда идёт «голевая передача» — создание сделки и передача лида менеджеру в CRM.

Архитектура: коннектор-фреймворк¶

flowchart TB
    orch[Orchestrator] --> reg[Реестр коннекторов]
    reg --> c1[Connector: Bitrix24]
    reg --> c2[Connector: amoCRM]
    reg --> c3[Connector: HubSpot]
    reg --> c4[Connector: Custom REST]
    reg --> c5[Connector: 1C]
    subgraph common [Общая инфраструктура]
        map[Маппинг полей]
        wh[Webhook-приёмник]
        q[(Очередь + retry)]
        oauth[Хранилище учёток / OAuth]
    end
    c1 --> map
    c2 --> map
    c3 --> map
    c4 --> map
    c5 --> map
    map --> ext[Внешние системы]
    wh --> ext
    q --> ext
    oauth --> ext

Единый интерфейс коннектора¶

Каждый коннектор реализует общий контракт (концептуально):

interface Connector:
    authenticate(credentials)          # OAuth / API-key / вебхук-секрет
    push_lead(lead) -> external_id      # создать/обновить сущность
    update_entity(id, patch)
    subscribe_events(callback)          # входящие вебхуки от системы
    map_fields(internal <-> external)   # маппинг полей
    healthcheck()

Способы интеграции¶

Готовые коннекторы-плагины: Bitrix24, amoCRM, HubSpot, 1С, Google/Яндекс Календарь, телефония.
Custom REST/Webhook коннектор: для «чего угодно» — настраиваемый маппинг полей и эндпоинтов без написания кода.
Connector SDK: для сложных случаев — разработка своего коннектора по контракту.
Вебхуки в обе стороны: платформа принимает события от внешних систем и шлёт свои.

Надёжность¶

Все вызовы через очередь с retry и circuit breaker.
Идемпотентность (по external_id) — чтобы не создавать дубли лидов.
Саги: если шаг «создать показ» упал — компенсируем «создать сделку».

2. Channel Service (любые каналы)¶

Назначение¶

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

Архитектура: адаптеры каналов¶

flowchart TB
    web[Web-виджет]
    wa[WhatsApp]
    tg[Telegram]
    em[Email]
    tel[Телефония / голос]
    web --> norm[Нормализатор в единое сообщение]
    wa --> norm
    tg --> norm
    em --> norm
    tel --> stt[STT]
    stt --> norm
    norm --> idres[Identity resolution: единый профиль контакта]
    idres --> orch[Orchestrator]
    orch --> outrouter[Роутер исходящих]
    outrouter --> web
    outrouter --> wa
    outrouter --> tg
    outrouter --> em
    outrouter --> tts[TTS]
    tts --> tel

Единый интерфейс адаптера¶

interface ChannelAdapter:
    receive(raw_event) -> NormalizedMessage
    send(NormalizedMessage)
    capabilities()        # текст, медиа, кнопки, голос
    identity_hint()       # телефон/username для склейки контакта

Ключевые механизмы¶

Нормализация: любое сообщение приводится к единому формату (текст, вложения, метаданные, автор).
Identity resolution (единый профиль контакта): клиент пришёл с сайта, затем написал в WhatsApp — система склеивает это в один профиль по телефону/почте/идентификаторам, чтобы не начинать диалог заново.
Выбор канала для продолжения (preferred_followup из конфига агента): агент продолжает коммуникацию там, где удобно клиенту.
Голос/телефония — отдельная сложность: real-time STT+TTS с низкой латентностью; выделяется в отдельный компонент (в MVP может быть опциональным — открытый вопрос в 00-overview.md).

Особенности каналов (важно для стоимости и права)¶

WhatsApp Business API — платный за диалоги/шаблоны; нужен провайдер (BSP).
Телефония — поминутная тарификация + STT/TTS.
Согласие на outbound: перед инициативным сообщением/звонком нужно юридическое основание (см. 08).

3. Почему так (обоснование)¶

Расширяемость без переписывания ядра — новая CRM/канал = новый плагин по контракту.
Изоляция отказов — падение одного коннектора/канала не роняет остальные (bulkhead + circuit breaker).
Единая модель данных внутри платформы — оркестратор не знает деталей конкретной CRM или мессенджера.