Telegram Bot Integration

Use this guide to send PayloadRelay webhook payloads to a Telegram chat, group, or channel.

Purpose#

Use this guide to:

• Create a Telegram bot with @BotFather.
• Get the chat ID or the channel ID.
• Save the bot token and the chat ID as a relay target.
• Attach the target to an endpoint destination.
• Send a test delivery.

Before you start#

• A Telegram account.
• Admin access to the Telegram chat or channel. A channel needs this access.
• Access to Relay targets and Endpoints in PayloadRelay.

Payload format#

PayloadRelay sends a sendMessage request to the Telegram Bot API:

{
  "chat_id": "<your-chat-id>",
  "parse_mode": "HTML",
  "text": "<b>EndpointName</b>\n<pre>{ ...original payload... }</pre>"
}

PayloadRelay escapes the JSON for HTML and puts it in a <pre> block. The message can contain a maximum of 4096 characters. PayloadRelay keeps space for the endpoint name, and it cuts the payload text when this is necessary. A template message also keeps space for an optional Activity link.

Procedure#

1. Create a bot with @BotFather#

1. Open Telegram and search for @BotFather.
2. Send /newbot. Enter a name and a username when @BotFather asks for them.
3. BotFather replies with your bot token in the format 123456789:ABCdefGhIJKlmnopQRSTuvWXYZ.
4. Copy this token and keep it in a safe location.

2. Get the chat ID#

For a private chat or a group:

1. Add your new bot to the chat or the group.
2. Send a message in the chat.
3. Open https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in a browser.
4. Find "chat": {"id": -1001234567890, ...} in the response.
5. Copy the id value. A group ID and a channel ID contain a minus sign.

Alternative: @userinfobot

1. Forward a message from the chat or the channel to @userinfobot.
2. The bot replies with the chat ID.

For a public channel:

1. Add your bot as an admin of the channel.
2. Use the getUpdates method above, or use @userinfobot.

3. Add a Telegram relay target#

1. Open Relay targets in PayloadRelay.
2. Select Add target.
3. Select Telegram as the type.
4. Enter the bot token in the Bot Token field.
   • PayloadRelay stores the token encrypted, and it does not show the token after you save.
5. Enter the Chat ID, for example, -1001234567890.
6. Add a name and a description. These values are optional. Then save.

The target needs no email confirmation. It is available immediately.

4. Attach the target to an endpoint#

1. Open the endpoint create page or the endpoint edit page.
2. In Outputs, select the Telegram target.
3. Save the endpoint.

5. Test delivery#

1. On the Relay targets page, find the Telegram target and select Send test.
2. PayloadRelay starts a test delivery and records the result in Activity. If Telegram accepts the request, a test message appears in the chat. If Telegram rejects the request, read the delivery details for the Bot API error.

Security#

• PayloadRelay stores the bot token in a safe location, and it does not show the token after you save.
• The chat ID is routing information. It is not a secret.
• To change the bot token, edit the target and enter the new token.

Retry behavior#

A failed endpoint delivery uses the standard automatic retry schedule of PayloadRelay, in the limit of the plan. A Telegram retry has no separate configuration. Telegram can rate-limit a continuous burst. Send the deliveries less frequently, or let the retries correct the temporary errors.

Troubleshooting#