Guide · Verified November 17, 2026

Telegram target guide

Short answer: A Hooks Telegram destination calls sendMessage with your bot token and a chat id; the token stays in a project secret. The message text renders from the event, and Telegram's ok flag decides success even when the HTTP status is 200.

One bot can post into any chat it belongs to, so the destination is just a token, a chat id, and a text template. Parse modes add formatting but require escaping, and a 200 response with ok:false is a real failure that the delivery log records instead of hiding.

1. Create the bot and add it to the chat

Talk to @BotFather, run /newbot, and copy the token (its shape is <id>:<secret>). Add the bot to the target chat or group, then find the numeric chat id: send the bot a message and read getUpdates for a private chat, or use the -100… id of a group. A bot with privacy mode on still receives outbound sends in groups.

2. Store the token as a project secret

Settings → Security → Project secrets → add TELEGRAM_BOT_TOKEN. The config references it as {{secret.TELEGRAM_BOT_TOKEN}}; a literal token is rejected at save time. The token is interpolated into the request path, so one containing /, ?, # or whitespace fails with INVALID_TELEGRAM_TOKEN before anything is sent.

Destination config

{
  "token": "{{secret.TELEGRAM_BOT_TOKEN}}",
  "chatId": "-1001234567890",
  "text": "New {{event.type}}: {{event.subject.title}}\n{{event.subject.url}}",
  "parseMode": "HTML",
  "disableNotification": false
}

3. Write the message and choose a parse mode

`chatId` is a template, so one destination can post into per-repo chats ({{event.repo}}); it must render non-empty or the delivery fails with EMPTY_TELEGRAM_CHAT_ID. `text` defaults to the event title and URL, and an empty render fails with EMPTY_TELEGRAM_MESSAGE. parseMode accepts HTML or MarkdownV2, and Hooks does not escape template output, so escape the rendered text yourself. disableNotification sends the message silently.

Request Hooks sends

POST https://api.telegram.org/bot<token>/sendMessage
Content-Type: application/json

{"chat_id":"-1001234567890","text":"<b>Login fails on Safari</b>\nhttps://github.com/acme/app/issues/7","parse_mode":"HTML"}

4. Handle ok:false and rate limits

Telegram answers JSON with an ok flag and can report failures as HTTP 200, so Hooks reads the body: {"ok":false,"error_code":400,"description":"chat not found"} fails permanently as TELEGRAM_ERROR with the reason. HTTP 429, or error_code 429 in the body, retries as TELEGRAM_RATE_LIMITED and records parameters.retry_after. 408, 425, and 5xx retry; other 4xx are permanent; 3xx is blocked. Send a test event from the endpoint to check the token and chat before a real event arrives; the delivery log shows Telegram's reply.

Frequently asked questions

How do I find the chat id?

For a private chat, message the bot and read getUpdates; the id is numeric. Group ids usually start with -100. Add the bot to the group first, otherwise Telegram returns chat not found.

Why is a 200 response recorded as failed?

Telegram can return HTTP 200 with ok:false and an error_code. Hooks checks the body, records TELEGRAM_ERROR with the description, and does not report the delivery as succeeded.

Does Hooks escape MarkdownV2 or HTML?

No. The template output is sent as-is, so characters that are special in the chosen parse mode must be escaped in the template or dropped from it. Plain text with no parseMode avoids the problem.

Can one bot post to several chats?

Yes. Keep one token secret and use a per-destination chat id, or render chatId from the event so the same destination routes to different chats.

Reference

Keep going

Trigger AI agents from webhooksPoint the provider's webhook at a Hooks endpoint, add one destination per agent target with filters and a task template, and every matching event becomes an agent task with retries and a delivery log.Grok Bot target guideA Hooks destination POSTs one JSON task to your Grok Bot routine URL with a Bearer key; a 2xx means the task was queued. Configure the routine URL and key once, then map event fields into the task template.T3 Code target guideA Hooks destination POSTs JSON to your T3 Code task's On a webhook URL; T3 Code answers 202 when the agent run is accepted. Keep the URL (it carries a token) in a project secret and sign the body when the task requires it.Paseo target guideA Hooks destination POSTs one manual-run dispatch to Paseo Hub (on: manual.run) with project, trigger, actor, and rendered input. Hub answers 200 with a triggerRunId that Hooks records on the delivery.Slack target guideA Hooks Slack destination posts either to an incoming webhook URL already bound to a channel, or to chat.postMessage with a bot token and channel id so one app can reach many channels.Discord target guideA Hooks Discord destination POSTs a message to a channel's incoming webhook URL; that URL carries the token, so it lives in a project secret. Content is plain text with optional embeds, and Discord answers 204 when the message is accepted.Microsoft Teams target guideA Hooks Microsoft Teams destination POSTs a MessageCard to an incoming webhook URL from an Office 365 Connector, Power Automate, or Workflows; the URL is a project secret. Connectors answer 200 with the body 1, and Workflows answer 202.Lark target guideA Hooks Lark destination posts a text message to a group's custom bot webhook on open.larksuite.com. The URL is a project secret, and when the bot's signature check is on, Hooks adds the timestamp and HMAC-SHA256 signature the bot requires.