> ## Documentation Index
> Fetch the complete documentation index at: https://learn.getodin.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Telegram Toolkit
> Connect your Telegram bot to agents and workflows to send messages, manage chats, and trigger automations from incoming messages.
The Telegram Toolkit lets agents and workflows interact with Telegram bots. It supports sending and editing messages, sending media, managing chat members, generating invite links, and registering webhooks to trigger workflows from incoming messages.
Telegram bots and their credentials are managed through a Telegram bot called **@BotFather** — there is no web developer console.
## Prerequisites
| Requirement | Detail |
| ---------------- | ------------------------------------ |
| Telegram account | Required to interact with @BotFather |
## Step 1 — Create a Telegram Bot
Open Telegram and start a conversation with [@BotFather](https://t.me/BotFather).
Send the command `/newbot` and follow the prompts:
| Prompt | Detail |
| -------- | -------------------------------------------------- |
| Bot name | A human-readable display name (e.g. `My App`) |
| Username | Must be unique and end in `bot` (e.g. `myapp_bot`) |
BotFather will reply with a success message containing your bot token — it looks like `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`. Copy and save it securely.
Set a profile picture that matches your application logo using the `/setuserpic` command in BotFather. A recognizable image makes your bot look professional and trustworthy to users.
## Step 2 — Add the Token to EK
1. In the workflow, add a Telegram toolkit step.
2. Click **Select a Connection** → **Create a Connection**.
3. Enter a **Connection Name** and paste your bot token.
4. Click **Save**.
1. Open your agent in the **Agent Builder**.
2. Go to the **Toolkits** tab in the left sidebar.
3. Find **Telegram** and click **Add to Agent**.
4. Paste your bot token under **Telegram Bot Token**.
5. Click **Save**.
## Managing Your Token
Your bot token is the master key to your bot. Do not share it, commit it to public repositories, or expose it in client-side code.
If your token is accidentally leaked, revoke it immediately:
1. Message @BotFather
2. Send `/mybots`
3. Select your bot
4. Tap **API Token** → **Revoke current token**
A new token will be generated. Update the connection in EK with the new value.
## Available Tools
| Tool | Description |
| ------------------------- | ------------------------------------------------------ |
| **New Message** (Trigger) | Start a workflow when a message is sent to your bot |
| **Send Text Message** | Send a text message from your bot to any chat |
| **Send Media** | Send a photo, video, sticker, or animated GIF |
| **Edit Message Text** | Update the text of a previously sent message |
| **Delete Message** | Delete a message from a chat |
| **Get Chat Info** | Retrieve metadata about a chat |
| **Get Chat Member** | Look up a user's membership status in a chat |
| **Create Invite Link** | Generate an invite link for a group or channel |
| **Register Webhook** | Tell Telegram to forward bot messages to your workflow |
| **Deregister Webhook** | Remove the webhook and stop message delivery |
## Trigger — New Message
Starts a workflow automatically whenever someone sends a message to your Telegram bot.
**Setup:**
Add a **New Message** trigger as the first step of your workflow. Copy the `/tool-webhook/{workflow-id}` URL from the trigger configuration panel.
Use the **Register Webhook** step to tell Telegram to deliver messages to that URL. Run it once — see [Register Webhook](#register-webhook) below.
Send a test message to your bot. The workflow fires and all message data is available as variables.
**Available trigger variables:**
| Variable | Description |
| -------------------------------------------- | --------------------------------------------------- |
| `{{ trigger.body.message.text }}` | The message text the user sent |
| `{{ trigger.body.message.chat.id }}` | The chat ID — use this as Chat ID in all send steps |
| `{{ trigger.body.message.from.id }}` | The sender's Telegram user ID |
| `{{ trigger.body.message.from.first_name }}` | The sender's first name |
| `{{ trigger.body.message.from.username }}` | The sender's username (may be empty) |
| `{{ trigger.body.message.message_id }}` | The ID of the incoming message |
| `{{ trigger.body.update_id }}` | The unique update ID from Telegram |
## Messaging Actions
### Send Text Message
Sends a text message from your bot to any Telegram chat.
**Key inputs:**
| Input | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chat ID | The chat to send to. For the person who triggered the workflow, use `{{ trigger.body.message.chat.id }}`. For a fixed group or channel, paste its numeric ID. |
| Message | The text to send. Mix static text with variables, e.g. `Hello {{ trigger.body.message.from.first_name }}, your request was received.` |
| Format | Leave blank for plain text. Set to `HTML` for `bold` / `italic`. Set to `MarkdownV2` for Markdown (special characters are auto-escaped). |
| Disable Web Page Preview | Set to `true` to suppress link previews |
| Message Thread ID | Optional — only relevant for Forum supergroups |
| Reply Markup | Optional — a JSON object for inline keyboards or custom reply keyboards |
**Referencing the output in downstream steps:**
* Message ID (needed for Edit or Delete later): `{{ step.output.message_id }}`
* Chat ID: `{{ step.output.chat_id }}`
### Send Media
Sends a photo, video, sticker, or animated GIF to a Telegram chat.
**Key inputs:**
| Input | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| Chat ID | The chat to send to |
| Media Type | Must be exactly one of: `photo`, `video`, `sticker`, `animation` |
| Media URL | A publicly accessible HTTPS URL to the file — Telegram fetches it directly |
| Media ID | Alternatively, a Telegram `file_id` from a previously uploaded file. Provide either Media URL or Media ID, not both. |
| Caption | Optional text shown below the media. Supports HTML/MarkdownV2 via Format. |
| Format | Parse mode for the caption |
| Message Thread ID | Optional — for forum supergroup topics |
If neither Media URL nor Media ID is provided, the step returns an error. The URL must be publicly reachable — local or private URLs will not work.
### Edit Message Text
Updates the text of a message previously sent by your bot.
**Key inputs:**
| Input | Description |
| ---------- | ----------------------------------------------------------------------------------- |
| Chat ID | The chat where the original message is |
| Message ID | The `message_id` from the Send Text Message output — `{{ step.output.message_id }}` |
| Text | The new message content |
| Format | Parse mode for the new text (blank = plain text, `HTML`, or `MarkdownV2`) |
**Example use case:** Send "Processing your request…" first. Run the workflow logic. Then edit that message with the final result — the user sees one message instead of two.
### Delete Message
Deletes a message from a chat.
**Key inputs:**
| Input | Description |
| ---------- | ----------------------------------------- |
| Chat ID | The chat containing the message |
| Message ID | The `message_id` of the message to delete |
Bots can only delete their own messages unless the bot is an admin in the chat. Telegram also imposes a time limit — messages older than 48 hours generally cannot be deleted by bots.
## Chat & Member Actions
### Get Chat Info
Retrieves metadata about a chat.
**Key inputs:**
| Input | Description |
| ------- | ------------------- |
| Chat ID | The chat to look up |
**Referencing values in downstream steps:**
* Chat title: `{{ step.output.title }}`
* Description: `{{ step.output.description }}`
* Invite link: `{{ step.output.invite_link }}`
### Get Chat Member
Looks up a specific user within a chat and returns their membership status and role.
**Key inputs:**
| Input | Description |
| ------- | --------------------------------------------------------------------------------------------------------------------- |
| Chat ID | The chat to look in |
| User ID | The Telegram user ID to look up. For the person who triggered the workflow, use `{{ trigger.body.message.from.id }}`. |
**Referencing values in downstream steps:**
* Status: `{{ step.output.status }}`
* Username: `{{ step.output.username }}`
**Possible status values:** `creator`, `administrator`, `member`, `restricted`, `left`, `kicked`
**Example use case:** Check `{{ step.output.status }}` — if it equals `left` or `kicked`, skip sending the message and handle the error instead.
### Create Invite Link
Generates a new invite link for a group or channel.
The bot must be an administrator with the "Invite Users" permission in the target chat.
**Key inputs:**
| Input | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Chat ID | The group or channel |
| Name | Optional label for the link (up to 32 characters), visible in the Telegram admin panel |
| Expire Date | Optional. An ISO-8601 string when the link expires, e.g. `2026-12-31T23:59:59Z`. Converted to a unix timestamp internally. |
| Member Limit | Optional. Max number of people who can join via this link (1–99,999) |
**Referencing the link in downstream steps:**
* Invite URL: `{{ step.output.invite_link }}`
`expire_date` in the output is a unix timestamp (integer seconds), not ISO format. `creates_join_request` will be `true` if the chat requires admin approval for new members.
## Webhook Setup Actions
These two steps connect a New Message trigger to your bot. Run them once per workflow.
### Register Webhook
Tells Telegram to start forwarding messages from your bot to your workflow URL.
**Key inputs:**
| Input | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| URL | The `/tool-webhook/{workflow-id}` URL from the New Message trigger panel |
| Allowed Updates | Set to `["message"]` to receive only regular messages (recommended). Leave blank to use the same default. |
| Secret Token | Optional but recommended. Any random string (e.g. `my-secret-abc123`). Telegram includes it in every webhook request header so you can verify requests are genuine. |
| Drop Pending Updates | Set to `true` to ignore messages that arrived before the webhook was registered |
Create a workflow with a New Message trigger. Copy the `/tool-webhook/{workflow-id}` URL from the trigger panel.
In a separate one-time workflow or manual test run, add a **Register Webhook** step and fill in the inputs above.
Run the step. Then send a message to your bot — your main workflow should now fire.
Alternatively, register via curl for a quick one-time setup:
```bash theme={null}
curl -X POST "https://api.telegram.org/bot/setWebhook" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/tool-webhook/",
"allowed_updates": ["message"],
"secret_token": "my-secret-abc123"
}'
```
A successful response:
```json theme={null}
{ "ok": true, "result": true, "description": "Webhook was set" }
```
A Telegram bot can only have one active webhook at a time. Registering a new URL replaces any previous one.
### Deregister Webhook
Removes the webhook and stops Telegram from delivering messages to your workflow.
**Key inputs:**
| Input | Description |
| -------------------- | ------------------------------------------------------------------------- |
| Drop Pending Updates | Set to `true` to discard any messages queued while the webhook was active |
Deregister the webhook when you retire or archive a workflow. If you leave the webhook registered but the workflow inactive, Telegram will keep sending requests that go unanswered.
## Troubleshooting
| Symptom | Likely Cause | Fix |
| ------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------- |
| Workflow does not fire on new messages | Webhook not registered or pointing to wrong URL | Run **Register Webhook** with the correct trigger URL |
| `401 Unauthorized` | Bot token is invalid or revoked | Verify the token or generate a new one via @BotFather |
| Media not delivered | URL is not publicly accessible | Use a public HTTPS URL — local or private URLs will not work |
| Cannot delete a message | Message is older than 48 hours, or bot is not an admin | Bots can only delete recent messages unless they have admin privileges |
| `creates_join_request: true` on invite link | Chat requires admin approval for new members | This is expected behavior — users must be approved before joining |
| Old messages triggering the workflow | Pending updates not cleared during webhook registration | Re-register with `Drop Pending Updates` set to `true` |