How to Set Up Telegram Alerts in Trackz

Overview

The Telegram integration delivers alert messages via a bot you own. Trackz uses the Telegram Bot API to send Markdown-formatted messages to any chat — a private conversation, a group, or a public channel. You control the bot and can revoke access at any time.

Prerequisites

• A Telegram account
• The channel, group, or user chat where alerts should be delivered
• A Trackz account on any plan

Step 1: Create a Telegram Bot via BotFather

1. Open Telegram and search for @BotFather.
2. Start a conversation and send /newbot.
3. Follow the prompts: choose a display name, then a username ending in bot (e.g., mytrackz_alerts_bot).
4. BotFather will reply with your bot token — a string like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ.
5. Copy this token. Treat it like a password — anyone with it can send messages as your bot.

Step 2: Get Your Chat ID

The chat ID tells Trackz where to deliver messages.

For a private chat with the bot:

1. Start a conversation with your new bot (search for it by username and click Start).
2. Send any message to the bot.
3. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in a browser.
4. Find the "chat" object in the response — the "id" field is your chat ID (a positive integer).

For a group or channel:

1. Add your bot to the group or channel (as a member or admin).
2. Send a message in the group/channel.
3. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates — the chat ID will be a negative number (e.g., -1001234567890).

Alternatively, add @userinfobot to your group to retrieve the chat ID without calling the API.

Step 3: Add the Integration in Trackz

1. In your Trackz dashboard, go to Settings → Integrations.
2. Click Add Integration.
3. Select Telegram from the integration picker.
4. Enter a name for this integration.
5. Paste your bot token into the Bot Token field.
6. Paste the chat ID (including the minus sign for groups/channels) into the Chat ID field.
7. Click Save.

Testing Your Integration

1. In Settings → Integrations, find your Telegram integration and click Send test.
2. A test message should appear in your Telegram chat within seconds.
3. The message will include a bold title, description, and a code block with sample metadata.

Alert Message Format

Trackz sends Telegram messages using Markdown formatting:

**Downtime detected: api.example.com**

Your monitor api.example.com is not responding. HTTP status: 503.

```json
{
  "monitor": "api.example.com",
  "event": "uptime.down",
  "statusCode": 503
}

## Troubleshooting

**Test message not received**

- Verify the bot token is correct — go to BotFather and use `/mybots` to confirm.
- Ensure you sent at least one message to the bot (or in the group) before fetching updates; the API only returns recent messages.
- For channels: make sure the bot has **Post Messages** admin permission.

**"Chat not found" error in integration history**

- Double-check the chat ID. A missing minus sign on a group chat ID is the most common cause.
- If you removed the bot from the group, re-add it and re-test.

**Messages arrive but formatting looks broken**

- Trackz sends messages with `parse_mode=Markdown`. Avoid using underscores or asterisks in your monitor names, as they may confuse the Markdown parser.

**Bot was deleted or token revoked**

- Create a new bot via BotFather, update the integration in Trackz with the new token, and re-test.