Bắt đầu từ đây
Yêu cầu đầu tiên của bạn trong bốn bước
Keep your main SMSMobileAPI subscription active; Telegram connection, API access, sending and sent-message history pause when it expires.
Kết nối tài khoản Telegram của bạn bằng QR code trong bảng điều khiển và đồng bộ hóa danh bạ của nó.
Sao chép khóa SMSMobileAPI của bạn từ My API Key và lưu trên máy chủ của bạn.
Liệt kê liên hệ và sao chép contact_id của người nhận dự kiến.
Send JSON for text, or multipart/form-data to attach an image or document. Use the returned message_id to check the sent log.
TÀI KHOẢN TELEGRAM CỦA BẠN
Kết nối, chọn một liên hệ, sau đó theo dõi việc gửi.
Mỗi khách hàng quét một QR code để kết nối tài khoản Telegram của họ. Đồng bộ danh bạ trong bảng điều khiển, dùng ID liên hệ trả về để đưa tin nhắn vào hàng đợi, rồi kiểm tra trạng thái trong nhật ký đã gửi.
1Kết nối
Quét QR code trên trang bảng điều khiển Telegram.
2Tìm một liên hệ
Đồng bộ, sau đó tìm ID liên hệ qua API.
3Gửi
POST một tin nhắn JSON với một khóa idempotency.
4Theo dõi
Đọc các trạng thái queued, sent, unknown hoặc error.
Xác thực
Giữ thẻ trên máy chủ
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.
- 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.
- QR code liên kết tài khoản Telegram riêng của từng khách hàng. Tin nhắn được gửi từ tài khoản đó, không phải từ tài khoản SMSMobileAPI dùng chung.
- Mã phản hồi 202 nghĩa là yêu cầu đã được đưa vào hàng đợi. Nó không chứng minh Telegram đã chấp nhận hoặc gửi tin nhắn. Kiểm tra nhật ký đã gửi để biết trạng thái đã gửi hoặc lỗi.
- Dịch vụ hiện gửi tới một liên hệ đã đồng bộ hoặc @username đã lưu cho mỗi yêu cầu. Tuân thủ quy tắc Telegram và sự đồng ý của người nhận.
- Yêu cầu bị giới hạn ở 15 tin nhắn mới mỗi phút và 30 tin nhắn đang chờ cho mỗi tài khoản đã kết nối. Sử dụng idempotency_key ổn định khi thử lại.
- 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.
LẤY
Liệt kê liên hệ Telegram
https://api.smsmobileapi.com/telegram/contacts/Trả về các liên hệ có sẵn trong tài khoản Telegram đã kết nối của bạn.
Tìm theo tên hiển thị hoặc @username, sau đó dùng contact_id để gửi.
Các tham số
| Tên | Kiểu | Cần thiết | Sự miêu tả |
|---|---|---|---|
q |
sợi dây | Tùy chọn | Tìm kiếm tên hoặc tên người dùng tùy chọn, tối đa 80 ký tự. |
limit |
Số nguyên | Tùy chọn | Kích thước trang từ 1 đến 100; mặc định 50. |
cursor |
Số nguyên | Tùy chọn | Dùng paging.next_cursor từ phản hồi trước; bỏ qua cho trang đầu. |
Ví dụ yêu cầu
curl -G 'https://api.smsmobileapi.com/telegram/contacts/' \
-H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
--data-urlencode 'q=Alex' \
--data-urlencode 'limit=50'Ví dụ về câu trả lời
{"ok":true,"data":[{"contact_id":42,"display_name":"Alex Example","username":"alex_example","source":"telegram"}],"paging":{"has_more":false,"next_cursor":null}}Muốn chạy yêu cầu này không?Kết nối phím API của bạn ở đầu trang để mở khóa bộ thử ra.
Phím kết nối Gỡ khóa- ID liên hệ thuộc về tài khoản đã kết nối; không thể dùng ID từ tài khoản khác.
- Làm mới danh bạ từ Dashboard → Telegram Contacts khi một người mới không xuất hiện.
BƯU KIỆN
Gửi một tin nhắn Telegram
https://api.smsmobileapi.com/telegram/send/Đưa vào hàng đợi một tin nhắn văn bản cho một liên hệ từ tài khoản Telegram đã kết nối của bạn.
Dùng contact_id từ endpoint contacts. Lưu message_id để theo dõi.
Các tham số
| Tên | Kiểu | Cần thiết | Sự miêu tả |
|---|---|---|---|
contact_id |
Số nguyên | Yêu cầu | ID liên hệ trả về bởi /telegram/contacts/. |
message |
sợi dây | Yêu cầu | Văn bản UTF-8, 1–4096 ký tự và tối đa 16.000 byte. |
idempotency_key |
Chuỗi UUID | Tùy chọn | Khóa ổn định kiểu UUID 36 ký tự viết thường. Tái sử dụng khi thử lại mạng để tránh gửi trùng. |
Ví dụ yêu cầu
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"}'Ví dụ về câu trả lời
{"ok":true,"message_id":123,"status":"queued","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161","duplicate":false}Muốn chạy yêu cầu này không?Kết nối phím API của bạn ở đầu trang để mở khóa bộ thử ra.
Phím kết nối Gỡ khóa- HTTP 202 nghĩa là đã xếp hàng; đây không phải là xác nhận giao hàng. Thử lại chính xác sẽ trả về HTTP 200 với duplicate=true và message_id gốc.
- Để thử lại, sử dụng lại cùng idempotency_key với cùng liên hệ và tin nhắn. Một payload thay đổi với cùng khóa sẽ trả về HTTP 409.
BƯU KIỆN
Send a Telegram image or document
https://api.smsmobileapi.com/telegram/send/Queue one file for a contact, with an optional caption.
Use multipart/form-data. The field name for the attachment is file.
Các tham số
| Tên | Kiểu | Cần thiết | Sự miêu tả |
|---|---|---|---|
contact_id |
Số nguyên | Yêu cầu | ID liên hệ trả về bởi /telegram/contacts/. |
file |
file | Yêu cầu | One JPG, PNG, WebP, PDF, TXT, CSV, JSON, ZIP or Office file, at most 5 MB. |
message |
sợi dây | Tùy chọn | Optional caption of at most 1024 characters. |
idempotency_key |
Chuỗi UUID | Tùy chọn | Reuse the same key and identical file and caption when retrying. |
Ví dụ yêu cầu
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'Ví dụ về câu trả lời
{"ok":true,"message_id":124,"status":"queued","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161","duplicate":false}Muốn chạy yêu cầu này không?Kết nối phím API của bạn ở đầu trang để mở khóa bộ thử ra.
Phím kết nối Gỡ khóa- 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.
BƯU KIỆN
Send a Telegram file using JSON
https://api.smsmobileapi.com/telegram/send/Queue one image or document using a Base64 string when multipart upload is inconvenient.
Encode the original file bytes with Base64. Do not include an API key in the JSON body.
Các tham số
| Tên | Kiểu | Cần thiết | Sự miêu tả |
|---|---|---|---|
contact_id |
Số nguyên | Yêu cầu | ID liên hệ trả về bởi /telegram/contacts/. |
filename |
sợi dây | Yêu cầu | Original file name, for example photo.png or invoice.pdf. |
file_base64 |
sợi dây | Yêu cầu | Raw Base64 file contents or a data URI; decoded file must be 5 MB or smaller. |
message |
sợi dây | Tùy chọn | Optional caption of at most 1024 characters. |
idempotency_key |
Chuỗi UUID | Tùy chọn | Reuse the same key with identical file contents, filename and caption on retries. |
Ví dụ yêu cầu
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"}'Ví dụ về câu trả lời
{"ok":true,"message_id":125,"status":"queued","idempotency_key":"2d40bb10-cc42-4c30-a282-93fc6dd8e161","duplicate":false}Muốn chạy yêu cầu này không?Kết nối phím API của bạn ở đầu trang để mở khóa bộ thử ra.
Phím kết nối Gỡ khóa- 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.
LẤY
Liệt kê tin nhắn Telegram đã gửi
https://api.smsmobileapi.com/telegram/sent/Trả về các tin nhắn hàng chờ, đang gửi, đã gửi và gửi lỗi gần đây, mới nhất trước.
Kiểm tra endpoint này với message_id để theo dõi tin nhắn được trả về bởi /telegram/send/.
Các tham số
| Tên | Kiểu | Cần thiết | Sự miêu tả |
|---|---|---|---|
message_id |
Số nguyên | Tùy chọn | Trả về message ID cụ thể từ /telegram/send/. |
contact_id |
Số nguyên | Tùy chọn | Giới hạn kết quả chỉ cho một contact ID. |
status |
queued | sending | sent | error | unknown | Tùy chọn | Lọc theo trạng thái gửi. |
limit |
Số nguyên | Tùy chọn | Kích thước trang từ 1 đến 100; mặc định 50. |
cursor |
Số nguyên | Tùy chọn | Dùng paging.next_cursor để truy xuất các tin nhắn cũ hơn. |
Ví dụ yêu cầu
curl -G 'https://api.smsmobileapi.com/telegram/sent/' \
-H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
--data-urlencode 'message_id=123'Ví dụ về câu trả lời
{"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}}Muốn chạy yêu cầu này không?Kết nối phím API của bạn ở đầu trang để mở khóa bộ thử ra.
Phím kết nối Gỡ khóa- 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 nghĩa là Telegram đã chấp nhận tin nhắn từ tài khoản được kết nối; việc giao tới người nhận và xác nhận đã đọc không được báo cáo.
- unknown nghĩa là không thể xác nhận kết quả gửi. Không được gửi lại tin nhắn một cách mù quáng trong trạng thái này.
LẤY
Download a sent Telegram attachment
https://api.smsmobileapi.com/telegram/media/Downloads a previously sent image or document while it remains available.
Use media.download_url from the sent log, or call this endpoint with the account API key.
Các tham số
| Tên | Kiểu | Cần thiết | Sự miêu tả |
|---|---|---|---|
message_id |
Số nguyên | Yêu cầu | Message ID returned by /telegram/send/. |
Ví dụ yêu cầu
curl -L 'https://api.smsmobileapi.com/telegram/media/?message_id=124' \
-H 'X-SMSMobileAPI-Key: YOUR_API_KEY' \
-o attachmentVí dụ về câu trả lời
Binary image or document bytes (Content-Type matches the file)Muốn chạy yêu cầu này không?Kết nối phím API của bạn ở đầu trang để mở khóa bộ thử ra.
Phím kết nối Gỡ khóa- 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.
Xử lý sự cố
Lỗi và cách ghi lưu an toàn
Đọc trường lỗi HTTP và trường lỗi JSON trước khi thử lại. Đừng thử lại hiệu lực hoặc xác thực lỗi mà không sửa lại yêu cầu trước.
| HTTP | Bộ mã | Làm sao đây? |
|---|---|---|
| 401 | api_key_required / invalid_api_key | Gửi một header X-SMSMobileAPI-Key hợp lệ. |
| 402 | subscription_expired | Renew the SMSMobileAPI subscription linked to the API key. Telegram API access resumes after renewal. |
| 403 | API_ENDPOINT_DISABLED | Bật Telegram API hoặc điểm cuối cụ thể này trong My API Key. |
| 404 | contact_not_found | Đồng bộ liên hệ và dùng ID từ kết nối Telegram của bạn. |
| 409 | telegram_not_connected / idempotency_conflict | Kết nối Telegram hoặc chọn khóa idempotency mới cho nội dung đã thay đổi. |
| 422 | invalid_message / invalid_pagination | Sửa tin nhắn, ID liên hệ hoặc tham số phân trang. |
| 429 | queue_full / rate_limited | Chờ các gửi đang hàng chờ hoặc giới hạn theo phút được giải phóng. |
| 503 | sending_unavailable / service_unavailable | Worker gửi hoặc lưu trữ tạm thời không khả dụng; thử lại sau. |
| 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. |
Bạn cần trợ giúp?
Hãy đưa ra yêu cầu về bối cảnh chứ không phải bí mật của bạn.
Chia sẻ điểm kết thúc, nhãn thời gian, trạng thái HTTP và phản ứng làm sạch. Không bao giờ bao gồm các phím API, vật thể hay tin nhắn riêng.
Ứng dụng di động chính thức
Cầu bảo mật giữa điện thoại, bảng điều khiển và API.
Kết nối và gọi đến cho chính thứcSMSMobileAPIỨng dụng được cài đặt trên điện thoại kết nối của bạn. Ứng dụng này đảm bảo kết nối thiết bị này với tài khoản của bạn, đồng bộ hoá các sự kiện cho phép và kết nối mạng di động vào bảng điều khiển và hệ thống điều khiển.
- Ký giấy phát hành qua danh sách Google Play và Apple App Store chính thức
- Xem lại nền tảng Google và Apple, ký và phân phối điều khiển
- Hai thiết bị bảo mật, HTTPS vận chuyển và xác thực quyền truy cập API
- Chỉ quyền hạn cần thiết cho các tính năng di động bạn bật
