Telegram

The Telegram trigger receives Update objects from a Telegram bot — DMs, group messages, channel posts, and edited messages — and starts a workflow with the message body and sender info already normalized.

For sending messages back, see the /telegram skill (bidirectional notifications via @samjr2026bot).

How to configure

1. Talk to @BotFather on Telegram and run /newbot (or /token on an existing bot) to get the bot's HTTP API token (looks like 123456789:AAH...). Paste it into the trigger's Bot token field — MyBotBox stores it encrypted and uses it both to register the webhook and to call sendMessage from downstream blocks.
2. On save, MyBotBox registers the webhook by calling POST https://api.telegram.org/bot<token>/setWebhook with url=<Webhook URL above> and a randomly generated secret_token. Telegram echoes that secret in the X-Telegram-Bot-Api-Secret-Token header on every delivery — the trigger rejects requests whose header does not match with 401.
3. Telegram delivers an Update object — typically with a message field. The trigger normalizes it: <telegram1.message.text> for the message body, <telegram1.message.raw.chat.id> for the chat ID to reply into, <telegram1.sender.firstName>, etc. updateType distinguishes message / edited_message / channel_post.
4. Verify by sending any message to your bot in Telegram (DM, or in a group after disabling Privacy Mode via /setprivacy). Expect a fire within ~1 second. To re-register after URL changes, simply re-save the trigger — setWebhook overwrites the previous URL atomically.

Signature format

Telegram does not HMAC-sign payloads; the per-trigger secret token is the entire authentication. Because every trigger gets a fresh random secret on save, leaked URLs alone cannot be used to spoof events. The Telegram update_id is used as the dedup key.

Sample payload

{
  "update_id": 925478123,
  "message": {
    "message_id": 4321,
    "from": {
      "id": 1234567890,
      "is_bot": false,
      "first_name": "Alex",
      "last_name": "Chen",
      "username": "alexchen",
      "language_code": "en"
    },
    "chat": {
      "id": 1234567890,
      "first_name": "Alex",
      "last_name": "Chen",
      "username": "alexchen",
      "type": "private"
    },
    "date": 1745700000,
    "text": "Summarize my last 5 meetings",
    "entities": []
  }
}

After normalization, downstream blocks see <telegram1.message.text>, <telegram1.message.id>, <telegram1.message.messageType> (text / photo / document / audio / …), and <telegram1.sender.id>. The original Telegram object is preserved at <telegram1.message.raw>.

Verify with the bundled scripts

bun apps/sat/tests/staging/triggers/telegram/verify.ts \
  https://mybotbox.com/api/webhooks/trigger/<path> \
  --secret=<webhook-secret-token>

python3 apps/sat/tests/staging/triggers/telegram/verify.py \
  https://mybotbox.com/api/webhooks/trigger/<path> \
  --secret=<webhook-secret-token>

Telegram's secret token is stored on the trigger's webhook row (the staging admin can read it from webhook.provider_config.webhookSecret). Source: apps/sat/tests/staging/triggers/telegram/.

Troubleshooting

• 401 on every delivery — X-Telegram-Bot-Api-Secret-Token does not match. The most common cause is re-saving the trigger and not re-registering the webhook (MyBotBox does this automatically on save; if you see this, check the deploy logs).
• No fire on group messages — bots only see group messages while Privacy Mode is off. DM /setprivacy to BotFather, pick the bot, choose Disable.
• setWebhook failed — invalid bot token, or Telegram's API returned 400 Bad Request. The trigger surfaces the error in the modal; usually means the token has been revoked. Re-issue with /token on BotFather.
• Duplicate runs — Telegram retries Update deliveries on non-2xx for ~24 hours. The trigger dedupes on update_id via webhook_event_dedup; if you still see dupes, confirm migration 0109 has been applied.