The key idea
Telegram handles the conversation interface. Your agent interprets the request, and your app’s tools provide the real data and actions behind the reply.
A Telegram bot gives your app an address people can message. An AI agent adds a conversational way to use the app: find information, clarify a request and complete an operation without making the customer navigate a set of screens.
Telegram is a good place to start when your customers already use it. The setup is explicit, the bot has its own identity and the platform provides a documented Bot API. The hard part is designing a workflow that stays useful after the first “hello.”
What is a Telegram AI agent?
A Telegram AI agent combines a bot connection, conversation state, a model and tools. The model can interpret varied requests; tools let it read or change information in your application.
A customer might ask a shop, “Do you have the blue one in medium?” A useful agent resolves the product, checks live stock and gives a grounded answer. If your backend supports ordering, it can collect the missing details and create an order after confirmation.
The distinction is the connection to real operations. A bot that only generates text can sound helpful while lacking the information needed to finish the task. Start with a small set of tools that make the most common requests possible.
Create and connect your bot
Create the bot through BotFather, Telegram’s bot-management interface. Choose a name and username, then obtain the token used to authorize Bot API requests. Telegram explains bot creation and token management in its bot features documentation.
Treat that token like a password. Keep it in the channel configuration or a server-side secret store. Never embed it in a website bundle, commit it to a repository or paste it into a customer conversation.
With Flow’s Messaging API, try your agent on Flow’s sandbox bot first, with a test key and no account (curl -X POST https://api.flow.engineer/v0/sandbox/keys). When it works, connect your own bot from your server with a live key: POST /v0/senders with channel telegram and the token. Flow checks the token, keeps it encrypted and points the bot’s webhook at Flow; the token is never returned. Keep ownership of the Telegram bot and its token clear within your team.
Give the bot a specific introduction. “I can check your order and help change its delivery details” tells the customer what to try. A vague “Ask me anything” creates expectations your application may not be able to fulfill.
Receive messages reliably
If you are building the channel integration yourself, Telegram offers two update mechanisms: getUpdates for polling or setWebhook for HTTPS delivery. They are mutually exclusive for a bot. Webhook requests contain update objects, and unsuccessful delivery can be retried. The Bot API reference defines the behavior and the update_id used to identify an update.
For a webhook, configure a secret token and check the X-Telegram-Bot-Api-Secret-Token header on incoming requests. Store accepted events durably before returning success, then process them from your queue. Deduplicate by update ID so a repeated event does not create another order.
Keep messages in order within a conversation. Two quick messages such as “Book Friday” and “Actually, Saturday” should not race to create different bookings. For a shared agent architecture, see the unified messaging API guide.
Telegram’s Bots FAQ also explains that bots cannot start an ordinary private conversation with a user who has never contacted them. Have the customer open the bot and press Start before expecting proactive messages.
Connect the agent to your app
Build tools around the customer’s job. For order support, that might be:
| Tool | What it should do | Useful boundary |
|---|---|---|
| Find order | Return the customer’s relevant order | Verify which orders they may access |
| Check delivery | Read the latest fulfillment state | Return the real state, including uncertainty |
| Change address | Update an eligible order | Require confirmation and reject shipped orders |
| Contact support | Give a defined escalation route | Preserve the customer’s context where supported |
Here is an illustrative conversation, assuming the connected app supports address changes:
Customer: I entered the wrong apartment number on my order.
Agent: I found order 1042, and it has not shipped. What apartment number should I use?
Customer: 4B.
Agent: Shall I update the apartment number on order 1042 to 4B?
Customer: Yes.
Agent: Updated. The delivery address now includes apartment 4B.
The agent should report the update only after the app confirms it. If the order has shipped, the tool should return that constraint and the agent should offer the next allowed action. Do not ask the model to invent an exception to your fulfillment rules.
Remember useful conversation context, such as the order being discussed, while keeping authorization in the backend. A Telegram username can change; an authenticated application account should determine which records a customer can access.
Send a message from your backend
Flow’s Messaging API sends an update to a customer who has already started your bot. Into an existing conversation, use its kind’s endpoint; a text goes to /basic:
curl -X POST "https://api.flow.engineer/v0/conversations/$CONVERSATION_ID/basic" \
-H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-1042-shipped' \
-d '{"text": "Your order 1042 has shipped."}'To write to someone who started the bot but has no conversation with this sender yet, POST /v0/messages takes your sender, to ({"telegram_user_id": "123456789"}) and a basic message. Replace the sample IDs with your own.
The response is 202 Accepted when the update is queued. Its outcome arrives as a message.sent or message.failed event, and GET /v0/messages/{message_id} reads its status. Keep the idempotency key stable when retrying the same shipping event.
Text is sent exactly as written. To style it, use Telegram’s own HTML or MarkdownV2 in telegram.parse_mode. When the agent should write the update itself, have your agent compose the text with its instructions and tools, then send it the same way; choose that path deliberately, because its tools may perform real actions.
Make it useful in real conversations
Start in private chats with one well-defined task. Add a clear /start introduction and a support route. Keep replies short enough to read comfortably on a phone, and ask one useful clarification at a time.
If you add groups later, review Telegram’s privacy mode and the messages the bot will receive. The group experience also needs a clear rule for when the agent should respond. A tool that is appropriate in a private, authenticated conversation may need a different boundary in a shared chat.
Measure whether customers complete the task. Track failed tool calls, repeated clarification and replies that arrive without a recorded business result. Expand the bot when the first workflow works consistently, then reuse the tools on WhatsApp or explore an iMessage integration.
Frequently asked questions
Do I need to build a webhook server to use Flow?
No. Flow’s Messaging API receives Telegram’s updates and hands them to your app in order per conversation: as signed webhooks, on a live stream that needs no public URL, or from an event log. The webhook guidance above is for developers building that connection themselves.
Can the bot contact users who have never started it?
For ordinary private bot conversations, customers must initiate contact first. Flow’s Messaging API follows the same rule: it starts a conversation only with someone who has started your bot.
Can I use an existing API or MCP server?
Yes. Expose the operations the agent should perform, describe their purpose and keep permission checks in your application. With Flow Framework, you write them once as typed tools (npx @flow-engineer/flow new my-agent), and the same project answers on Telegram, serves MCP and runs as a CLI. Sign up for the free trial.
Can I keep the same business logic on several channels?
Keep the tools independent of the channel. Adapt identity, incoming messages and reply formatting at the messaging boundary, as described in the unified API guide.
