> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/telegram.md).

# Telegram

https\://core.telegram.org/bots

The Appmixer Telegram connector talks to the **Telegram Bot API** and authenticates with a **Bot Token**. There is no OAuth app to register — you create a bot with **@BotFather** inside Telegram, copy its token and paste it into Appmixer.

A bot only sees chats it is a member of. To read public channels you do not own, use the [Telegram User](/connector-configuration/telegram-user.md) connector, which signs in as a user account.

{% hint style="warning" %}
The bot token grants **full control of the bot** (reading its messages, sending as the bot, changing its webhook). Treat it exactly like a password and never commit it to a repository or share it in a chat.
{% endhint %}

***

## 1. Create a Bot with @BotFather

1. Open Telegram (mobile or desktop) and search for **@BotFather** — the account with the blue verified checkmark.
2. Start the chat and send `/newbot`.
3. Enter a **display name** for the bot (e.g. `Appmixer Notifier`). This is what users see in the chat header.
4. Enter a **username** for the bot. It must be unique and end with `bot` (e.g. `appmixer_notifier_bot`).
5. BotFather replies with the token, in the form:

   ```
   123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
   ```
6. Copy the token — you will paste it into Appmixer in Step 3.

### Using an existing bot

If the bot already exists, send `/mybots` to **@BotFather**, pick the bot and choose **API Token**. If the token has leaked, use **Revoke current token** — the old token stops working immediately and every Appmixer connection using it must be updated.

***

## 2. Configure the Bot for Your Use Case

Telegram restricts what a bot can see and do. Set this up **before** building flows, otherwise triggers stay silent and sends fail with `403`.

### Direct messages (1:1 chats)

A bot **cannot start a conversation**. The user must open the chat with the bot and press **Start** (`/start`) at least once. Only after that can the bot send messages to that user.

### Groups

1. Add the bot to the group like any other member.
2. By default **Group Privacy** is on, which means the bot only receives messages that are commands (`/command`), replies to its own messages, or that mention `@yourbot`.
3. To receive **all** group messages, send `/mybots` to @BotFather → select the bot → **Bot Settings** → **Group Privacy** → **Turn off**.

{% hint style="info" %}
Changing Group Privacy only takes effect after the bot is **removed from the group and added again**.
{% endhint %}

### Channels

Add the bot to the channel as an **administrator**. Posting to a channel requires the *Post Messages* right; the **New Message** trigger only receives channel posts when *Include Channel Posts* is enabled and the bot administers the channel.

***

## 3. Connect in Appmixer

When you add a Telegram component to a flow, Appmixer asks you to authenticate:

| Field         | Value                 |
| ------------- | --------------------- |
| **Bot Token** | The token from Step 1 |

Appmixer verifies the token with a `getMe` call and names the connection after the bot's username (e.g. `@appmixer_notifier_bot`), so it is easy to tell several bots apart.

***

## 4. Find the Chat ID

Every Telegram component takes a **Chat ID**. There are two accepted forms:

| Chat type                      | Value to use                                                |
| ------------------------------ | ----------------------------------------------------------- |
| Public channel or public group | `@channelusername`                                          |
| Private chat                   | Numeric user ID, e.g. `6412345678`                          |
| Group                          | Negative number, e.g. `-987654321`                          |
| Supergroup / channel           | Negative number starting with `-100`, e.g. `-1002345678901` |

The simplest way to obtain it: build a flow with the **New Message** trigger, leave *Chat ID* empty, send a message to the bot (or in the group) and read `chat.id` from the trigger output.

***

## 5. Triggers and Webhooks

The **New Message** and **New Callback Query** triggers are webhook-based. When a flow starts, Appmixer calls `setWebhook` and points the bot at your Appmixer instance.

Things worth knowing:

* **Telegram allows exactly one webhook per bot.** Every Appmixer Telegram trigger of the same bot shares that single registration. Do not use the same bot in another platform (Make, n8n, a custom script) or with `getUpdates` polling — whoever registers last wins, and the other side stops receiving updates and may see `409 Conflict`.
* **Stopping a flow does not remove the webhook**, because sibling flows using the same bot may still need it. An unused registration is harmless — updates arrive, match no listener and are dropped.
* **Your Appmixer instance must be reachable from the internet over HTTPS** with a certificate Telegram accepts. This matters for self-managed installations: Telegram will not deliver updates to `localhost`, a private IP or a self-signed endpoint.
* Each update is verified with a secret token Telegram sends in the `X-Telegram-Bot-Api-Secret-Token` header, so forged requests to the webhook URL are rejected.

***

## Limits

| Limit                           | Value                                                                    |
| ------------------------------- | ------------------------------------------------------------------------ |
| Messages per second (all chats) | \~30 — Appmixer throttles to 25/s so the bot does not trip flood control |
| Messages per minute per group   | \~20, enforced by Telegram                                               |
| **Send Photo** upload size      | 10 MB                                                                    |
| **Send Document** upload size   | 50 MB                                                                    |
| **Get File** download size      | 20 MB (Bot API limit)                                                    |

***

## Troubleshooting

### 401 — Authentication failed

The bot token is invalid or was revoked. Get the current token from @BotFather (`/mybots` → **API Token**) and update the Appmixer connection.

### 403 — Forbidden

* The bot is not a member of the chat, or was removed from it.
* The user blocked the bot, or never pressed **Start** in a private chat (a bot cannot message a user first).
* The bot lacks the required admin right — e.g. posting to a channel without *Post Messages*.

### 400 — "chat not found"

The Chat ID is wrong. Use `@channelusername` for public chats, or the numeric ID (negative for groups, prefixed with `-100` for supergroups and channels). Note that a private group's ID is not visible in the Telegram UI — read it from the **New Message** trigger output.

### 409 — Conflict

Another process is polling this bot with `getUpdates`, or a different webhook is registered for it. Use a dedicated bot for Appmixer.

### 429 — Rate limit exceeded

Telegram's flood control kicked in. The error carries a `retry_after` value in seconds. Reduce the send rate, or split the traffic across several bots and chats.

### The trigger never fires

* In a group, **Group Privacy** is still on, so the bot only sees commands, replies and mentions — turn it off in @BotFather and re-add the bot to the group.
* For channel posts, the bot is not an administrator, or *Include Channel Posts* is off on the trigger.
* Another system took over the bot's webhook — see the `409` note above.
* The Appmixer instance is not publicly reachable over HTTPS, so Telegram cannot deliver the update.

***

## Resources

* [Telegram Bots: an introduction for developers](https://core.telegram.org/bots)
* [Bot API reference](https://core.telegram.org/bots/api)
* [BotFather commands](https://core.telegram.org/bots/features#botfather)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/connector-configuration/telegram.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.