---
title: "Telegram integration"
description: "Get mention alerts and daily digests in a Telegram chat or group."
canonical: https://docs.mentio.dev/alerts/telegram
markdown: https://docs.mentio.dev/alerts/telegram.mdx
---

# Telegram integration

Get mention alerts and daily digests in a Telegram chat or group.

Mentio ships a Telegram bot that posts instant alerts and daily digests to any chat you connect: a
direct message to yourself, or a group your team sits in. Connecting is one tap in Telegram: no
tokens to copy, no chat ids to look up.

## Connecting from the dashboard

The short path is Settings, then Integrations, then Telegram:

1. **Connect Telegram**: the dashboard prepares a single-use link.
2. **Open in Telegram** and press **Start**, or **Add to a group** and pick the group. Either way the
   bot receives the code and the chat appears in the dashboard within a few seconds.
3. Under **Alerts**, attach the chat to the rules that should post there.

The link expires after 15 minutes. If your Telegram client cannot open `t.me` links, send
`/start <code>` to the bot yourself; the code is shown next to the buttons.

A chat can serve any number of rules. Remove it from the Telegram card (or from Alerts) and it is
detached from every rule; the bot never posts to a chat that is not connected.

## What lands in the chat

An instant rule posts each matching mention as it happens:

```
New mention of "your product" on Hacker News
by devkatie
Positive firsthand report of building on the product.
> The text of the post, trimmed.
Open on Hacker News · See it in the feed
```

A daily rule posts one digest at the local time you picked: counts against the previous day, the
split by platform, the top mentions, anything negative, and buying signals. Long digests keep their
headline and drop trailing sections rather than exceed Telegram's message size.

Delivery follows the pipeline rules:

* Only classified mentions that pass the rule's filter are sent; filtered noise never reaches the
  chat.
* One post matching two of your keywords is announced once per chat.
* Telegram limits a bot to roughly one message per second per chat and 20 per minute in groups. A
  rate limit retries up to 5 times; for a busy keyword prefer a daily digest.
* A chat that blocked or removed the bot fails permanently and is surfaced in delivery history
  instead of retrying forever.

## Connecting via the API

Everything the dashboard does is plain REST:

```bash
# 1. Mint a connect link; open it (or hand it to whoever owns the group).
curl -X POST "$MENTIONS_API_URL/v1/telegram/links" \
  -H "Authorization: Bearer $MENTIONS_API_KEY"
# { "url": "https://t.me/MentioBot?start=…", "groupUrl": "https://t.me/MentioBot?startgroup=…",
#   "code": "…", "expiresAt": 1757000000000 }

# 2. After Start is pressed, the chat is a channel of kind "telegram".
curl -H "Authorization: Bearer $MENTIONS_API_KEY" "$MENTIONS_API_URL/v1/channels"

# 3. Point a rule at it.
curl -X POST "$MENTIONS_API_URL/v1/alerts" \
  -H "Authorization: Bearer $MENTIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Telegram alerts", "mode": "instant", "filter": { "minRelevance": 70 }, "channelIds": ["dest_…"] }'
```

`GET /v1/telegram/status` reports whether the deployment has a bot at all and its username.
`DELETE /v1/channels/{channelId}` disconnects a chat.

## Errors

| Code                      | Status | When                                           |
| ------------------------- | ------ | ---------------------------------------------- |
| `telegram_not_configured` | 503    | The deployment has no bot token                |
| `internal_error`          | 502    | Telegram's API failed while looking up the bot |

## Self-hosting: configuring the bot

One bot serves every workspace on a deployment. The integration switches on when the API worker
and the deliverer worker hold its token; without it, Telegram endpoints return
`503 telegram_not_configured` and everything else keeps working.

1. Create a bot with [@BotFather](https://t.me/BotFather) (`/newbot`) and copy its token. Turn
   **group privacy off** (`/setprivacy`, Disable) so the bot sees `/start` in groups.
2. Set the token on both workers, and a webhook secret on the API worker:

```bash
wrangler secret put TELEGRAM_BOT_TOKEN        # api worker and deliverer worker
wrangler secret put TELEGRAM_WEBHOOK_SECRET   # api worker only, any long random string
```

3. Register the webhook once per environment, with the same secret:

```bash
curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -d url="https://<your-api-host>/v1/webhooks/telegram" \
  -d secret_token="$TELEGRAM_WEBHOOK_SECRET" \
  -d 'allowed_updates=["message","channel_post"]'
```

<Callout title="Local development">
  Telegram only delivers webhooks to public https URLs, so the connect round-trip cannot complete
  against plain [http://localhost](http://localhost). Use an https tunnel to your local API worker, or test the flow on a
  deployed environment; sending (test alerts, digests) works locally with just the token.
</Callout>