Telegram

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, verifying signatures, and 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.

To handle Telegram conversations yourself with no AI reply, turn off the Telegram AI Assistant or use Global External Reply Mode; to keep message bodies out of stored delivery logs, see Inbound Body Purge.

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

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

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).

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.

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

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, idempotency, response format, 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.

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; it maps to Telegram's sendChatAction.

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

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