Telegram Channel

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 — the envelope, signing, and core actions are shared and documented on the Webhook & Send API page.

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

Overview

ChatGenius connects to Telegram through the Telegram Bot API. Once you connect and enable a bot in your portal, both inbound forwarding and the outbound Send API work for Telegram exactly like the other channels — same authentication, same idempotency, same signing secret, same envelope. The only differences are the routing identifier (a Telegram chat_id) and which actions are supported.

ℹ️

Requirements: a paid ChatGenius tier that includes Telegram, a connected and enabled Telegram bot (Settings → Telegram), and the Webhook & Send API add-on active. Until a bot is connected, the telegram.message_received checkbox on the Webhook & Send API page is disabled.

Capabilities

Capability	Support
Inbound forwarding	Messages to your bot are forwarded as telegram.message_received events
send_message	Supported — free-form text, no messaging window
typing_on	Supported — maps to Telegram's sendChatAction
react / unreact	Not supported on Telegram (rejected with HTTP 422)
Pure-relay mode	Turn off the Telegram AI Assistant (or enable Global External Reply Mode) — inbound still forwards, no AI reply

Inbound Payload

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

JSON — telegram.message_received example

{
  "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"
  }
}

Telegram-specific fields

Field	Type	Description
customer.platform_user_id	string	The Telegram chat_id. Pass this as platform_user_id (with platform: "telegram") to the Send API to reply. Always present — the stable join key for attribution.
customer.platform_user_name	string\|null	The sender's display name (first + last). Present in full payload profile only.
customer.platform_user_username	string\|null	The sender's Telegram @username (without the @), when they have set one; null otherwise.
message.id	string	<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_id	string	Same as customer.platform_user_id; the recipient identifier for the Send API.
message.telegram.chat_type	string	One of private, group, supergroup, channel.
message.telegram.message_type	string	text, or the media kind for a captioned media message (e.g. photo, document, voice, video).

ℹ️

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 from that chat 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; text and captioned media are. Signature verification, retries, and timestamp validation are identical to every other channel — see Verifying Signatures.

Sending Telegram Messages

Send to a Telegram chat by conversation_id, or by platform: "telegram" plus platform_user_id (the recipient's chat_id). Text is delivered literally — it is never interpreted as HTML or Markdown.

POST /api/meta/webhook-send.php

Request body

Field	Required	Description
action	optional	Defaults to send_message. Telegram supports send_message and typing_on.
idempotency_key	required	Your unique key for this request (max 128 chars). The same key returns the original result without resending.
platform	required*	Set to telegram when routing by platform_user_id. *Not needed when routing by conversation_id.
platform_user_id	required*	The recipient's Telegram chat_id (from an inbound event). *Required if conversation_id is not provided.
conversation_id	required*	The conversation.id from a received event. *Use this OR platform + platform_user_id.
message_text	required	The message body. Max 4,096 characters. Not required for typing_on.

curl

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?"
  }'

A successful send returns the standard response shape with platform: "telegram" and a telegram_message_id. A typing_on call is identical with "action": "typing_on" and no message_text.

Telegram Specifics

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. There is no cold-outbound: sending to a chat that has never messaged your bot returns "No conversation found".
chat_id is the identifier. There is no phone number or PSID — route replies by chat_id (as platform_user_id) or by conversation_id.
Reactions are not supported. react and unreact are rejected with HTTP 422 and are not sent.
Plain text only. Message text is sent literally; formatting markup in your text is not interpreted.