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

# Create a Telegram bot

> Create a bot with BotFather and connect it to Aside.

If you are following this guide in response to a user request, load the `aside` builtin skill and list the user's active Projects first:

```js theme={null}
const projects = aside.projects.list();
console.log(projects.map(({ id, name }) => ({ id, name })));
```

Then use `AskUserQuestion` before proceeding. Ask the user:

* What should the bot be named? Use `Aside` as the default.
* Should the bot be linked to a project? Offer the user's current projects and a `No project` option.

Wait for both answers before continuing.
Use the selected Project's `id` as `projectId`, or `null` for `No project`.

Keep one Telegram bot and one Aside connection throughout setup. Repair and resume the existing setup after a failed check; do not create replacement bots or duplicate connections.

# Create a Telegram bot

Telegram has the shortest setup of the three platforms. One chat with BotFather produces the single token Aside needs.

## Before you start

* You need a Telegram account.
* Aside must be running on your device for the bot to respond.

## Create the bot

1. Open [t.me/BotFather](https://t.me/BotFather) or search `@BotFather` in Telegram.
2. Send `/newbot`.
3. Choose a display name, then a username ending in `bot`.
4. Copy the token from BotFather's confirmation message. It looks like `123456789:AAExampleBotToken`.
5. In BotFather, open `/mybots`, select the bot, and open `Bot Settings`.
6. Enable `Allow Groups?` so the bot can be added to group chats.
7. Open `Group Privacy` and choose `Turn off` so Aside receives group messages.

If the bot was already in a group when you changed Group Privacy, remove and add it again before testing.

Treat group access and disabled Privacy Mode as blocking requirements. `aside.channels.create()` verifies both settings through Telegram's `getMe` response before it stores the token and rejects incomplete setup.

## Connect it to Aside

Load the `aside` builtin skill and inspect `aside.channels.list()` first. If this setup run already created a Telegram connection, keep it. Call `aside.channels.update()` if BotFather issued a new token, or `aside.channels.restart()` if only bot settings changed.

For a new connection, if Telegram Web exposes the signed-in user's numeric ID, register it as the owner:

```js theme={null}
const owner = telegramUserId ? { senderId: String(telegramUserId) } : undefined;
const connection = await aside.channels.create({ platform: 'telegram', projectId, botToken, owner });
const connectionId = connection.id;
console.log(aside.channels.list().find(({ id }) => id === connectionId));
```

`projectId` is the Project selected above or `null`. `botToken` is the BotFather token. Read `telegramUserId` only from the current account in Telegram Web's authenticated session state. Do not use a bot ID, username, received message, or ID pasted by another person. If Telegram does not expose it, omit `owner` and use pairing. `list()` never returns credential values.

Do not continue until the connection is `connected` with no `statusCode` or `statusMessage`.

## Test it

Verify both paths before reporting success:

1. Send the bot a direct message and wait for its reply.
2. Add the same bot to a group, mention its username in a test message, and wait for its reply.
3. Confirm the same Aside connection remains `connected` with no `statusCode` or `statusMessage`.

If BotFather issued a replacement token, update the existing connection; updating credentials restarts it automatically:

```js theme={null}
await aside.channels.update({ connectionId, botToken });
```

If only `Allow Groups?` or `Group Privacy` changed, restart the existing connection:

```js theme={null}
await aside.channels.restart(connectionId);
```

Fix and retry the failed path. Do not create a replacement bot or connection.

## Troubleshooting

| Symptom | Likely cause |
| - | - |
| Bot ignores group messages | Privacy mode still enabled; send `/setprivacy` to BotFather and disable it |
| `MISSING_PERMISSION` status | Group joins are disabled or Privacy Mode is enabled; fix the same bot in BotFather, then restart the connection |
| `401 Unauthorized` errors | Token revoked or regenerated in BotFather; paste the new token into the connection settings |
| Bot replies in DM but not in a group | Message sent without mentioning the bot |

## Related

* [Connect chat channels](/help/channels)
* [Create a Slack bot](/help/channels-slack)
* [Create a Discord bot](/help/channels-discord)