Set up Telegram

Back to 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:

Create the Telegram bot with BotFather.
Artemis channel configuration: enter the bot’s username and token, then create 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.

Open BotFather

Search Telegram for @BotFather, or open t.me/botfather.
Confirm the blue verification badge beside the name. Fake BotFather accounts exist to harvest tokens.
Select Start.

Create the bot with /newbot

Send /newbot.
Enter a display name. Users see it at the top of the chat, and you can change it later.
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.

Copy the username and token

Copy the username without the t.me/ prefix. Artemis strips a leading @, so either form works.
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.

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 `/`

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 in BotFather.

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.

Open Artemis and select the project.
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.

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.

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.

Open the bot by its exact username, select Start, and send a short, distinctive message. Confirm one session and one reply.
Send /start, or open a deep link with a start payload. Artemis passes it to the agent as a welcome action, with the payload as its value.
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.
Select a button on an inline keyboard. Confirm the loading spinner clears and the action returns to the same chat session.
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.

Credentials
Configuration
Deployment

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.

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.

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	How Telegram bots work.
BotFather	Every BotFather command.
Privacy mode	What Telegram sends a bot in groups.
Bot API	`setWebhook`, `getWebhookInfo`, and message limits.

Related articles:

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Prerequisites

How Artemis routes Telegram messages

Create the Telegram bot

Artemis channel configuration

Verify the connection

Telegram limits

Security and lifecycle

Manage the channel connection

Troubleshoot connection issues

Telegram reference

​Prerequisites

​How Artemis routes Telegram messages

​Create the Telegram bot

​Artemis channel configuration

​Verify the connection

​Telegram limits

​Security and lifecycle

​Manage the channel connection

​Troubleshoot connection issues

​Telegram reference

Prerequisites

How Artemis routes Telegram messages

Create the Telegram bot

Artemis channel configuration

Verify the connection

Telegram limits

Security and lifecycle

Manage the channel connection

Troubleshoot connection issues

Telegram reference