Alerts with a Telegram bot

Introduction

A Telegram bot is a Telegram account run by a program rather than a person. You do not drive it from the app: you give it orders by calling a web address Telegram provides, the Bot API (opens in a new tab)↗.

That address looks like this, and the last part (sendMessage) is called a method: it is the order you are giving.

https://api.telegram.org/bot<TOKEN>/sendMessage

You hand it two things — which chat, and what text — and Telegram delivers the message. Who makes that call does not matter: a script of yours, a server, an automated task that runs on deploy, or you from a terminal to try it out.

In one line: something calls that address → a message appears in your chat.

The <TOKEN> in that address is the bot's password, and BotFather hands it to you in the first step.

Problem it solves

You want something to alert you on your phone, or in the team's group, without standing up infrastructure. A minimal bot is enough: a deploy fails, an order arrives, someone fills in a form. Anything your system already detects can end up as a message.

Pieces you need to know

Minimum setup

Do the private chat with yourself path first (simplest). Groups come later.

One detail that catches people out: a bot cannot message you until you message it first. Telegram enforces this so nobody can spam you by creating a bot and guessing your username. That is why the third step is tapping Start: without it, sending fails even with a correct token.

1. Get the chat_id

After Start, open a terminal. Pick your OS in the block and paste the BotFather token (looks like 123456:AAH…) where it says paste-your-token-here.

TOKEN="paste-your-token-here"
curl -sS "https://api.telegram.org/bot${TOKEN}/getUpdates"

That command asks Telegram “which messages has my bot received?”, and the answer includes who sent them — which is exactly the value you are after.

What comes back is JSON: the format APIs use to return data, with labels and values inside braces. It arrives long and on a single line; you do not need to understand all of it. Look for a chunk like this (your numbers will differ):

"chat": {
  "id": 123456789,
  "type": "private"
}

That "id" is your chat_id. If the list is empty ("result": []), send another message to the bot and run the command again.

2. Send a test message

Use the same token and the chat_id you just found (numbers only). Replace 123456789 with yours too.

TOKEN="paste-your-token-here"
CHAT_ID="123456789"
curl -sS -X POST "https://api.telegram.org/bot${TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d "{\"chat_id\":${CHAT_ID},\"text\":\"Hello from the guide\"}"

Typical success response: "ok": true and a message_id. You should see the text in Telegram.

That is enough to prove token + chat + sendMessage.

What about a group?

1. Create a group (or use one) and add the bot.
2. Give it permission to send messages.
3. Write something in the group (so there is an update).
4. Run getUpdates again. The group "chat"."id" is often negative (e.g. -100123…). Use it the same way in sendMessage.

If you only need alerts to yourself, stay on the private chat.

Security

• Prefer a bot only for operational alerts, not mixed with personal use.
• You do not need a public URL to send alerts (this flow uses outbound sendMessage).
• Send plain text. Telegram accepts a parse_mode parameter for bold and links, but then it treats characters like _ or . as formatting marks: a branch name or an error message often contains them, and the send fails with an unhelpful error. Start without it.

Common mistakes

Next step

When sendMessage works for you:

1. Wire it to your source — the same POST from a script, a cron, a CI job, or a webhook receiver.
2. Think about format — start with plain text; add Markdown/HTML only if you need it.
3. Secrets — token (and sometimes chat_id) in env vars or your platform’s secret store.

Once sendMessage works, the bot is ready for your own flows: any source that can POST will do.

Guided automations

Apply what you learned in this guide with one of our automations:

• Form → lead alert
• GitHub Actions → Telegram
• Stripe → Telegram