> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Telegram

[Back to messaging or digital channels](https://koreai.mintlify.site/agent-platform/channels.md#messaging-or-digital-channels)

Connect a Telegram bot to your agent so users reach it in private chats, groups, and supergroups. You create the bot in Telegram and give Artemis its username and token. Artemis then registers a protected webhook with Telegram for you.

The setup requires:

1. [Create the Telegram bot](#create-the-telegram-bot) with BotFather.
2. [Artemis channel configuration](#artemis-channel-configuration): enter the bot's username and token, then create the connection.
3. [Verify the connection](#verify-the-connection) in a private chat, a group, and with buttons and media.

After you create the connection, Telegram posts each update to Artemis, and the agent replies in the same chat.

**Important considerations**

* **The bot username selects the connection**: Artemis builds the webhook path from it and routes each update by it. You can't change it after creation.
* **Artemis registers the webhook for you**: Don't call `setWebhook` yourself. Telegram keeps one webhook per bot, so a manual call replaces the one Artemis registered and stops the connection.
* **One active connection per bot token**: Artemis rejects a second active connection that uses the same token, so it can't silently replace the first one's webhook.
* **Treat BotFather messages as secrets**: Anyone with the bot token can call the Bot API. Keep it out of tickets, screenshots, browser code, logs, and client-side configuration.

## Prerequisites

Confirm these before you start.

* A Telegram account to talk to BotFather.
* An Artemis runtime reachable over public HTTPS, with outbound access to `api.telegram.org`.
* Artemis project access with permission to open **Deployments** > **Channels**, and a deployed agent in the environment you intend to bind.

***

## How Artemis routes Telegram messages

Four pieces carry the integration. You supply the first two, and Artemis manages the rest.

| Piece | Owner | What it does |
| - | - | - |
| **Bot Username** | BotFather | Routes incoming updates. Artemis puts the normalized username at the end of the webhook path and matches each update to this connection by it. |
| **Bot Token** | BotFather | Authorizes every outbound Bot API call: `setWebhook`, `sendMessage`, typing indicators, callback answers, and media downloads. |
| Secret token | Artemis | Proves each update came from Telegram. Artemis generates it, encrypts it, and never asks you for it. |
| **Webhook URL** | Artemis | Receives updates. Artemis builds it from the bot username and registers it during creation. |

***

## Create the Telegram bot

Do this in Telegram before you open Artemis. Select **Open BotFather** or **Open Bot API documentation** in the setup guide to jump straight there.

**1. Open BotFather**

1. Search Telegram for `@BotFather`, or open [t.me/botfather](https://t.me/botfather).
2. Confirm the blue verification badge beside the name. Fake BotFather accounts exist to harvest tokens.
3. Select **Start**.

**2. Create the bot with /newbot**

1. Send `/newbot`.
2. Enter a display name. Users see it at the top of the chat, and you can change it later.
3. Enter a username. It must be 5 to 32 Latin letters, numbers, or underscores, and end in `bot`.

Choose the username carefully. Telegram never lets you change it, and Artemis builds the webhook path from it. BotFather replies with the bot link and the token.

**3. Copy the username and token**

1. Copy the username without the `t.me/` prefix. Artemis strips a leading `@`, so either form works.
2. Copy the full token, including the numeric bot ID and the colon before the secret part.

To retrieve either value later, send `/mybots`, select the bot, and select **API Token**.

**4. Configure discovery (optional)**

Use these BotFather commands to shape what users see. They don't affect message delivery or replace the webhook.

| Command | What it sets |
| - | - |
| `/setdescription` | The text on the empty chat screen, before a user selects **Start** |
| `/setabouttext` | The short line on the bot's profile page |
| `/setuserpic` | The bot's profile photo |
| `/setcommands` | The command menu Telegram suggests when a user types `/` |

**5. Decide group behavior**

Artemis processes a group or supergroup message only when it mentions the bot, replies to one of the bot's messages, or uses `/start` or `/help`. Ordinary group chatter never reaches the agent, even if you turn off [privacy mode](https://core.telegram.org/bots/features#privacy-mode) in BotFather.

**6. Use a separate bot for each environment**

Create one bot for development and another for production, each with its own token and its own Artemis connection.

***

## Artemis channel configuration

Create the connection with the bot's values. Artemis registers the webhook as part of creation.

1. Open Artemis and select the project.

2. Go to **Deployments** > **Channels** > **Telegram** > **+ New**. The **New Telegram Connection** dialog opens, with the setup guide on the left and the connection fields on the right.

3. Configure the fields:

   | Artemis field | Source / Notes | What it controls |
   | - | - | - |
   | **Display Name** | You choose it | The label operators see in the connections list. Routing ignores it. |
   | **Bot Username** | BotFather's confirmation message | The routing key. Enter the exact BotFather username, preferably without `@`. Don't enter the display name, a numeric bot or chat ID, a token fragment, or a `t.me` URL. |
   | **Bot Token** | BotFather's confirmation message | Authorizes every outbound Bot API call. Artemis encrypts it on save. |
   | **Environment** | Your published environments | The environment whose active deployment answers messages. Leave the working copy default only while you develop. |
   | **Provider Verification Strength** | Defaults to **Weak** | How far the runtime trusts Telegram's identity assertion when it links a user to an existing session. Choose **Strong** only when you base continuity and account-linking decisions on it. |
   | **Initial Status** | Defaults to **Active** | **Active** takes traffic immediately. **Inactive** saves the connection disabled until you activate it. |

4. Select **Create**.

When you select **Create**, Artemis completes the Telegram side in one step:

* Generates a high-entropy secret token and stores it encrypted.
* Calls `setWebhook` with the connection-specific URL, which ends with the normalized bot username.
* Subscribes to `message` and `callback_query` updates only. Telegram channel posts and other update types stay outside the connection.
* Drops updates still pending from an earlier webhook, so stale events never reach the new connection.

If registration fails, Artemis rolls back the creation rather than leaving a connection that can't receive anything.

***

## Verify the connection

Each check exercises a different path. A bot that answers private messages can still fail in groups or on buttons.

1. Open the bot by its exact username, select **Start**, and send a short, distinctive message. Confirm one session and one reply.
2. Send `/start`, or open a [deep link](https://core.telegram.org/bots/features#deep-linking) with a start payload. Artemis passes it to the agent as a welcome action, with the payload as its value.
3. Add the bot to a group, then mention it with `@BotUsername`, reply to one of its messages, and send `/start` or `/help`. Confirm each reaches the agent and an unrelated message doesn't.
4. Select a button on an inline keyboard. Confirm the loading spinner clears and the action returns to the same chat session.
5. Send each media type your agent accepts, including a caption at least once.

Artemis downloads the largest photo size or the attached file through `getFile` before the agent processes it.

| Media type | What to confirm |
| - | - |
| `text` | The agent receives and answers it. |
| `photo`, `document`, `audio`, `video`, `voice` | The download succeeds and the agent processes the file and its caption. |
| `inline buttons` | The selection returns to the same session with the right action. |

***

## Telegram limits

Artemis applies these limits before it calls the Bot API. Design agent responses to fit them.

| Area | Limit |
| - | - |
| Text | 1 to 4096 characters per message. Artemis sends a single ellipsis for an otherwise empty response. |
| Inline keyboards | Up to 10 rows. Button text up to 64 characters. |
| Callback data | 64 bytes. Keep authored action IDs and values short. |
| Media | 20 MB per file download. Artemis rejects larger files before upload. |
| Chats | Private chats, groups, and supergroups under the mention and reply rule. Artemis ignores channel posts. |

***

## Security and lifecycle

A Telegram connection depends on two secrets and one webhook registration.

* **Secret header**: Telegram returns the generated secret in the `X-Telegram-Bot-Api-Secret-Token` header on every update. Artemis compares it with the stored value before processing, so any proxy in front of Artemis must preserve the header.
* **Bot token**: It authorizes every Bot API call and appears in request URLs. Store it only in Artemis, and redact it from logs and diagnostics.
* **Token rotation**: If BotFather revokes or regenerates the token, update it in the **Credentials** tab so Artemis can send messages and re-register the webhook.
* **Diagnosis**: Use `getWebhookInfo` only through a secure operator tool to confirm the URL and last error. Never call `setWebhook` or delete the webhook outside Artemis.
* **Duplicates**: Artemis deduplicates on Telegram's `update_id`, so a Telegram retry never creates a second agent turn.

***

## Manage the channel connection

Open a Telegram connection from **Deployments** > **Channels** > **Telegram** to manage it. The page has a header, three tabs, and a summary panel on the right.

**Header.** Shows the connection name, its status, and when it last changed. The **...** overflow menu holds the connection-level actions.

**Summary panel.** Stays visible on every tab.

| Field | Description |
| - | - |
| **Channel** and **Connection Type** | Read **Telegram** and **Channel Connection**. |
| **Identifier** | The normalized bot username this connection routes on. |
| **Credentials** | Reads **Configured** once credentials save. |
| **Webhook URL** | The URL Artemis registered with Telegram, with a copy control. If `getWebhookInfo` reports a different URL, something outside Artemis re-registered the bot. |
| **Created** and **Updated** | Date and time of creation and of the last change. |

> [tab] Credentials
>
> Artemis encrypts the token after you save it. Leave the field blank to keep the current value, or enter a new token to replace it.
>
> | Field | Description |
> | - | - |
> | **Use Auth Profile** | Turn it on, then select a saved auth profile from the list in place of the token field. |
> | **Bot Token** | Replace it here whenever BotFather issues a new token. |
>
> Select **Save Credentials** to apply your changes.

> [tab] Configuration
>
> Update how the connection behaves. **Telegram Settings** holds the provider-specific fields.
>
> | Setting | Description |
> | - | - |
> | **Display Name** | The label operators see in the connections list. |
> | **Provider Verification Strength** | How far the runtime trusts Telegram's identity assertion. |
> | **Bot Username** | Read-only, with a copy control. To target a different bot, create a new connection. |
> | **Enable Streaming** | Sends the response to Telegram as the agent generates it. |
> | **Chunk Size (characters)** | The minimum characters Artemis buffers before each update. Lower values feel faster and make more API calls. |
> | **Message template** | The authorization message the connection sends when a tool needs the user to authorize. |
> | **Webhook URL** | The registered URL, with a copy control. |
>
> Insert variables into the **Message template** from the chips below the editor, select **Show more** for the full list, and select **Show preview** to check the result.
>
> | Scope | Variables |
> | - | - |
> | Whole message | `{{total}}`, `{{completed}}`, `{{remaining}}` |
> | Repeat block | `{{#authorizations}}` ... `{{/authorizations}}`, which repeats once per pending authorization |
> | Inside the block | `{{profileName}}`, `{{authLink}}`, `{{authUrl}}`, `{{index}}`, `{{count}}` |
>
> Select **Save Changes** to apply your changes.

> [tab] Deployment
>
> Choose which deployed version answers the bot.
>
> | Setting | Description |
> | - | - |
> | **Environment** | Under **Environment Binding**. Selects which deployed version handles incoming messages. |
> | **Active Deployment** | Shows the bound version and when someone deployed it. |
>
> A connection on **Working Copy (draft)** shows a warning, because the working copy changes as you edit the agent. Bind the connection to a published environment before you open the bot to users. Select **Save Changes** after you switch the environment.

***

## Troubleshoot connection issues

Most failures trace to the token, the webhook registration, or the group mention rule.

| Symptom | Likely cause | Recommended action |
| - | - | - |
| Creation fails with a webhook registration error | Artemis can't reach Telegram or the token is wrong | Verify the Bot Token, the public HTTPS runtime URL, outbound access to `api.telegram.org`, and that BotFather allows `setWebhook` for the bot. |
| Creation returns a conflict | The token already belongs to another active Telegram connection in the project | Reuse or deactivate that connection instead of replacing its webhook. |
| Updates return 401 | An external `setWebhook` call replaced the secret, or a proxy dropped the secret header | Re-save or recreate the connection in Artemis, and preserve `X-Telegram-Bot-Api-Secret-Token`. |
| Private messages don't arrive | The user hasn't started the bot, or the webhook points elsewhere | Confirm the user selected **Start**, `getWebhookInfo` shows this connection's URL, `allowed_updates` includes `message`, and the connection is **Active**. |
| Private chats work but groups don't | The message doesn't meet the mention and reply rule | Mention the exact bot username or reply to its message, test `/start` or `/help`, and confirm the bot is a group member. |
| Text works but buttons don't | Callback updates fail or the action is gone | Confirm `allowed_updates` includes `callback_query`, the callback payload fits 64 bytes, and the authored action still exists. |
| Text works but files fail | Unsupported type, oversized file, or a changed token | Confirm your agent accepts the media type, `getFile` succeeds with the current token, the file is 20 MB or smaller, and your attachment policy accepts it. |
| Messages sent before creation never arrive | Expected behavior | The initial `setWebhook` call drops pending updates so stale events can't enter the new connection. |

***

## Telegram reference

Use these pages when you need detail beyond what this article covers.

| Resource | Use it for |
| - | - |
| [Bots: an introduction](https://core.telegram.org/bots) | How Telegram bots work. |
| [BotFather](https://core.telegram.org/bots/features#botfather) | Every BotFather command. |
| [Privacy mode](https://core.telegram.org/bots/features#privacy-mode) | What Telegram sends a bot in groups. |
| [Bot API](https://core.telegram.org/bots/api) | `setWebhook`, `getWebhookInfo`, and message limits. |

***

**Related articles:**

* [Channels](https://koreai.mintlify.site/agent-platform/channels.md)
* [Set up WhatsApp](https://koreai.mintlify.site/agent-platform/channels/whatsapp)
* [Set up Slack](https://koreai.mintlify.site/agent-platform/channels/slack)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.