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, describe what your app should do, provide the relevant API or MCP connection and connect Telegram from the bot’s channel settings. 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 owner API can queue a fixed message or ask the agent to write one. This example addresses a customer who has already started your connected Telegram bot. Replace the bot ID and chat ID with your own values, and create a scoped key in Settings → API.
curl -X POST 'https://flow.engineer/api/v1/bots/42/messages' \
-H "Authorization: Bearer $FLOW_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-1042-shipped' \
-d '{
"to": "telegram:123456789",
"text": "Your order 1042 has shipped."
}'The response is 202 Accepted when the update is queued. Read GET /api/v1/bots/42/messages/{id} using the returned ID to follow its status. Keep the idempotency key stable when retrying the same shipping event.
Use text for exact copy, such as a confirmed shipping notice. Use prompt when the agent should compose a message using its instructions and tools. Choose that second 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?
Flow handles its connected channel’s messaging path. Connect your Telegram bot and focus on the app operations and behavior you want the agent to provide. 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 owner API also requires an existing customer on the connected channel.
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. Tell Flow about your app.
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.
