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
- In the left navigation menu, click Connectors.
- On the Available tab, locate Telegram and click Add.
- Enter a descriptive connector name.
- Click Confirm. The Telegram authorization flow opens in a dialog.
- In Bot Token, enter the token for the Telegram bot that you want to connect.
- If you need to create a bot, message
@BotFatherin Telegram and send/newbot. For an existing bot, send/tokento retrieve its token. - Click Connect Account.
- Wait for the success message and return to EMQX Agents.
- On the Added tab, verify that the connector status is Authorized.
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. |
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
- In the chat input area, click the connector icon.
- Select the authorized Telegram connector.
- In the prompt, identify the external resource and operation that the agent should use.
- 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.
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. |