# Telegram bot

How you give an agent its own Telegram bot, and how the agent reads what people write to it and answers. What the bot is and what it costs is on [Services](/services).

## Before you start

- The agent needs an open account. One account has one bot, and one bot serves one account.
- You need to be the owner or an admin.

## Connect the bot

There are two ways. The first makes the bot for you: the command returns a link, you open it in Telegram, and the bot is made and connected. The link works once and lasts 10 minutes.

```bash
npx @getstackrun/cli account telegram-start acct_123
```

The second connects a bot you made yourself with BotFather in Telegram, which gives you the bot's token. The token is a secret, so there is no tool for this step and a chat sign-in cannot do it. Connect from the terminal, where the token is read from a hidden prompt:

```bash
npx @getstackrun/cli account telegram-connect acct_123

# See the bot and its link.
npx @getstackrun/cli account telegram acct_123
```

From code, with an API key: `stack.accounts.telegram.connect('acct_123', botToken)`. STACK checks the token with Telegram and stores it encrypted. The answer carries `start_url`, the link people open to write to the bot.

## Read what people write

A person has to write to the bot first. Telegram does not let a bot start a chat.

```text
What has been written to the assistant's Telegram bot?
```

The client calls `stack_list_account_messages` with `channel: "telegram"`. Each message carries the `chat_id` to answer. From code: `stack.accounts.messages.list('acct_123', { channel: 'telegram' })`.

- To start the agent when someone writes, set a wake rule with the source telegram: see Wake-ups. Without a rule, a message is stored and wakes no one.
- Messages are content from outside. They are scanned, and with controls on a flagged message is withheld.
- The bot works in private chats and in groups.

## Answer a chat

```typescript
await stack.accounts.sendTelegram('acct_123', {
  chat_id: '123456789',
  text: 'Thanks, got it.',
}, { passportToken });
```

```bash
npx @getstackrun/cli account send-telegram acct_123 --chat-id 123456789 --body "Thanks, got it."
```

- The tool is stack_send_account_telegram.
- Only the account's own agent, or you, can send from its bot. An agent you set to read only cannot: see Email.
- A message is plain text, at most 4,096 characters.
- One message is one action. Telegram charges nothing, and receiving is free.

## See chats or disconnect

`stack_list_account_telegram_chats` lists the chats that wrote to the bot. `stack_disconnect_account_telegram` stops receiving and sending. The bot stays yours in Telegram.

## When it is refused

- 403 TELEGRAM_SEND_REFUSED, reason chat_unknown - that chat never wrote to the bot.
- 403 TELEGRAM_SEND_REFUSED, reason chat_blocked - the person blocked the bot. It clears when they write again.
- 403 TELEGRAM_SEND_REFUSED, reason no_bot or bot_unavailable - no bot is connected, or Telegram no longer accepts its token.
- 403 MESSAGES_READ_ONLY - you set this agent to read only. It cannot send.
- 429 RATE_LIMITED - Telegram asked the bot to wait. The answer says how long.
- 409 CONFLICT on connect - the account already has a bot, or the bot is connected to another account.
- 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as telegram.send.

## Reference

Every field is on [Chat Channels](/docs/api/chat-channels). Every tool is in the [tool reference](/docs/mcp-tools).
