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

# Telegram

> Connect a Telegram bot to Synti so you can drive the agent from private chats on any device.

Telegram is the quickest messaging integration to set up: create a bot, paste its token into Synti, and you can talk to the agent from your phone or desktop. This page walks through both halves — creating the bot in Telegram and connecting it in Synti.

## Create a bot

Telegram bots are created by chatting with BotFather, Telegram's official bot for managing bots.

<Steps>
  <Step title="Open BotFather">
    Search for `@BotFather` in Telegram and start a chat.
  </Step>

  <Step title="Create the bot">
    Send `/newbot`, then give it a display name and a username. The username must end in `bot`.
  </Step>

  <Step title="Copy the token">
    BotFather replies with a token. Treat it like a password — anyone who has it can control your bot.
  </Step>

  <Step title="(Optional) group privacy">
    Only if you plan to use groups: run `/setprivacy`, pick your bot, and disable privacy mode. For the recommended one-on-one use, you can skip this.
  </Step>
</Steps>

<Warning>
  Keep the bot token secret. If it leaks, use BotFather's `/revoke` to regenerate it, then update the token in Synti.
</Warning>

## Connect it in Synti

<Steps>
  <Step title="Open messaging settings">
    Go to **Settings → Messaging** and click **Connect** on the Telegram tile.
  </Step>

  <Step title="Paste and test">
    Paste the bot token and click **Test**. Synti validates it against Telegram's `getMe` endpoint.
  </Step>

  <Step title="Save">
    Click **Save**. The token is stored in the workspace keychain and the adapter starts.
  </Step>
</Steps>

<Note>
  An invalid token fails the test with **401 Unauthorized**. Regenerate it with BotFather's `/token` or `/revoke` and try again.
</Note>

## Start a conversation

Once connected, open the bot and bind a session:

1. Open the bot via its `t.me/<username>` link or by searching its username.
2. Send `/new` to create and bind a session.
3. Start typing. Your messages go to the agent, and replies come back in the mode you chose.

A fresh bot won't do anything until you run `/new` or `/pair` — it needs a bound session first.

## Managing sessions

The standard [messaging commands](/messaging/overview#commands) all work here: `/new`, `/bind`, `/unbind`, `/status`, `/stop`, and `/pair <code>`. Flows like `/bind` show a tappable list of sessions using Telegram's inline buttons instead of asking you to type a number; the keyboard clears itself once you pick.

## Attachments

The gateway downloads photos, documents, voice messages, videos, and audio you send, and converts each to the right attachment type for the agent.

<Note>
  Attachments are capped at **20 MB** each.
</Note>

## Access control

By default your bot is private — only people on the workspace allowlist can run pre-binding commands. A few rules shape who gets in:

* **First-pair rule.** Redeeming a pairing code automatically captures the sender's Telegram ID, so you never have to enter it by hand.
* **Pending requests.** An unrecognized sender gets a "Bot is private" reply and shows up under **Settings → Messaging → Pending requests**, where you can approve them with one click.
* **Per-binding overrides.** Each binding can inherit the workspace settings, use its own allowlist, or be open to anyone.

## Direct messages only

Only direct chats with the bot can drive a session. Messages in groups, supergroups, and channels are rejected at the adapter, no matter the privacy setting. Keep the bot in one-on-one chats.

## Desktop vs. headless

<Tabs>
  <Tab title="Desktop app">
    The Electron app uses long-poll mode, so no public URL is needed. This is the default and works from any network.
  </Tab>

  <Tab title="Headless server">
    The [headless server](/server/headless) uses webhook mode. Configure a public URL and Synti verifies inbound calls with the `X-Telegram-Bot-Api-Secret-Token` header.
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The bot doesn't respond to my messages">
    Make sure you've bound a session with `/new` or `/pair`. A fresh bot has nothing to route messages to.
  </Accordion>

  <Accordion title="Test fails with 401 Unauthorized">
    The token is wrong or has been revoked. Get a fresh one from BotFather with `/token` or `/revoke` and re-test.
  </Accordion>

  <Accordion title="The bot works in one workspace but not another">
    Messaging is workspace-scoped. The bot only operates within the workspace where it's configured.
  </Accordion>
</AccordionGroup>