---
title: "Telegram API"
description: "Send Telegram text, photos, documents, video, location and contact messages from your connected sender, use saved templates, and smoke-test in a sandbox."
canonical: "https://omnichannels.ai/developers/telegram/"
language: "en"
updated: "2026-10-10"
publisher: "BroadNet Technologies"
brand: "OmniChannels.ai"
section: "Messaging channels"
---

# Telegram API

Canonical: https://omnichannels.ai/developers/telegram/
Language: en
Publisher: OmniChannels.ai by BroadNet Technologies

The Telegram API sends messages from your connected Telegram sender to phone numbers and chats. Every message type goes through `POST /telegram-sms/send`, a multipart endpoint where `messageType` selects the payload.

## Before you send

Your Telegram sender is connected and activated with our team during onboarding. Once it is live, you send with your normal Bearer token; no Telegram-specific credentials are needed in your API calls.

Recipients can be phone numbers in international format with a leading `+` (for example `+447700900123`) or numeric chat IDs.

## Send a message

```bash title="cURL"
curl -X POST https://api.broadnet.me/telegram-sms/send \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F campaignName=order-updates \
  -F allowDuplicate=false \
  -F destinationNo=+447700900123 \
  -F messageType=TEXT \
  -F "content=Your OmniDemo order 8842 has shipped."
```

```js title="Node.js"
const form = new FormData();
form.append("batchId", "0");
form.append("campaignName", "order-updates");
form.append("allowDuplicate", "false");
form.append("destinationNo", "+447700900123");
form.append("messageType", "TEXT");
form.append("content", "Your OmniDemo order 8842 has shipped.");

const res = await fetch("https://api.broadnet.me/telegram-sms/send", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BROADNET_TOKEN}` },
  body: form,
});
console.log(await res.json());
```

```python title="Python"
import os
import requests

fields = {
    "batchId": "0",
    "campaignName": "order-updates",
    "allowDuplicate": "false",
    "destinationNo": "+447700900123",
    "messageType": "TEXT",
    "content": "Your OmniDemo order 8842 has shipped.",
}
r = requests.post(
    "https://api.broadnet.me/telegram-sms/send",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    files={k: (None, v) for k, v in fields.items()},
    timeout=30,
)
print(r.json())
```

The response summarises the batch. Use `batchId` to track and control it:

```json title="Response"
{
  "totalFilesProcessed": 0,
  "totalNumbersSuccess": 1,
  "totalNumbersFailed": 0,
  "totalNumbersDuplicate": 0,
  "batchId": "2601221336333031021",
  "files": []
}
```

When you upload a recipients file in `destinationFiles`, `files` lists per-file counts and any failed or duplicate numbers.

## Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messageType` | string | Yes | `TEXT`, `PHOTO`, `VIDEO`, `AUDIO`, `DOCUMENT`, `STICKER`, `LOCATION`, `CONTACT` or `REACTION`. |
| `destinationNo` | string | One of these two | One or more recipients, comma-separated. |
| `destinationFiles` | file | One of these two | CSV file of recipients. |
| `content` | string | `TEXT`; caption otherwise | Message text, or the caption for media. |
| `file` | file | Media types | The photo, video, audio, document or sticker (`.webp`). |
| `showCaptionAboveMedia`, `hasSpoiler` | string | No | Media display options (`true` or `false`). |
| `supportsStreaming` | string | No | For `VIDEO`. |
| `latitude`, `longitude` | string | `LOCATION` | Coordinates. |
| `phoneNumber`, `firstName`, `lastName` | string | `CONTACT` | The contact to share. |
| `replyToMessageId` | string | No | Reply to, or react to, an earlier message. |
| `emoji` | string | `REACTION` | The reaction emoji. |
| `templateId` | string | No | Send a saved template. |
| `batchId` | string | No | `0` starts a new batch. |
| `campaignName`, `allowDuplicate`, `delay` | string | No | Reporting label, de-duplication and throttle. |
| `scheduled`, `scheduleTime`, `gmt` | string | No | Schedule the send. |

### Send a document

```bash title="cURL"
curl -X POST https://api.broadnet.me/telegram-sms/send \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=+447700900123 \
  -F messageType=DOCUMENT \
  -F "content=Your October invoice" \
  -F file=@invoice-oct.pdf
```

## Templates

| Method | Path | Description |
| --- | --- | --- |
| POST | `/telegram-templates/save` | Create a template. |
| POST | `/telegram-templates/get-all` | List templates. |
| GET | `/telegram-templates/by-id/{TEMPLATE_ID}` | Read one template. |
| PUT | `/telegram-templates/update/{TEMPLATE_ID}` | Update a template. |
| DELETE | `/telegram-templates/delete/{TEMPLATE_ID}` | Delete a template. |

## Batches

| Method | Path | Description |
| --- | --- | --- |
| POST | `/telegram/telegram-sms/all-bulk` | List batches with filters. |
| GET | `/telegram/telegram-sms/edit?batch_Id=…` | Batch details. |
| GET | `/telegram/telegram-sms/pause?batch_Id=…` | Pause a batch. |
| GET | `/telegram/telegram-sms/resume?batch_Id=…` | Resume a batch. |
| DELETE | `/telegram/telegram-sms/abort?batch_Id=…` | Abort a batch. |

## Sandbox

For smoke tests, `POST /telegram/telegram-sandbox/send` sends a single message through a sandbox session. Our team connects the sandbox session for you; then send with:

```bash title="cURL"
curl -X POST https://api.broadnet.me/telegram/telegram-sandbox/send \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F to=+447700900123 \
  -F "text=Sandbox test from OmniDemo"
```

`to` accepts a numeric chat ID, a public `@username` or a phone number. Sandbox traffic is for testing only; use `/telegram-sms/send` for real campaigns.

## Next steps

- [Webhooks](/developers/webhooks/): receive delivery statuses.
- [Errors and limits](/developers/errors-and-limits/): handle errors and retries.
- [Email](/developers/email/) and [Push](/developers/push/): the other owned channels.