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
- sendMessagehttps://core.telegram.org/bots/api#sendmessage
- Making requestshttps://core.telegram.org/bots/api#making-requests
- Payload templateshttps://hooks.events/docs/templates.md
- Secrets & rotationhttps://hooks.events/docs/secrets.md