Telegram’s interactive types

Telegram bots support a few kinds of interactive elements, all sendable through the Octopods API under a single payload shape:

Reply buttons (reply_buttons) — buttons attached to the message itself. Tapping a button sends a callback that Octopods forwards to your inbox as a special inbound entry.
Reply keyboard (reply_keyboard) — a custom keyboard that appears below the text input. Tapping a key sends that key’s text as a regular reply message. The keyboard is persistent until dismissed.
Remove reply keyboard (remove_reply_keyboard) — clear a reply keyboard you previously sent.
Highlight reply (highlight_reply) — a reply that highlights or quotes a previous message.

These messages are freeform and do not require any template approval.

Before you start

You need:

A Telegram channel in Active status. See Setting Up Telegram or Setting Up Telegram for HubSpot.
The channel API key from the channel detail page.
A destination user ID for the recipient. Telegram user IDs are captured automatically when a customer messages your bot; each conversation in your inbox corresponds to one user ID.
The Telegram interactive API enabled on your account. If your account isn’t opted in, the endpoint returns HTTP 403. Contact Octopods support to enable it.

Note: Telegram bots cannot message a user who hasn’t messaged them first. You can only use this API for users who have already started a conversation with your bot.

Endpoint

Send a POST request to:

POST https://api.octopods.io/api/v1/telegram/interactive

Authenticate with your channel API key in the X-Octopods-Auth header:

X-Octopods-Auth: <your-channel-api-key>

Payload shape

The top-level body has two fields:

destination_user_id — the recipient’s Telegram user ID.
telegram_interactive_message — an object that contains the entire interactive payload, including its type (reply_buttons, reply_keyboard, remove_reply_keyboard, or highlight_reply) and the type-specific structure.

Optional top-level fields:

open_intercom_conversation — true to automatically open a new Intercom conversation when the message is sent.
intercom_teammate_id — the ID of the Intercom user who should appear as the sender.

Reply buttons

Use type: "reply_buttons" to attach an inline button grid to a message.

{
  "destination_user_id": "123456789",
  "telegram_interactive_message": {
    "type": "reply_buttons",
    "text": "Here's your order summary. What would you like to do next?",
    "buttons": [
      [
        { "text": "View receipt", "url": "https://example.com/receipt/ORD-9876" }
      ],
      [
        { "text": "Track shipment", "callback_data": "track:ORD-9876" },
        { "text": "Contact support", "callback_data": "support:ORD-9876" }
      ]
    ]
  }
}

Each inner array is a row; the example renders as one button on the first row and two on the second. Buttons can either open a URL (url) or send a callback payload (callback_data).

Reply keyboard

Use type: "reply_keyboard" to replace the user’s keyboard with a custom button set. Tapping a button sends its text as a regular reply.

{
  "destination_user_id": "123456789",
  "telegram_interactive_message": {
    "type": "reply_keyboard",
    "text": "Pick a topic to continue.",
    "keyboard": [
      ["Orders", "Returns"],
      ["Account", "Other"]
    ],
    "resize_keyboard": true,
    "one_time_keyboard": true
  }
}

resize_keyboard — shrink the keyboard to fit the number of buttons.
one_time_keyboard — hide the keyboard after the user taps a button.

Remove reply keyboard

To dismiss a reply keyboard you previously sent, use type: "remove_reply_keyboard":

{
  "destination_user_id": "123456789",
  "telegram_interactive_message": {
    "type": "remove_reply_keyboard",
    "text": "Thanks, we've got what we need."
  }
}

Response

On success, Octopods returns details about the queued send:

{
  "request_id": "req_01HT5Q...",
  "message_id": "msg_01HT5Q...",
  "message_status_url": "https://api.octopods.io/api/v1/telegram/messages/msg_01HT5Q...",
  "destination_user_id": "123456789"
}

Handling callbacks

When a user taps an inline button with callback_data:

Telegram sends a callback event to Octopods.
Octopods appends a special inbound entry to the conversation in your inbox. The entry contains the button’s callback_data payload.
Your agent or automation reads the callback data and responds however you’d like.

Callback handling requires your automation to read conversations from Intercom or HubSpot. Plain-text responses to the customer can be sent from the inbox UI or through the same interactive endpoint.

Common errors

HTTP 403 — Telegram interactive messaging is an opt-in feature. Contact Octopods support to enable it on your account.
Chat not found — the user hasn’t messaged your bot yet. Wait for them to start a conversation.
Message too long — Telegram limits message text to 4,096 characters. Shorten the message.
Unauthorized — the X-Octopods-Auth header is missing, revoked, or from a different channel.
Bot blocked — the user has blocked your bot. No messages can be delivered until they unblock you.

For the full numeric error-code table, see API Error Reference.

Sending Telegram Interactive Messages