Telegram Bot Integration

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

Purpose

This workflow helps you:

• Create a Telegram bot via @BotFather.
• Obtain your chat or channel ID.
• Register the bot token and chat ID as a relay target.
• Attach the target to an endpoint output.
• Validate with a test delivery.

Prerequisites and permissions

• A Telegram account.
• Admin access to the target Telegram chat or channel (for channels).
• 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>"
}

The payload JSON is HTML-escaped and embedded in a <pre> block for monospace rendering. Total message length is capped at ~3500 characters (Telegram max is 4096) to leave headroom for the header.

Step-by-step workflow

1. Create a bot via @BotFather

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to choose a name and username.
3. BotFather will reply with your bot token in the format 123456789:ABCdefGhIJKlmnopQRSTuvWXYZ.
4. Copy and save this token securely.

2. Get the chat ID

For a private chat or group:

1. Add your new bot to the chat or group.
2. Send any message in the chat.
3. Open https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in a browser.
4. Look for "chat": {"id": -1001234567890, ...} in the response.
5. Copy the id value (including the minus sign for groups/channels).

Alternative — @userinfobot:

1. Forward a message from the target chat/channel to @userinfobot.
2. The bot will reply 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. Choose Telegram as the type.
4. Enter your Bot Token in the Bot Token field.
   • Stored encrypted and never shown again after saving.
5. Enter the Chat ID (e.g., -1001234567890).
6. Optionally add a name and description, then save.

No email confirmation is required — the target is ready immediately.

4. Attach the target to an endpoint

1. Open the endpoint create/edit page.
2. In Target destinations, select your Telegram target.
3. Save the endpoint.

5. Validate delivery

1. On the Relay targets page, find your Telegram target and select Send test.
2. PayloadRelay queues a test delivery and records the result in activity. If Telegram accepts the request, a test message appears in the configured chat; if Telegram rejects it, check the delivery details for the Bot API error.

Security

• The bot token is stored securely and is not shown again after saving.
• Treat the chat ID as non-secret routing information.
• To rotate the bot token, edit the target and enter the new token.

Retry behavior

Failed endpoint deliveries use PayloadRelay's standard automatic retry schedule capped by your plan. Telegram retries are not separately configurable like webhook-output retry policies. Telegram may rate-limit sustained bursts; if that happens, reduce delivery frequency or let retries recover temporary failures.

Troubleshooting