Build a Telegram AI agent with the Flow Messaging API

This guide builds an AI agent on Telegram, first on Flow’s sandbox bot and then on your own bot, with the same code.

TypeScript

// npm install @flow-engineer/messaging openai
import OpenAI from "openai";
import { FlowMessaging, contentText } from "@flow-engineer/messaging";

const flow = new FlowMessaging();
const openai = new OpenAI();

for await (const event of flow.events.stream({ types: ["message.received"] })) {
  await event.conversation.reply(
    openai.chat.completions.create({
      model: "gpt-4.1-mini",
      stream: true,
      messages: [{ role: "user", content: contentText(event.data.message.content) }],
    }),
  );
}

1. Try it on the sandbox bot

Get a test key, with no account: curl -X POST https://api.flow.engineer/v1/sandbox/keys (or npx @flow-engineer/messaging init). Set its key as FLOW_MESSAGING_KEY. It allows 1 contact and 50 messages for 7 days; sign in to get more (Keys and sign-in).
GET /v1/senders?channel=telegram lists the sandbox bot. Its address.link is https://t.me/<bot>?start=<code>, with your join code in it. (npx @flow-engineer/messaging init prints it too.)
Open the link and tap Start. That’s it, you’ve joined.
Run the code above and send the bot a message.

If the link can’t be used (for example you found the bot by searching for it), send the bot the sender’s join_code instead, for example join wild-otter-04508705.

2. Your own Telegram bot

Telegram is the fastest channel to go live on: bring a bot token and it is connected at once.

In Telegram, open @BotFather, send /newbot, and copy the token.
Put the token in an environment variable on your server or in your terminal, and connect it with a live key (FLOW_MESSAGING_KEY=fk_live_...):

curl

export TELEGRAM_BOT_TOKEN=...   # the token from BotFather; never commit it

curl https://api.flow.engineer/v1/senders \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"channel\": \"telegram\", \"telegram_bot_token\": \"$TELEGRAM_BOT_TOKEN\"}"

Flow checks the token, keeps it encrypted, points the bot’s webhook at Flow and answers with the sender active. The token is never returned. With FLOW_MESSAGING_KEY set to the live key, your agent now answers on your bot.

The bot token controls your bot. Never paste it into a chat with an AI assistant (including your coding agent), and never commit it. Keep it in an environment variable and send it from your own server or terminal, as above.

To disconnect the bot, call DELETE /v1/senders/{sender_id} with your live key: Flow removes the bot’s webhook, deletes its token and retires the sender (banned). If Telegram rejects the token (you revoked it in @BotFather), the sender turns flagged: new sends answer 403 permission and queued messages are held. Send the new token the same way (POST /v1/senders) and the same sender becomes active again and sends them. A held message waits at most 72 hours after Flow accepted it; after that it fails with outside_window (channel_code queued_too_long) in message.failed instead of going out late.

A bot can have only one webhook. Connecting a bot to Flow replaces any webhook it had, so do not keep another server polling or receiving updates for the same bot.

3. Inline keyboards

buttons content shows as an inline keyboard (1 to 10 buttons). Taps arrive as button_reply with the button’s id. URL buttons open a link and send nothing back.

TypeScript

import { buttons } from "@flow-engineer/messaging";

await event.conversation.send(buttons("Pick a size", ["Small", "Medium", "Large"]));

4. Edit and unsend

Telegram lets bots edit their messages and delete them within 48 hours:

TypeScript

const [msg] = await event.conversation.reply("Checking stock...");
await flow.messages.edit(msg.id, "In stock: 12 left.");
await flow.messages.unsend(msg.id);

5. What Telegram supports

Content	Telegram
Text with markdown	yes
Photos, video, audio, voice notes	yes
Documents	received (not malware-scanned yet, so treat them as untrusted); sending uploaded documents is refused with `422 unsupported_content` until scanning is on
Buttons	inline keyboard, up to 10
Reactions, typing	yes
Read receipts	no: bots cannot send them (skipped and reported in `delivered_as`)
Edit, unsend	yes (unsend within 48 hours)
Starting a conversation	only with people who started your bot (`to.telegram_user_id`)

6. Telegram rules worth knowing

People must start your bot first. Telegram does not let a bot message someone who has never pressed Start.
Commands are messages. /start and other commands arrive as text content; your agent decides what to answer.
Contacts have no phone number. A Telegram contact is identified by address.telegram_user_id and maybe address.username.

Get started

Concepts

Channel guides

Agent frameworks

Compare

Build a Telegram AI agent with the Flow Messaging API

1. Try it on the sandbox bot

2. Your own Telegram bot

3. Inline keyboards

4. Edit and unsend

5. What Telegram supports

6. Telegram rules worth knowing

​1. Try it on the sandbox bot

​2. Your own Telegram bot

​3. Inline keyboards

​4. Edit and unsend

​5. What Telegram supports

​6. Telegram rules worth knowing

​Related

1. Try it on the sandbox bot

2. Your own Telegram bot

3. Inline keyboards

4. Edit and unsend

5. What Telegram supports

6. Telegram rules worth knowing

Related