# Connect EMQX Agents to Telegram

The Telegram connector lets EMQX Agents use a Telegram bot to send and manage messages, files, locations, polls, chats, members, invite links, and bot commands. Use it for alerting, bot-based workflows, and operational notifications.

## Common Use Cases

- Send a device alert to a Telegram group or channel.
- Send an image, file, or location generated by a workflow.
- Read recent bot updates or chat history.
- Create a poll or configure bot commands for an operations workflow.

Example chat prompt:

```text
Use the operations-telegram connector to send a critical device alert to the configured operations chat. Include the device ID, timestamp, and recommended action.
```

## Prerequisites

Before adding the connector, prepare:

- A Telegram bot and its bot token.
- The bot must have access to the target chat, group, or channel.
- Administrator permissions for operations such as creating invite links or managing messages when required.

## Add a Telegram Connector

1. In the left navigation menu, click **Connectors**.
2. On the **Available** tab, locate **Telegram** and click **Add**.
3. Enter a descriptive connector name.
4. Click **Confirm**. The Telegram authorization flow opens in a dialog.
5. In **Bot Token**, enter the token for the Telegram bot that you want to connect.
6. If you need to create a bot, message `@BotFather` in Telegram and send `/newbot`. For an existing bot, send `/token` to retrieve its token.
7. Click **Connect Account**.
8. Wait for the success message and return to EMQX Agents.
9. On the **Added** tab, verify that the connector status is **Authorized**.

<!-- TODO: Confirm bot token rotation behavior and whether write operations require per-action approval. -->

## Supported Tools

### Send Messages

| Tool | Access | Description |
|---|---|---|
| `TELEGRAM_ANSWER_CALLBACK_QUERY` | Write | Responds to an inline keyboard callback query. |
| `TELEGRAM_SEND_DOCUMENT` | Write | Sends a file to a chat. |
| `TELEGRAM_SEND_LOCATION` | Write | Sends a location to a chat. |
| `TELEGRAM_SEND_MESSAGE` | Write | Sends a text message to a chat. |
| `TELEGRAM_SEND_PHOTO` | Write | Sends an image to a chat. |
| `TELEGRAM_SEND_POLL` | Write | Sends a poll to a chat. |

### Manage Messages

| Tool | Access | Description |
|---|---|---|
| `TELEGRAM_DELETE_MESSAGE` | Destructive | Deletes a message. |
| `TELEGRAM_EDIT_MESSAGE` | Write | Edits a message. |
| `TELEGRAM_FORWARD_MESSAGE` | Write | Forwards a message to another chat. |

### Bot and Chat Information

| Tool | Access | Description |
|---|---|---|
| `TELEGRAM_GET_CHAT` | Read | Gets chat information. |
| `TELEGRAM_GET_CHAT_ADMINISTRATORS` | Read | Lists chat administrators. |
| `TELEGRAM_GET_CHAT_HISTORY` | Read | Gets chat history. |
| `TELEGRAM_GET_CHAT_MEMBER` | Read | Gets information about a chat member. |
| `TELEGRAM_GET_CHAT_MEMBERS_COUNT` | Read | Gets the number of chat members. |
| `TELEGRAM_GET_ME` | Read | Gets information about the authorized bot. |
| `TELEGRAM_GET_UPDATES` | Read | Gets recent updates sent to the bot. |

### Chat and Bot Configuration

| Tool | Access | Description |
|---|---|---|
| `TELEGRAM_CREATE_CHAT_INVITE_LINK` | Write | Creates an invite link for a chat. |
| `TELEGRAM_SET_MY_COMMANDS` | Write | Sets the bot command list. |

::: warning Important Notice
Message send, edit, delete, forward, invite link, and bot command tools change Telegram chats or communicate with users. Confirm the chat ID and content before write operations.
:::

## Use the Connector in a Chat

1. In the chat input area, click the connector icon.
2. Select the authorized **Telegram** connector.
3. In the prompt, identify the external resource and operation that the agent should use.
4. Review the generated agent definition and confirm that it contains only the required tools.

## Permissions and Data Access

The connector acts through the Telegram bot identified by the supplied bot token. Bot membership, chat administrator privileges, Telegram privacy settings, and chat type determine accessible messages and actions.

Do not include external service credentials or access tokens in the chat prompt or agent instructions.

## Limitations

- Telegram Bot API rate limits and file limits apply.
- Bots can access only chats where they are present and only updates permitted by Telegram bot privacy settings.
- Some message management and invite link operations require administrator privileges.

<!-- TODO: Confirm service-specific result size limits, file limits, API rate limits, plan restrictions, and unsupported resource types. -->

## Troubleshooting

| Symptom | Resolution |
|---|---|
| The connector remains **Unauthorized**. | Retry authorization and verify that the **Bot Token** is for the intended Telegram bot. |
| A tool returns a permission error. | Verify the authorized account's access to the target resource and operation. |
| A required tool is unavailable. | Verify that the tool is supported and approved for this connector, then select the connector again in the chat. |
| Requests are rejected intermittently. | Check the external service status, API quota, rate limits, and account plan. |

## Related Links

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)