Start here

Your first request in four steps

Keep your main SMSMobileAPI subscription active; Telegram connection, API access, sending and sent-message history pause when it expires.

Connect your own Telegram account by QR code in the dashboard and synchronize its contacts.

Copy your SMSMobileAPI key from My API Key and keep it on your server.

List contacts and copy the contact_id of the intended recipient.

Send JSON for text, or multipart/form-data to attach an image or document. Use the returned message_id to check the sent log.

YOUR TELEGRAM ACCOUNT

Connect, choose a contact, then follow the send.

Account scoped

Each customer scans a QR code to connect their own Telegram account. Synchronize contacts in the dashboard, use the returned contact ID to queue a message, then inspect its status in the sent log.

1

Connect

Scan the QR code in the Telegram dashboard page.

2

Find a contact

Synchronize, then search for the contact ID via API.

3

Send

POST one JSON message with an idempotency key.

4

Track

Read queued, sent, unknown or error states.

Authentication

Keep credentials on your server

Send X-SMSMobileAPI-Key: YOUR_API_KEY in an HTTPS header. Keep this key on your server, never in browser JavaScript or a public repository. The endpoints are scoped to the Telegram account connected to that SMSMobileAPI account. A short-lived signed download_url can be opened without the key. Access can be disabled in My API Key.

Before you integrate

An expired SMSMobileAPI subscription blocks Telegram API access with HTTP 402 subscription_expired, including attachment downloads. Renew in the dashboard to restore access; existing connection and history are preserved.
The QR code links each customer’s own Telegram account. Messages are sent from that account, not from a shared SMSMobileAPI account.
A 202 response means the request was queued. It does not prove Telegram accepted or delivered the message. Poll the sent log for sent or error.
The service currently sends to one synchronized contact or saved @username per request. Respect Telegram rules and recipient consent.
Requests are limited to 15 new messages per minute and 30 queued messages per connected account. Use a stable idempotency_key when retrying.
Images and documents can be up to 5 MB. The send queue holds file bytes only until processing finishes; a separate private copy supports later downloads. File bytes are never embedded in the sent log.
Newly sent attachments are kept in private storage for 90 days. The sent log returns a download_url valid for 15 minutes; request the log again to get a new link. Older attachments sent before this feature have no downloadable copy.

GET

List Telegram contacts

ENDPOINThttps://api.smsmobileapi.com/telegram/contacts/

Returns contacts available in your connected Telegram account.

When to use it

Search by display name or @username, then use contact_id to send.

Parameters

Name	Type	Requirement	Description
`q`	string	Optional	Optional name or username search, up to 80 characters.
`limit`	integer	Optional	Page size from 1 to 100; default 50.
`cursor`	integer	Optional	Use paging.next_cursor from the previous response; omit for the first page.

Request example

cURL

curl -G 'https://api.smsmobileapi.com/telegram/contacts/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  --data-urlencode 'q=Alex' \
  --data-urlencode 'limit=50'

Example response

JSON

{"ok":true,"data":[{"contact_id":42,"display_name":"Alex Example","username":"alex_example","source":"telegram"}],"paging":{"has_more":false,"next_cursor":null}}

Want to run this request? Connect your API key at the top of the page to unlock the interactive tester.

Connect key ↑

Good to know

Contact IDs belong to the connected account; an ID from another account cannot be used.
Refresh contacts from Dashboard → Telegram Contacts when someone new does not appear.

POST

Send a Telegram message

ENDPOINThttps://api.smsmobileapi.com/telegram/send/

Queues one text message for a contact from your connected Telegram account.

When to use it

Use contact_id from the contacts endpoint. Save message_id for tracking.

Parameters

Name	Type	Requirement	Description
`contact_id`	integer	Required	Contact ID returned by /telegram/contacts/.
`message`	string	Required	UTF-8 text, 1–4096 characters and at most 16,000 bytes.
`idempotency_key`	UUID string	Optional	Stable 36-character lowercase UUID-style key. Reuse on network retries to avoid duplicate messages.

Request example

cURL

curl -X POST 'https://api.smsmobileapi.com/telegram/send/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"contact_id":42,"message":"Your appointment is confirmed.","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161"}'

Example response

JSON

{"ok":true,"message_id":123,"status":"queued","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161","duplicate":false}

Want to run this request? Connect your API key at the top of the page to unlock the interactive tester.

Connect key ↑

Good to know

HTTP 202 means queued; it is not a delivery receipt. An exact retry returns HTTP 200 with duplicate=true and the original message_id.
For retries, reuse the same idempotency_key with the same contact and message. A changed payload with the same key returns HTTP 409.

POST

Send a Telegram image or document

ENDPOINThttps://api.smsmobileapi.com/telegram/send/

Queue one file for a contact, with an optional caption.

When to use it

Use multipart/form-data. The field name for the attachment is file.

Parameters

Name	Type	Requirement	Description
`contact_id`	integer	Required	Contact ID returned by /telegram/contacts/.
`file`	file	Required	One JPG, PNG, WebP, PDF, TXT, CSV, JSON, ZIP or Office file, at most 5 MB.
`message`	string	Optional	Optional caption of at most 1024 characters.
`idempotency_key`	UUID string	Optional	Reuse the same key and identical file and caption when retrying.

Request example

cURL

curl -X POST 'https://api.smsmobileapi.com/telegram/send/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  -F 'contact_id=42' \
  -F 'message=Here is the document.' \
  -F 'file=@./document.pdf' \
  -F 'idempotency_key=2d40bb10-cc42-4c30-a282-93fc6dd8e161'

Example response

JSON

{"ok":true,"message_id":124,"status":"queued","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161","duplicate":false}

Want to run this request? Connect your API key at the top of the page to unlock the interactive tester.

Connect key ↑

Good to know

Do not set Content-Type manually; cURL adds the multipart boundary.
For JSON clients, send file_base64 with the Base64 file contents and filename, alongside contact_id and an optional message caption.
A queued response is not proof of delivery. Check GET /telegram/sent/?message_id=124.
The connected Telegram account sends the file to one contact.

POST

Send a Telegram file using JSON

ENDPOINThttps://api.smsmobileapi.com/telegram/send/

Queue one image or document using a Base64 string when multipart upload is inconvenient.

When to use it

Encode the original file bytes with Base64. Do not include an API key in the JSON body.

Parameters

Name	Type	Requirement	Description
`contact_id`	integer	Required	Contact ID returned by /telegram/contacts/.
`filename`	string	Required	Original file name, for example photo.png or invoice.pdf.
`file_base64`	string	Required	Raw Base64 file contents or a data URI; decoded file must be 5 MB or smaller.
`message`	string	Optional	Optional caption of at most 1024 characters.
`idempotency_key`	UUID string	Optional	Reuse the same key with identical file contents, filename and caption on retries.

Request example

cURL

curl -X POST 'https://api.smsmobileapi.com/telegram/send/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"contact_id":42,"filename":"photo.png","file_base64":"BASE64_ENCODED_FILE","message":"See attached","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161"}'

Example response

JSON

{"ok":true,"message_id":125,"status":"queued","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161","duplicate":false}

Want to run this request? Connect your API key at the top of the page to unlock the interactive tester.

Connect key ↑

Good to know

Replace BASE64_ENCODED_FILE with the actual Base64 of a supported file.
Use multipart/form-data instead if your client supports direct file upload; it avoids Base64 size overhead.

GET

List sent Telegram messages

ENDPOINThttps://api.smsmobileapi.com/telegram/sent/

Returns recent queued, sending, sent and failed messages, newest first.

When to use it

Poll this endpoint with message_id to follow a message returned by /telegram/send/.

Parameters

Name	Type	Requirement	Description
`message_id`	integer	Optional	Return the specific message ID from /telegram/send/.
`contact_id`	integer	Optional	Limit results to one contact ID.
`status`	queued \| sending \| sent \| error \| unknown	Optional	Filter by sending state.
`limit`	integer	Optional	Page size from 1 to 100; default 50.
`cursor`	integer	Optional	Use paging.next_cursor to fetch older messages.

Request example

cURL

curl -G 'https://api.smsmobileapi.com/telegram/sent/' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  --data-urlencode 'message_id=123'

Example response

JSON

{"ok":true,"data":[{"message_id":123,"contact_id":42,"contact_name":"Alex Example","username":"alex_example","message":"Your appointment is confirmed.","type":"text","media":null,"status":"sent","telegram_message_id":781,"error_code":null,"error_detail":null,"attempts":1,"queued_at":"2026-11-06T09:42:00+00:00","sent_at":"2026-11-06T09:42:04+00:00"}],"paging":{"has_more":false,"next_cursor":null}}

Want to run this request? Connect your API key at the top of the page to unlock the interactive tester.

Connect key ↑

Good to know

The top-level type is text, image or file. For an attachment, media contains the filename, MIME type, size, download_url and available_until; media is null for text messages. File bytes are not embedded in the log.
The download_url opens in a browser for 15 minutes. Refresh this endpoint for a new link while the file remains available.
sent means Telegram accepted the message from the connected account; recipient delivery and read receipts are not reported.
unknown means the sending outcome could not be confirmed. Do not blindly resend a message in this state.

GET

Download a sent Telegram attachment

ENDPOINThttps://api.smsmobileapi.com/telegram/media/

Downloads a previously sent image or document while it remains available.

When to use it

Use media.download_url from the sent log, or call this endpoint with the account API key.

Parameters

Name	Type	Requirement	Description
`message_id`	integer	Required	Message ID returned by /telegram/send/.

Request example

cURL

curl -L 'https://api.smsmobileapi.com/telegram/media/?message_id=124' \
  -H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
  -o attachment

Example response

JSON

Binary image or document bytes (Content-Type matches the file)

Want to run this request? Connect your API key at the top of the page to unlock the interactive tester.

Connect key ↑

Good to know

A download_url returned by /telegram/sent/ is signed and works without an API key for 15 minutes. Keep it private.
The authenticated endpoint requires the Telegram sent-log API access switch.
Files are retained for 90 days; the type and filename remain in the log after expiry.

Troubleshooting

Errors and safe retries

Read the HTTP status and the JSON error field before retrying. Do not retry validation or authentication failures without correcting the request first.

HTTP	Code	What to do
401	`api_key_required / invalid_api_key`	Send a valid X-SMSMobileAPI-Key header.
402	`subscription_expired`	Renew the SMSMobileAPI subscription linked to the API key. Telegram API access resumes after renewal.
403	`API_ENDPOINT_DISABLED`	Enable the Telegram API or this specific endpoint in My API Key.
404	`contact_not_found`	Synchronize contacts and use an ID from your own Telegram connection.
409	`telegram_not_connected / idempotency_conflict`	Connect Telegram or choose a new idempotency key for changed content.
422	`invalid_message / invalid_pagination`	Correct the message, contact ID or paging parameters.
429	`queue_full / rate_limited`	Wait for queued sends or the per-minute limit to clear.
503	`sending_unavailable / service_unavailable`	The sending worker or storage is temporarily unavailable; retry later.
503	`media_not_ready`	File sending requires the current Telegram service update. Text sending remains available.
404 / 410	`media_not_found / media_expired`	The file is unavailable or past its 90-day retention period.

Retry ruleRetry only transient 429 and 5xx responses. Start after 1 second, then back off to 2, 4 and 8 seconds.

Need help?

Bring the request context—not your secrets.

Share the endpoint, timestamp, HTTP status and sanitized response. Never include API keys, tokens or private message content.

Contact API support →

The secure SMSMobileAPI mobile app connecting a phone to the web dashboard and REST API for SMS and call operations — Encrypted mobile-to-platform connection

Official mobile application

The secure bridge between your phone, dashboard and API.

SMS and call operations pass through the official SMSMobileAPI app installed on your connected phone. The app securely pairs the device with your account, synchronizes authorized events and links the mobile network to the dashboard and REST API.

1Mobile appPairs the phone and its SIM 2Encrypted linkAuthenticates and protects data in transit 3Dashboard & APIControls workflows and activity

Signed releases distributed through the official Google Play and Apple App Store listings
Google and Apple platform review, signing and distribution controls
Secure device pairing, HTTPS transport and authenticated API access
Only the permissions required for the mobile features you enable

Get the official SMSMobileAPI app on Google Play

Download the official SMSMobileAPI app on the Apple App Store

Capabilities depend on the permissions and background access allowed by Android or iOS.

Telegram API documentation

Your first request in four steps

Connect

Find a contact

Send

Track

Keep credentials on your server

Parameters

Request example

Example response

Parameters

Request example

Example response

Parameters

Request example

Example response

Parameters

Request example

Example response

Parameters

Request example

Example response

Parameters

Request example

Example response

Errors and safe retries

Bring the request context—not your secrets.

The secure bridge between your phone, dashboard and API.