Skip to content
OmniChannels.ai
Menu

Telegram API

Send Telegram text, photos, documents, video, location and contact messages from your connected sender, use saved templates, and smoke-test in a sandbox.

Base URL https://api.broadnet.meUpdated

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#

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

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

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:

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#

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:

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#

Ready to send your first message?

Request test credentials. An engineer sets up your account, and test sends go to your own verified numbers.

Request test access