Send and receive Telegram messages from Guild agents

Integrations · Telegram

A Guild agent can send messages through a Telegram bot, read incoming messages, and start automatically each time someone writes to the bot. Guild stores the bot token encrypted and injects it server-side, so it never appears in agent code. Credential policies let you restrict which operations each agent may call, and every request passes through Guild’s audit trail.

Book a demo

See how teams govern agents that use Telegram.

Start free

Connect Telegram and scope your first agent.

What the Telegram integration exposes

The integration provides tools to verify the bot identity, retrieve incoming messages, and send text replies. The send tool accepts plain text or formatted content using MarkdownV2, HTML, or Markdown, up to 4096 characters per message. A webhook event trigger fires an agent each time someone sends the bot a new message, passing the Telegram update as the agent’s input.

How it works

Create a bot with BotFather

BotFather replies with a bot token; copy it.

Add the credential in Guild

Go to Access & setup > Credentials, click Connect, select telegram, and paste the token into API Key. See Credentials for workspace, member, and agent-scoped options.

Create a trigger for incoming messages

Create a webhook trigger in the Guild UI and select the message event. Guild registers the webhook with Telegram automatically and checks a secret token on each delivery. See Event triggers for input templates and trigger management.

Why Telegram bot access needs governing

A bot token grants full control over the bot. Anyone who holds it can send messages to any chat the bot belongs to. Guild stores the token encrypted and adds it to requests server-side through its credential proxy, so agent code, prompts, and logs never contain it. You can scope a credential to a single workspace, a single member, or a single agent, keeping the token out of shared contexts where it is not needed. See Credentials and Security architecture. Credential policies let you write ALLOW and DENY rules that the proxy enforces before any request leaves Guild. You can restrict an agent to read-only operations, or block sending entirely for agents that only need to poll for updates. Rules can be scoped to specific agents or workspaces on the same credential. Without a policy, a credential starts with an allow-all default; deleting that default flips the posture to deny-by-default. See Credential policies.

About the Telegram integration

The Telegram integration connects a Telegram bot to Guild. Agents can send messages as the bot and read the messages people send it, and a trigger can run an agent each time someone messages the bot. The integration is guildai~telegram.

Authentication

Type: Bot token

Create a bot by messaging @BotFather in Telegram and sending /newbot. BotFather replies with a bot token such as 123456789:AAH.... Anyone with the token controls the bot, so treat it as a secret; BotFather can revoke it. Telegram expects the token in the request URL rather than a header. Guild stores it encrypted and adds it to each request server-side, so agent code never sees it.

Setup

Open Credentials

Go to Access & setup > Credentials in Guild.

Connect Telegram

Click Connect, select telegram, and paste the bot token into API Key.

See Credentials for workspace, member, and agent-scoped credentials.

Tools

Tools in the latest published version of guildai~telegram:

Tool	What it does
`telegram_get_me`	Return the bot’s own account: ID, username, and names. Use it to confirm the token works.
`telegram_get_updates`	Return messages people have sent the bot, so the agent can find the `chat_id` to reply to. Takes optional `offset`, `limit` (1-100), `timeout` (seconds to long-poll), and `allowed_updates`.
`telegram_send_message`	Send a text message to a chat. Takes `chat_id` and `text` (1-4096 characters), plus optional `parse_mode` (`MarkdownV2`, `HTML`, or `Markdown`), `disable_notification`, `link_preview_options`, and `reply_parameters`.

A Telegram bot can’t start a conversation. Someone must message the bot first, or add it to a group, before the bot can send to that chat.

Usage

import { TelegramTools } from "@guildai-services/guildai~telegram"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that answers questions sent to a Telegram bot",
  systemPrompt: `You receive a Telegram update as input.
Answer the message, then reply with telegram_send_message,
using message.chat.id from the update as chat_id.`,
  tools: { ...TelegramTools },
})

Trigger an agent from a message

Event	Description
`message`	Someone sent the bot a new message

Create a trigger in the web UI, or with the CLI:

guild trigger create --type webhook --integration telegram --event message --agent <identifier>

When you enable the first Telegram trigger, Guild registers its webhook with Telegram. Each delivery carries a secret token that Guild checks before running the trigger. Disabling the last trigger, or disconnecting the credential, removes the webhook. The agent receives the Telegram update as its input. Guild doesn’t reply for it; the agent calls telegram_send_message to answer. Each message starts a new session. See Event triggers for agent input templates and trigger management.

Limitations

Telegram allows one webhook per bot. Enabling a trigger replaces any webhook the bot already has, so connect each bot token in one place only.
telegram_get_updates doesn’t work while a Telegram trigger is enabled. Telegram rejects polling while a webhook is registered; read incoming messages from the trigger input instead.
Only new messages trigger agents. Edited messages, channel posts, and button presses don’t.
In groups, Telegram’s privacy mode is on by default, so the bot receives only messages meant for it, such as commands and replies to it. To trigger on every group message, turn privacy mode off with BotFather’s /setprivacy command.

Frequently asked questions

Can the bot start a conversation with someone?

No. A Telegram bot cannot start a conversation. Someone must message the bot first, or add it to a group, before the bot can send to that chat.

Can I poll for updates while a trigger is enabled?

Not yet. The telegram_get_updates tool does not work while a Telegram trigger is active. Telegram rejects polling when a webhook is registered; read incoming messages from the trigger input instead.

Does enabling a trigger affect an existing webhook on the bot?

Yes. Telegram allows one webhook per bot. Enabling a trigger replaces any webhook the bot already has, so each bot token should be connected in one place only.

Which message types start a trigger run?

Only new messages trigger agents. Edited messages, channel posts, and button presses do not fire the trigger.

Put a governed Telegram bot agent in production this week

Book a demo

See how teams govern agents that use Telegram.

Start free

Connect Telegram and scope your first agent.

Also runs on Guild: Discord · Email · Gmail · SendGrid Read: Docs: Credential policies · Credentials · Tools in agents

Overview

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Recruiting

Send and receive Telegram messages from Guild agents

Book a demo

Start free

What the Telegram integration exposes

How it works

Why Telegram bot access needs governing

About the Telegram integration

Authentication

Setup

Tools

Usage

Trigger an agent from a message

Limitations

Frequently asked questions

Put a governed Telegram bot agent in production this week

Book a demo

Start free

Book a demo

Start free

​What the Telegram integration exposes

​How it works

​Why Telegram bot access needs governing

​About the Telegram integration

​Authentication

​Setup

​Tools

​Usage

​Trigger an agent from a message

​Limitations

​Frequently asked questions

​Put a governed Telegram bot agent in production this week

Book a demo

Start free

​Related

What the Telegram integration exposes

How it works

Why Telegram bot access needs governing

About the Telegram integration

Authentication

Setup

Tools

Usage

Trigger an agent from a message

Limitations

Frequently asked questions

Put a governed Telegram bot agent in production this week

Related