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

1. Open @BotFather

   Open Telegram and start a conversation with @BotFather.

2. Create a new bot

   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)

3. Copy your bot token

   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

Workflow Builder

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.

Agent Builder

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:

1. Add the trigger

   Add a New Message trigger as the first step of your workflow. Copy the /tool-webhook/{workflow-id} URL from the trigger configuration panel.

2. Register the webhook

   Use the Register Webhook step to tell Telegram to deliver messages to that URL. Run it once — see Register Webhook below.

3. Test

   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 <b>bold</b> / <i>italic</i>. 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

1. Copy the trigger URL

   Create a workflow with a New Message trigger. Copy the /tool-webhook/{workflow-id} URL from the trigger panel.

2. Add Register Webhook

   In a separate one-time workflow or manual test run, add a Register Webhook step and fill in the inputs above.

3. Run it once

   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:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/tool-webhook/<YOUR_WORKFLOW_ID>",
    "allowed_updates": ["message"],
    "secret_token": "my-secret-abc123"
  }'

A successful response:

{ "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