supersam/docs/chatbot-integration.md

Логика чатботов VK, Telegram и Messenger Max

Общий принцип

Все каналы работают через единый слой адаптеров:

1. webhook принимает событие от канала;
2. адаптер нормализует payload в общую структуру;
3. сообщение или действие сохраняется в chat_messages;
4. при изменении состояния заказа создаётся запись в order_history;
5. UI обновляет карточку заказа и уведомления.

Единая модель событий

{
  "order_id": "uuid",
  "channel": "telegram | vk | messenger_max",
  "direction": "inbound | outbound",
  "message_type": "text | button | system",
  "sender_type": "client | bot | operator",
  "text": "Подтверждаю доставку",
  "payload": {
    "action": "confirm_delivery",
    "slot_id": "uuid"
  },
  "external_message_id": "string"
}

При обновлении заказа бот теперь меняет два поля:

• orders.status — основной статус заказа;
• orders.delivery_agreement_status — состояние согласования доставки с клиентом.

Telegram

• Отправка статуса готовности через sendMessage.
• Кнопки подтверждения через inline keyboard: confirm, reschedule, cancel.
• Callback query несёт order_id, slot_id, action.
• При ответе клиента обновляются chat_messages, delivery_slots, orders.status.

VK

• Используется Callback API сообщества.
• Кнопки в keyboard отправляют payload с order_id и action.
• Система проверяет подпись webhook, нормализует payload и сохраняет событие.

Messenger Max

• Адаптер должен принимать webhook событий сообщений и postback-действий.
• На входе событие маппится в ту же структуру, что и Telegram/VK.
• Неизвестные типы сохраняются как system для последующего разбора администратором.

Автоматические сценарии

• Готово к доставке → бот отправляет предложение со слотами.
• Подтверждение клиента → статус Доставка согласована, согласование Подтверждено клиентом.
• Перенос → создаётся новый delivery_slot, статус Ожидает согласования доставки, согласование Перенос запрошен.
• Отмена или сбой сценария → статус Проблема доставки.
• Нет ответа после SLA → согласование Нет ответа и задача логисту на ручную обработку.

Надёжность и аудит

• Все inbound/outbound события нужно логировать с external_message_id.
• Ошибки интеграции стоит писать в отдельную таблицу integration_events или error_logs.
• Повторная обработка webhook должна быть идемпотентной по external_message_id.

Что уже добавлено в репозиторий

• supabase/functions/chatbot-webhook/index.ts — приём webhook и фиксация inbound-событий.
• supabase/functions/send-chatbot-message/index.ts — отправка outbound-сообщений и логирование.
• supabase/functions/_shared/chatbot.ts — общий слой нормализации событий и статусов.
• supabase/functions/_shared/workflow.ts — чистая карта переходов для inbound/outbound событий.