← Back to documentation

Telegram Bot Integration

Create a Telegram bot, save its credentials as a target, and test delivery.

4 min read

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:

Code Example
{
  "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 Create relay 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 relay target form with Telegram selected, the bot token, and the chat ID

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 Destinations, 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 delivery.
  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, up to the retry 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.

A Telegram target cannot be the failover of a webhook destination. The API rejects this configuration with Telegram targets are not supported for failover.

Troubleshooting#

SymptomLikely causeFix
400 Bad Request: chat not foundA wrong chat IDRead the chat ID again. You can use getUpdates.
403 Forbidden: bot was kickedThe bot is not a member of the chatAdd the bot to the chat again.
403 Forbidden: bot is not adminThe bot has no send permission in the channelMake the bot an admin with the Post Messages permission.
No delivery and no errorThe bot token is revokedCreate a new token with @BotFather, and update the target.
The test button fails with 400The bot token is missingEdit the target and enter the bot token.