Send Telegram Message API
Send Telegram Message API for SMSGatewayCenter APIs
Send Telegram Message API
Use the Send Telegram API to deliver Telegram messages programmatically through SMSGatewayCenter. Send text, media (photo, audio, document, video, animation, voice, video_note), location, contact, and poll messages to a single chat, multiple chat IDs, or by phone number. This endpoint accepts POST requests with application/x-www-form-urlencoded and returns JSON.
Ideal for server-to-server delivery, transactional alerts, appointment reminders, and broadcasts triggered from your application.
API Endpoint
https://unify.smsgateway.center/rest/tg/v1/send
Authentication
Identify your account with one of the following methods: send userid + password in the POST body, or send userid in the body with your account API key in the apikey request header.
| Parameter | Required | Description | Example/Value |
|---|---|---|---|
| Authentication | |||
| userid | Yes | Your SMSGatewayCenter account username. The message is sent using the Telegram bot linked to this account. | YourUsername |
| password | Conditional | Your account password. Required when the apikey header is not sent. | ********** |
| Message Parameters | |||
| msgType | Yes | Message type: text, photo, audio, document, video, animation, voice, video_note, location, contact, or poll. | text |
| chatId | Conditional | Telegram chat ID. Required when phoneNumber is not sent. For multiple recipients, pass comma-separated IDs. Do not combine with phoneNumber. | 123456789,987654321 |
| phoneNumber | Conditional | Recipient mobile number with country code, digits only. Use instead of chatId when sending by phone. | 919999999999 |
| text | Conditional | Message body for text messages, or caption for media types. Max 4096 characters for text; max 1024 for captions. | Hello from API |
| mediaPayload | Conditional | JSON string with extra fields for non-text message types (see media payload fields below). | {"mediaUrl":"https://.../image.jpg"} |
| replyMarkup | Optional | JSON string for inline buttons, reply keyboard, force reply, or remove keyboard. Must follow the Telegram Bot API reply_markup format. | {"inline_keyboard":[[{"text":"Open","url":"https://..."}]]} |
| output | Optional | Response format. Use json for structured output. | json |
mediaPayload JSON Fields
| Field | Used for | Description |
|---|---|---|
mediaUrl | photo, audio, document, video, animation, voice, video_note | Public https:// URL to the media file. |
latitude, longitude | location | Decimal coordinates. Latitude -90 to 90, longitude -180 to 180. |
phoneNumber, firstName, lastName | contact | Contact card details. Phone may include a leading +. |
pollQuestion, pollOptions, isAnonymous | poll | Question max 300 characters. Provide 2-10 options as a JSON array. isAnonymous: 0 or 1. |
Sample Request - Text Message (cURL)
curl --location 'https://unify.smsgateway.center/rest/tg/v1/send' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'userid=YourUsername' \
--data-urlencode 'password=xxxxx' \
--data-urlencode 'msgType=text' \
--data-urlencode 'chatId=123456789' \
--data-urlencode 'text=Hello from API' \
--data-urlencode 'output=json'
Sample Request - API Key Header (cURL)
curl --location 'https://unify.smsgateway.center/rest/tg/v1/send' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: YourApiKey' \
--data-urlencode 'userid=YourUsername' \
--data-urlencode 'msgType=text' \
--data-urlencode 'chatId=123456789' \
--data-urlencode 'text=Hello from API' \
--data-urlencode 'output=json'
Sample Request - Photo with Caption (cURL)
curl --location 'https://unify.smsgateway.center/rest/tg/v1/send' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'userid=YourUsername' \
--data-urlencode 'password=xxxxx' \
--data-urlencode 'msgType=photo' \
--data-urlencode 'chatId=123456789' \
--data-urlencode 'text=Product image' \
--data-urlencode 'mediaPayload={"mediaUrl":"https://example.com/image.jpg"}'
Sample Request - Send by Phone Number (cURL)
curl --location 'https://unify.smsgateway.center/rest/tg/v1/send' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'userid=YourUsername' \
--data-urlencode 'password=xxxxx' \
--data-urlencode 'msgType=text' \
--data-urlencode 'phoneNumber=917770907999' \
--data-urlencode 'text=Hello'
Sample Request - Multiple Chat IDs (cURL)
curl --location 'https://unify.smsgateway.center/rest/tg/v1/send' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'userid=YourUsername' \
--data-urlencode 'password=xxxxx' \
--data-urlencode 'msgType=text' \
--data-urlencode 'chatId=536510855,496786735' \
--data-urlencode 'text=Broadcast message with multiple chat ids'
Sample Success Response
{
"status": "success",
"message": "Message sent successfully.",
"uniqueId": 17123456789012,
"uuId": "17123456789012",
"transactionId": "17123456789012",
"msgId": "42"
}
Sample Error Response
{
"status": "error",
"message": "Telegram API sending is disabled for this account."
}
Validation Rules
- Use either
chatIdorphoneNumber, never both in the same request. At least one recipient identifier is required. - Media messages require a valid public HTTPS
mediaUrlunless the type islocation,contact, orpoll. - Multiple recipients and phone-based sending require the Telegram API service to be enabled on your account.
- Track delivery using
uniqueId,uuId, ortransactionIdwith the Telegram Delivery Report REST API.
Testimonials
Why do Great Businesses Trust SMS Gateway Center?
