Skip to main content

​
Telegram Setup Guide

Connect your Machine agents to Telegram and chat with them from anywhere — in about 5 minutes.

​
How It Works

Machine’s Telegram Integration lets you connect any of your Machine agents to a Telegram bot. Once connected, anyone who messages your bot on Telegram will receive responses powered by your agent — complete with the model and instructions you’ve configured.
1

User sends message

User sends a message to your Telegram bot
2

Telegram webhooks to Machine

Telegram forwards the message to Machine via webhook
3

Routed to your Agent

Machine routes the message to your selected agent
4

Agent generates response

Your agent processes the message using its configured model and instructions
5

Reply sent on Telegram

The response is sent back to the user on Telegram

​
Prerequisites

Telegram Account

A personal Telegram account (free)

Machine Account

An active Machine account with at least one agent

An Agent

At least one agent configured (powers your bot’s responses)

​
Part 1 — Create a Bot on Telegram

~2 min BotFather is Telegram’s official tool for creating and managing bots. Open Telegram and search for @BotFather (look for the blue verified checkmark ✓).
1

Start a chat with BotFather

Tap Start or type /start. BotFather will reply with a list of available commands.
2

Create a new bot

Send the command /newbot.
3

Name your bot

BotFather asks: “How are we going to call it?” — type any display name you like, e.g. MyAssistantBot.
4

Choose a username

The username must end in bot or Bot. If it’s taken, BotFather will ask you to try another.
5

Copy your API token

BotFather responds with “Done! Congratulations on your new bot.” and provides:
  • A link to talk to your bot — e.g. t.me/MyAssistantBot
  • An API token — looks like 123456789:ABCdefGHIjklMNO...
Keep your token secret! Anyone with this token can control your bot. If it ever gets leaked, revoke it with /revoke in BotFather.

​
Part 2 — Connect the Bot in Machine

~1 min Now bring that bot token into Machine to link it with one of your agents.
1

Navigate to the Telegram page

In the Machine dashboard sidebar, click Telegram — or go directly to /telegram.
2

Click 'Add Bot'

A configuration dialog will open with three fields.
3

Paste your Bot Token

In the Bot Token field, paste the API token from BotFather. Format: 123456789:ABCdefGHIjklMNO...
4

Select an Agent

Choose which Machine agent should handle incoming messages. This agent’s instructions, personality, and tools will power your bot’s responses.
5

Select a Model (optional)

Optionally pick a specific AI model. If you leave this blank the bot uses the agent’s default model.
6

Click 'Save Configuration'

Machine validates your token, sets up the webhook automatically, and shows a success notification. Your bot appears in the Connected Bots table with a green Active badge.

​
Part 3 — Talk to Your Bot

Your bot is now live! Open Telegram, search for your bot’s username (e.g. @MyAssistantBot), and tap Start. 
@MyAssistantBot
online
/start
👋 Hello! I'm your Machine-powered assistant. Here's what I can help with…

Hey, you're my Telegram bot
That's right! I'm connected to your Machine agent. How can I help you today?

What can you do?
I can help with a variety of tasks — just ask me anything and I'll use all the tools and knowledge my agent has access to!
The bot maintains conversation context within each chat thread, so you can have natural back-and-forth conversations just like chatting with a person.

​
Managing Your Bots

All your connected bots appear on the Telegram dashboard.
Click the pencil icon next to a bot, pick a new model, and save. The change takes effect immediately for new messages.
Click the trash icon and confirm. The bot stops responding, but you can reconnect it any time with the same token.
Machine supports multiple bots per account. Each can have its own agent and model — just click “Add Bot” again.

​
Tips & Best Practices

​
Agent Configuration

Customize Instructions

Customize your agent’s instructions for Telegram’s conversational style. Add instructions like “Keep responses concise and suitable for mobile messaging”

Message Length

Telegram messages tend to be shorter — tune your prompts accordingly

​
Security

Never share your bot token publicly — treat it like a password. If compromised: @BotFather → /revoke. Machine encrypts your bot token at rest.

​
BotFather Commands

Change display name
Set bot description
Upload profile pic
Define slash commands
Toggle privacy mode
Regenerate token

​
Advanced Branding & Groups

​
Branding Your Bot

Use these BotFather commands to give your bot a professional identity:

/setuserpic

Profile Picture - Upload a 512x512 square logo

/setdescription

Description - Shown before users start the bot

/setabouttext

About Text - Shown on the bot’s profile page

/setcommands

Menu List - Define your bot’s slash command menu

​
Group Chat Intelligence

When you add your bot to a group, Machine provides it with context about who is speaking.
By default, bots only see messages that @mention them. To see all messages, use /setprivacy → Disable. Note: Changing privacy requires removing and re-adding the bot to the group.
Disabling privacy increases credit usage as the bot processes all messages in the group.

​
Troubleshooting

The webhook may not have been set correctly. Try disconnecting and re-adding the bot.
Make sure you copied the full token from BotFather. It should look like 123456789:ABCdefGHIjklMNO…
Ensure an agent is selected in the Machine dashboard. If you revoked the token in BotFather, you’ll need a new one.
Response time depends on the chosen model and agent complexity. Some models are faster than others.
Privacy Mode is on by default — use /setprivacy in BotFather to disable it, then remove and re-add the bot to the group.
If your bot stops responding, another service might have claimed the webhook. Simply click “Save Configuration” again in Machine to re-claim it.

​
Technical Specifications

​
Message Delivery

Character Limit

Strict 4,096 character limit per message. Machine automatically truncates longer responses.

Markdown Stripping

Formatting is intentionally simplified to prevent Telegram parse errors. Bold/Italic are converted to plain text.

​
Vision & Media

Supported if using a vision-capable model. Send photos directly or as uncompressed files.
Currently supports image-based documents. Non-image file processing is coming soon.

​
Frequently Asked Questions

Yes! Machine supports multiple bots per account. Each can have its own agent and model.
Yes, you can use the same agent for multiple Telegram bots.
Yes, the bot maintains conversation context within each chat thread.
Click the pencil icon next to your bot in the Telegram dashboard, select a different agent, and save.
Messages consume credits based on your Machine plan and the model used by your agent.
Currently, bots work best in direct messages and groups. Channel support may vary.
If you delete the bot in BotFather, you’ll need to create a new bot and reconnect it in Machine.

​
Ready to Get Started?

Head to the Telegram dashboard to connect your first bot in minutes.

Go to Telegram Dashboard

Connect your first bot in Machine

Open BotFather

Create your Telegram bot