> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zexa.ao/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Messaging with Zexa: Bot Setup and API Guide

> Send messages to Telegram users and channels via Zexa. Connect your Telegram bot token and start reaching subscribers programmatically.

Zexa connects to the Telegram Bot API so you can programmatically send messages to individual users or broadcast updates to Telegram channels. Once your bot is connected, sending a message is as simple as a single API call — no polling or webhook management required on your end.

## Setup

Connect your Telegram bot to Zexa by following these steps:

<Steps>
  <Step title="Create a bot via @BotFather">
    Open Telegram and start a conversation with [@BotFather](https://t.me/BotFather). Use the `/newbot` command, follow the prompts to name your bot, and copy the **bot token** that BotFather provides.
  </Step>

  <Step title="Open Telegram settings in Zexa">
    Log in to the [Zexa dashboard](https://app.zexa.ao) and navigate to **Channels > Telegram**.
  </Step>

  <Step title="Paste your bot token">
    Enter the bot token you copied from BotFather and click **Save**. Zexa will verify the token and activate the connection.
  </Step>

  <Step title="Have users start a conversation">
    Before you can message a user, they must first initiate a conversation with your bot on Telegram (or subscribe to your channel). This gives your bot permission to send them messages and provides you with their **chat ID**.
  </Step>
</Steps>

<Note>
  You cannot send messages to a Telegram user who has not previously interacted with your bot. This is a Telegram platform restriction, not a Zexa limitation.
</Note>

## Send a Telegram message via API

Send a `POST` request to `/messages` with `"channel": "telegram"` to deliver a message via your connected bot.

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.zexa.ao/v1/messages \
    --header 'Authorization: Bearer <api_key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "channel": "telegram",
      "to": "CHAT_ID",
      "from": "my_bot",
      "body": "Your delivery is on its way!"
    }'
  ```

  ```python python theme={null}
  import requests

  url = "https://api.zexa.ao/v1/messages"

  payload = {
      "channel": "telegram",
      "to": "CHAT_ID",
      "from": "my_bot",
      "body": "Your delivery is on its way!"
  }

  headers = {
      "Authorization": "Bearer <api_key>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

A successful request returns a `201` response with the message object:

```json theme={null}
{
  "id": "msg_tg8834",
  "status": "queued",
  "channel": "telegram",
  "to": "CHAT_ID",
  "created_at": "2026-06-24T10:10:00Z"
}
```

<Tip>
  The `to` field for Telegram is the recipient's **chat ID**, not a phone number. You can capture the chat ID automatically by handling the first incoming message from a user via a Zexa inbound webhook.
</Tip>

## Supported message formats

Zexa supports the following content types when sending Telegram messages through the API:

* **Plain text** — standard unformatted message content.
* **Markdown formatting** — use `**bold**`, `_italic_`, and `` `inline code` `` syntax to style your messages. Telegram renders these natively.
* **Links** — include URLs directly in the message body; Telegram auto-previews them by default.

For richer content such as images, files, or inline buttons, refer to the Zexa API documentation.

## Next steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/api/webhooks">
    Receive incoming Telegram messages and capture chat IDs automatically with Zexa webhooks.
  </Card>

  <Card title="Campaigns" icon="bullhorn" href="/messaging/campaigns">
    Broadcast messages to large subscriber lists across Telegram and other channels with scheduling and reporting.
  </Card>
</CardGroup>