mcps — it lends an agent no tools, and adding it there is refused. The
binding lives entirely in the trigger. See
triggers for the model; this page is the walkthrough.
Telegram is the only messaging channel Talqing has. There is no WhatsApp, no
Slack, no SMS, and no second trigger type. If you need another channel today, it
is not here.
Set it up
1
Create a bot with BotFather
In Telegram, message @BotFather and send
/newbot. Give it a display name and a username. BotFather answers with a
token shaped 123456789:AAH…. That token is the bot — treat it like a
password.You do not paste a webhook URL into BotFather. Talqing registers the
webhook for you when you enable the trigger.2
Create the integration
It takes two fields: the bot token, and a webhook secret of your own choosing.The secret is any string of 1–256 characters made of letters, digits,
underscores and hyphens. Telegram sends it back in the
The create call reaches Telegram’s
X-Telegram-Bot-Api-Secret-Token header on every delivery, and Talqing
refuses a delivery that does not carry it — it is what stops anyone who
guesses the callback URL from feeding your agent messages.Both values are stored as workspace secrets
(TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET) and reads return the
reference, never the value.getMe before the row is written, so a
token Telegram will not accept fails here rather than producing a connection
that looks fine and cannot work. The bot’s id and username are stored from
that answer — the bot id is what conversation keys are built from, which is
why it comes from Telegram rather than from parsing the token.One bot is one integration: a second connection for the same bot is refused
with a Telegram integration with that bot already exists.3
Publish the agent
The trigger only accepts an agent that exists, is published, and whose
published version is on the
text channel. A draft is not enough — live
traffic runs the published version, and there is nothing else for a trigger
to point at.4
Create the trigger
setWebhook with a callback URL it owns and allowed_updates: ["message"],
then writes that URL onto the trigger’s provider_subscription_ref and sets
status: "active".5
Message the bot
Open a private chat with the bot in Telegram and send it something. You should
see a typing indicator, then the reply.On the Integrations page the connection’s webhook badge moves from
waiting for message to receiving once the first delivery lands. The thread
itself appears under Conversations.
When enabling fails
The webhook registration is part of enabling, so a failure is visible immediately rather than as a bot that silently never answers.
Both of the last two leave the trigger row in place at
status: "error". Fix the
cause and PATCH it enabled again — the registration is retried each time.
Disabling or deleting a trigger calls deleteWebhook on a best-effort basis, so
Telegram stops delivering. Deleting the whole integration does the same.
reply_mode
What happens with the agent’s answer.
The value is accepted by the API in all three cases — the refusal happens at
delivery, not at save — so setting
internal_note produces an agent that appears
to work and says nothing.
What Telegram actually delivers
Private chats only. A message from a group, supergroup or channel is discarded. The bot works in a one-to-one chat with a person and nowhere else. Text messages only. A photo, sticker, voice note, document or location in a private chat is ignored — the agent is not told it arrived and does not answer it. So an agent that can read images on the web cannot read one sent to it here. The bot’s own messages are ignored, and a delivery whose secret header does not match is refused with403.
How a Telegram person becomes a conversation
The first message from a chat creates a contact and a conversation for it, automatically. You do not open one.
Because a text agent always carries the whole transcript, one chat is one thread
for its whole life: the person comes back a week later and the agent has
everything they said. The thread is on the Conversations page with a live
timeline, and readable over the API exactly like any other —
GET /v1/conversations?contact_key=telegram:123456789:987654321. See
conversations.
{{vars.*}} cannot be supplied on a Telegram thread: nothing opens the
conversation with a request body, so every agent runs on its declared defaults.
Anything that varies per person belongs in userdata.
While the agent works
A typing indicator is shown in the chat for the whole turn, cold start included, and refreshed every four seconds — Telegram expires the hint after five. It stops when the reply lands. A reply longer than 4096 characters is split into several messages. Telegram’s own cap. The split falls on the last newline or space inside the limit, so the parts read as whole sentences rather than mid-word fragments, and an unbroken run of characters is cut hard at the limit. The conversation timeline still holds one item for the message the model produced; the split is transport only. If a later part fails after earlier ones are already in the chat, the item is markedfailed rather than retried — retrying would show the person the delivered
parts twice.
Running the same agent elsewhere
Nothing about the agent is Telegram-specific. The same published text agent can serve a Telegram trigger and your own app’s text conversations at the same time; each person is a separate thread, keyed by their owncontact_key.
Republishing the agent reaches Telegram on the next message. A warm window closes
with session_replaced and the next turn cold starts on the new version.
Next
Triggers
The trigger model, statuses, and every rule enabling one checks.
Text conversations
Items, the event stream and the window lifecycle behind every text thread.
Conversations
Reading a Telegram thread back, and the sessions inside it.