Telegram

OPORA поддерживает Telegram Bot API: входящие webhook’и + 6 outbound операций (send / edit / delete / callback.answer / chat.action / media.send).

За ~10 минут вы:

Заведёте бота через @BotFather
Сохраните token в OPORA и зарегистрируете webhook
Запустите AI-ответчика, который принимает сообщения и шлёт reply

1. Заведите бота

Откройте Telegram, найдите @BotFather
/newbot → введите имя (любое) + username (заканчивается на _bot или Bot)
BotFather выдаст token вида 7123456789:AAExxx-yyyZZZ...
(опционально) /setdescription, /setabouttext, /setuserpic — косметика профиля бота

2. Сохраните в OPORA

Settings → Secrets → telegram-bot-token → paste token.

Также сгенерируйте произвольный webhook_secret — понадобится для валидации incoming webhook’ов:

openssl rand -hex 32

Сохраните его как secret telegram-webhook-secret.

3. Зарегистрируйте webhook

После создания telegram.webhook.trigger ноды в workflow’е и publish’а, OPORA покажет webhook-URL (https://app.opora.example/ webhook/<uuid>).

Зарегистрируйте в Telegram:

curl "https://api.telegram.org/bot<token>/setWebhook" \
  -d "url=https://app.opora.example/webhook/<uuid>" \
  -d "secret_token=<webhook_secret>"

Telegram echo’ит secret_token обратно в каждый update’е как заголовок X-Telegram-Bot-Api-Secret-Token. OPORA проверяет его на каждом incoming-запросе — это анти-spoofing защита.

Проверьте что webhook активен:

curl "https://api.telegram.org/bot<token>/getWebhookInfo"
# ожидаемо: {"ok":true,"result":{"url":"https://app.opora..."}}

4. Workflow: AI-ответчик

telegram.webhook.trigger
    ↓
ai.chat
  system = "Ты помощник магазина <X>. Отвечай коротко, вежливо."
  input = "{{trigger.message.text}}"
  memory_key = "tg:{{trigger.message.chat.id}}"
    ↓
telegram.message.send
  chat_id = {{trigger.message.chat.id}}
  text = {{ai.chat.output}}
  reply_to_message_id = {{trigger.message.message_id}}

ai.chat с memory_key = "tg:<chat_id>" держит conversation-history per-чат — бот помнит контекст предыдущих сообщений в пределах retention window’а (по умолчанию 24 часа, настраивается).

Ноды Telegram

Нода	Что делает
`telegram.webhook.trigger`	Приём update’ов (messages / callbacks / my_chat_member / edited_message / etc.)
`telegram.message.send`	Отправка текстового сообщения (с опциональными reply-кнопками)
`telegram.message.edit`	Редактирование сообщения (по message_id)
`telegram.message.delete`	Удаление
`telegram.callback.answer`	Ответ на inline-кнопку (обязателен в течение 15 секунд)
`telegram.chat.action`	Индикатор «печатает…», «загружает видео…»
`telegram.media.send`	Photo / document / video / voice / animation / video_note по URL или `file_id`

Не реализовано (добавим по demand’у): direct multipart-upload (загрузка бинарного файла в боте-runtime’е), audio, location, venue, polls, inline-mode queries.

Inline-клавиатуры

Отправка сообщения с кнопками:

telegram.message.send
  chat_id = {{trigger.message.chat.id}}
  text = "Выберите действие:"
  reply_markup = {
    "inline_keyboard": [
      [{"text": "Подтвердить", "callback_data": "confirm:{{order_id}}"}],
      [{"text": "Отменить", "callback_data": "cancel:{{order_id}}"}]
    ]
  }

Обработка callback’а:

telegram.webhook.trigger (update_type: callback_query)
    ↓
control.switch (on: {{trigger.callback_query.data}})
  ├─ match "confirm:*" → amocrm.deal.update (status=confirmed)
  └─ match "cancel:*"  → amocrm.deal.update (status=canceled)
    ↓
telegram.callback.answer
  callback_query_id = {{trigger.callback_query.id}}
  text = "Готово"

Отправка медиа

По URL (Telegram скачает сам):

telegram.media.send
  chat_id = {{chat_id}}
  type = "photo"
  url = "https://your-cdn.example/image.jpg"
  caption = "Фото товара"

По file_id (если файл уже был отправлен через бота раньше — cheaper, Telegram-side CDN):

telegram.media.send
  chat_id = {{chat_id}}
  type = "document"
  file_id = "{{prev.telegram.media.send.result.document.file_id}}"
  caption = "Тот же файл, отправлен повторно"

Forwarding из CRM в Telegram

Типовой паттерн: новый lead в amoCRM → уведомление менеджеру в Telegram-чате команды:

amocrm.webhook.trigger (event: leads.add)
    ↓
telegram.message.send
  chat_id = -1001234567890   # id группового чата, находится через /getUpdates
  text = "🔥 Новый лид: {{trigger.leads.add.0.name}}\nТелефон: {{trigger.leads.add.0.custom_fields_values[0].values[0].value}}\namoCRM: https://acme.amocrm.ru/leads/detail/{{trigger.leads.add.0.id}}"
  parse_mode = "HTML"

Troubleshooting

401 от Telegram Bot API

Token неверный / отозван. /revoke в BotFather + выдайте новый.
Token попал в логи / git — это компрометация, обязательно ревокайте + перегенерируйте.

Webhook не срабатывает

curl "https://api.telegram.org/bot<token>/getWebhookInfo"

Смотрите last_error_date + last_error_message. Частые причины:

URL за HTTPS без валидного сертификата (Telegram требует TLS)
secret_token не совпадает с настроенным в trigger-ноде
OPORA webhook-endpoint 5xx’ит — проверьте docker compose logs api

Бот не видит сообщения в группе

/setprivacy в BotFather → Disable. Бот должен быть добавлен в группу как admin (или с правом читать сообщения).

«Flood control exceeded»

Telegram rate-limit — 30 сообщений/секунду на всех чатах суммарно + 1 сообщение/секунду в один чат. OPORA не ретраит автоматически — в workflow’е добавьте control.delay между batch-send’ами или используйте data.array.foreach с concurrency: 1 для sequential- доставки.

Связанное

MAX — российский мессенджер с похожим Bot API
VK — VK messenger через Callback API
Cookbook → AI Telegram bot — полный end-to-end пример с RAG поверх knowledge-базы