> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Send and receive Telegram messages from Guild agents

> Connect a Telegram bot to Guild so agents can send messages, read updates, and run on each new message, with the bot token kept server-side.

<div className="guild-lockup">
  <span className="guild-eyebrow">Integrations · Telegram</span>
</div>

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.

<CardGroup cols={2}>
  <Card title="Book a demo" icon="calendar" href="https://guild-ai.cal.com/gtm/meeting-with-guild.ai">
    See how teams govern agents that use Telegram.
  </Card>

  <Card title="Start free" icon="rocket" href="https://app.guild.ai">
    Connect Telegram and scope your first agent.
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="Create a bot with BotFather">
    BotFather replies with a bot token; copy it.
  </Step>

  <Step title="Add the credential in Guild">
    Go to **Access & setup > Credentials**, click **Connect**, select **telegram**, and paste the token into **API Key**. See [Credentials](/platform/credentials) for workspace, member, and agent-scoped options.
  </Step>

  <Step title="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](/platform/event-triggers) for input templates and trigger management.
  </Step>
</Steps>

## 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](/platform/credentials) and [Security architecture](/platform/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](/platform/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](https://t.me/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

<Steps>
  <Step title="Open Credentials">Go to **Access & setup > Credentials** in Guild.</Step>
  <Step title="Connect Telegram">Click **Connect**, select **telegram**, and paste the bot token into **API Key**.</Step>
</Steps>

See [Credentials](/platform/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`. |

<Note>
  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.
</Note>

## Usage

```typescript theme={null}
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:

```bash theme={null}
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](/platform/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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Which message types start a trigger run?">
    Only new messages trigger agents. Edited messages, channel posts, and button presses do not fire the trigger.
  </Accordion>
</AccordionGroup>

## Put a governed Telegram bot agent in production this week

<CardGroup cols={2}>
  <Card title="Book a demo" icon="calendar" href="https://guild-ai.cal.com/gtm/meeting-with-guild.ai">
    See how teams govern agents that use Telegram.
  </Card>

  <Card title="Start free" icon="rocket" href="https://app.guild.ai">
    Connect Telegram and scope your first agent.
  </Card>
</CardGroup>

## Related

**Also runs on Guild:** [Discord](/integrations/discord) · [Email](/integrations/email) · [Gmail](/integrations/gmail) · [SendGrid](/integrations/sendgrid)

**Read:** Docs: [Credential policies](/platform/credential-policies) · [Credentials](/platform/credentials) · [Tools in agents](/sdk/tools)