---
title: "Telegram"
source: https://sumgenius.ai/docs/webhook-telegram
generated: 2026-08-24
---

# Telegram

Receive messages sent to your Telegram bot as webhook events, and reply through the same Send API you use for Facebook, Instagram, SMS, and WhatsApp. This page covers only the Telegram-specific details: `chat_id` routing, supported actions, and rendering. Everything shared lives on the [authentication](https://sumgenius.ai/docs/api-authentication), [receiving webhooks](https://sumgenius.ai/docs/receiving-webhooks), and [Send API](https://sumgenius.ai/docs/send-api) pages.

Add-on · $29/month · Requires Creator+ plan

### Overview

ChatGenius connects to Telegram through the **Telegram Bot API**. Once a bot is connected and enabled, inbound forwarding and outbound sending work exactly like the other channels; the only differences are the routing identifier (a Telegram `chat_id`) and which actions are supported. The envelope, signing, retries, and API keys are shared: see [the envelope](https://sumgenius.ai/docs/webhook-events#envelope), [verifying signatures](https://sumgenius.ai/docs/receiving-webhooks#verify), and [authentication](https://sumgenius.ai/docs/api-authentication).

Capabilities

- inbound forwarding Messages to your bot are forwarded as `telegram.message_received` events.
- send_messagesupported Free-form text, plain-text rendering, no messaging window.
- typing_onsupported Maps to Telegram's `sendChatAction`.
- react · unreactnot supported Rejected with HTTP 422 and not sent.

> **Note**
>
> **Requirements:** a paid ChatGenius tier that includes Telegram, a connected and enabled Telegram bot (*Settings → Telegram*), and the add-on active. Until a bot is connected, the `telegram.message_received` checkbox on the endpoint page is disabled.

To handle Telegram conversations yourself with no AI reply, turn off the Telegram AI Assistant or use [Global External Reply Mode](https://sumgenius.ai/docs/receiving-webhooks#external-reply-mode); to keep message bodies out of stored delivery logs, see [Inbound Body Purge](https://sumgenius.ai/docs/receiving-webhooks#inbound-body-purge).

**At a glance**

```
// inbound event
event_type: "telegram.message_received"
channel:    "telegram"

// outbound
actions: send_message · typing_on
routing: chat_id (as platform_user_id)
window:  none
```

### Inbound payload

When a customer messages your bot, ChatGenius forwards a `telegram.message_received` event: the standard envelope plus a Telegram sub-block under `message.telegram`. `source.channel` is always `telegram`.

Telegram-specific fields

- customer.platform_user_idstring The Telegram `chat_id`. Pass it as `platform_user_id` (with `platform: "telegram"`) to the Send API to reply. Always present; the stable join key for attribution. `message.telegram.chat_id` repeats the same value.
- customer.platform_user_namestring | null The sender's display name (first + last). Present in `full` payload profile only.
- customer.platform_user_usernamestring | null The sender's Telegram @username (without the `@`) when they have set one; `null` otherwise.
- message.idstring `<chat_id>:<telegram_message_id>`. Telegram message ids are unique only per chat, so the chat is prefixed to keep the id stable for deduplication.
- message.telegram.chat_typeenum `private` · `group` · `supergroup` · `channel`.
- message.telegram.message_typestring `text`, or the media kind for a captioned media message (e.g. `photo`, `document`, `voice`, `video`).

> **Note**
>
> **First-message `conversation.id`.** On the very first message from a new chat, `conversation.id` can be `null`: the event is forwarded a moment before the conversation record is created. Every subsequent message carries the populated id. Use `customer.platform_user_id` (the chat_id) as your stable attribution key. This matches SMS and WhatsApp behavior.

In v1, the customer's text (or a media caption) is forwarded. Media-only messages with no caption carry no text body and are not forwarded. Signature verification, retries, and timestamp validation are identical to every other channel: see [verifying signatures](https://sumgenius.ai/docs/receiving-webhooks#verify).

**telegram.message_received · full profile**

```
{
  "event_id":    "a9b8c7d6e5f40312a1b2c3d4e5f60718",
  "event_type":  "telegram.message_received",
  "occurred_at": "2026-07-24T18:30:00Z",
  "source": {
    "platform": "telegram",
    "channel":  "telegram"
  },
  "conversation": {
    "id": 5310
  },
  "customer": {
    "platform_user_id":       "820032950394075",
    "platform_user_name":     "Jane Doe",
    "platform_user_username": "janedoe"
  },
  "message": {
    "id":          "820032950394075:1487",
    "text_raw":    "Do you ship to Kyiv?",
    "attachments": [],
    "telegram": {
      "chat_id":      "820032950394075",
      "chat_type":    "private",
      "username":     "janedoe",
      "message_type": "text"
    }
  },
  "meta": {
    "version":         "v1",
    "payload_profile": "full",
    "generated_at":   "2026-07-24T18:30:00Z"
  }
}
```

### POST Sending Telegram messages

Route by `conversation_id`, or by `platform: "telegram"` plus `platform_user_id` (the recipient's `chat_id`). Shared fields (`idempotency_key`, response shape, generic errors) are documented on the Send API page: [send_message](https://sumgenius.ai/docs/send-api#send-message), [idempotency](https://sumgenius.ai/docs/send-api#idempotency), [response format](https://sumgenius.ai/docs/send-api#response-format), [errors](https://sumgenius.ai/docs/send-api#errors).

Telegram routing & body

- platform_user_idstring The recipient's Telegram `chat_id` from an inbound event, with `platform: "telegram"`. There is no phone number or PSID on this channel. Required if `conversation_id` is not provided.
- conversation_idinteger The `conversation.id` from a received event. Use this or `platform` + `platform_user_id`.
- message_textstringrequired Max 4,096 characters. Delivered literally as plain text; it is never interpreted as HTML or Markdown. Not required for `typing_on`.

> **Note**
>
> **No messaging window.** Unlike Meta DM's 24-hour / 7-day window, Telegram has no time limit, but a bot can only message a chat that has already started it. Sending to a `chat_id` with no existing conversation record auto-creates the conversation and attempts the send; Telegram itself rejects a chat that has never started your bot (`chat not found`, HTTP 422).

A successful send returns the standard [response shape](https://sumgenius.ai/docs/send-api#response-format) with `platform: "telegram"` and a `telegram_message_id`. A `typing_on` call is identical with `"action": "typing_on"` and no `message_text`; it maps to Telegram's `sendChatAction`.

**Endpoint**

```
POST https://sumgenius.ai/api/meta/webhook-send.php
```

**Request**

```
curl -X POST https://sumgenius.ai/api/meta/webhook-send.php \
  -H "X-SumGenius-Api-Key: sgwh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "tg-reply-5310-001",
    "platform":        "telegram",
    "platform_user_id": "820032950394075",
    "message_text":    "Yes, we ship to Kyiv. Want me to start an order?"
  }'
```

Examples on this page use the [Send API](https://sumgenius.ai/docs/send-api). New integrations should prefer [`POST /v1/messages`](https://sumgenius.ai/docs/rest-api#send-message), which accepts the same body and returns the v1 envelope.