Inizia qui

La vostra prima richiesta in quattro passi

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

Connetti il tuo account Telegram tramite QR code nella dashboard e sincronizza i suoi contatti.

Copia la tua chiave SMSMobileAPI da My API Key e conservala sul tuo server.

Elenca i contatti e copia il contact_id del destinatario desiderato.

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

IL TUO ACCOUNT TELEGRAM

Connetti, scegli un contatto, poi segui l'invio.

Conto in corso

Ogni cliente esegue la scansione di uno QR code per connettere il proprio account Telegram. Sincronizza i contatti nella dashboard, usa l'ID contatto restituito per mettere in coda un messaggio, quindi verifica lo stato nel registro inviati.

1

Collegare

Scansiona lo QR code nella pagina della dashboard Telegram.

2

Trova un contatto

Sincronizza, poi cerca l'ID contatto tramite API.

3

Inviare

POST un messaggio JSON con una chiave di idempotenza.

4

Traccia

Leggi stati in coda, inviato, sconosciuto o errore.

Autenticazione

Mantenere le credenziali sul 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.

Prima di integrare

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.
Lo QR code collega l'account Telegram di ciascun cliente. I messaggi sono inviati da quell'account, non da un account SMSMobileAPI condiviso.
Una risposta 202 significa che la richiesta è stata messa in coda. Non prova che Telegram abbia accettato o consegnato il messaggio. Interroga il registro inviati per invii o errori.
Il servizio invia attualmente un contatto sincronizzato o un @username salvato per richiesta. Rispetta le regole Telegram e il consenso del destinatario.
Le richieste sono limitate a 15 nuovi messaggi al minuto e 30 messaggi in coda per account connesso. Usa un idempotency_key stabile quando ritenti.
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.

OTTENERE

Elenca i contatti Telegram

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

Restituisce i contatti disponibili nel tuo account Telegram connesso.

Quando usarlo

Cerca per display name o @username, poi usa contact_id per inviare.

Parametri

Nome	Tipo	Requisito	Descrizione
`q`	corda	Facoltativo	Ricerca opzionale per nome o username, fino a 80 caratteri.
`limit`	Integer	Facoltativo	Dimensione pagina da 1 a 100; default 50.
`cursor`	Integer	Facoltativo	Usa paging.next_cursor dalla risposta precedente; ometti per la prima pagina.

Esempio di richiesta

CURL

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

Esempio di risposta

JSON

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

Vuoi eseguire questa richiesta?Collegare il tasto API nella parte superiore della pagina per sbloccare il tester interattivo.

Collegare la chiave

Buono a sapersi

Gli ID contatto appartengono all'account connesso; non è possibile usare un ID di un altro account.
Aggiorna i contatti da Dashboard → Telegram Contacts quando una nuova persona non appare.

INVIARE

Invia un messaggio Telegram

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

Mette in coda un messaggio di testo per un contatto dal tuo account Telegram connesso.

Quando usarlo

Usa contact_id dall'endpoint contacts. Salva message_id per il tracciamento.

Parametri

Nome	Tipo	Requisito	Descrizione
`contact_id`	Integer	Necessario	ID contatto restituito da /telegram/contacts/.
`message`	corda	Necessario	Testo UTF-8, da 1 a 4096 caratteri e al massimo 16.000 byte.
`idempotency_key`	Stringa UUID	Facoltativo	Chiave stabile di 36 caratteri in stile UUID minuscolo. Riutilizzala nei retry di rete per evitare messaggi duplicati.

Esempio di richiesta

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"}'

Esempio di risposta

JSON

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

Vuoi eseguire questa richiesta?Collegare il tasto API nella parte superiore della pagina per sbloccare il tester interattivo.

Collegare la chiave

Buono a sapersi

HTTP 202 significa in coda; non è una ricevuta di consegna. Un retry identico restituisce HTTP 200 con duplicate=true e il message_id originale.
Per i tentativi successivi, riusa la stessa idempotency_key con lo stesso contatto e messaggio. Un payload modificato con la stessa chiave restituisce HTTP 409.

INVIARE

Send a Telegram image or document

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

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

Quando usarlo

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

Parametri

Nome	Tipo	Requisito	Descrizione
`contact_id`	Integer	Necessario	ID contatto restituito da /telegram/contacts/.
`file`	file	Necessario	One JPG, PNG, WebP, PDF, TXT, CSV, JSON, ZIP or Office file, at most 5 MB.
`message`	corda	Facoltativo	Optional caption of at most 1024 characters.
`idempotency_key`	Stringa UUID	Facoltativo	Reuse the same key and identical file and caption when retrying.

Esempio di richiesta

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'

Esempio di risposta

JSON

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

Vuoi eseguire questa richiesta?Collegare il tasto API nella parte superiore della pagina per sbloccare il tester interattivo.

Collegare la chiave

Buono a sapersi

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.

INVIARE

Send a Telegram file using JSON

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

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

Quando usarlo

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

Parametri

Nome	Tipo	Requisito	Descrizione
`contact_id`	Integer	Necessario	ID contatto restituito da /telegram/contacts/.
`filename`	corda	Necessario	Original file name, for example photo.png or invoice.pdf.
`file_base64`	corda	Necessario	Raw Base64 file contents or a data URI; decoded file must be 5 MB or smaller.
`message`	corda	Facoltativo	Optional caption of at most 1024 characters.
`idempotency_key`	Stringa UUID	Facoltativo	Reuse the same key with identical file contents, filename and caption on retries.

Esempio di richiesta

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"}'

Esempio di risposta

JSON

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

Vuoi eseguire questa richiesta?Collegare il tasto API nella parte superiore della pagina per sbloccare il tester interattivo.

Collegare la chiave

Buono a sapersi

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.

OTTENERE

Elenca i messaggi Telegram inviati

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

Restituisce i messaggi recenti in coda, in invio, inviati e falliti, dal più nuovo al più vecchio.

Quando usarlo

Interroga questo endpoint con message_id per seguire un messaggio restituito da /telegram/send/.

Parametri

Nome	Tipo	Requisito	Descrizione
`message_id`	Integer	Facoltativo	Restituisci l'ID messaggio specifico da /telegram/send/.
`contact_id`	Integer	Facoltativo	Limita i risultati a un unico ID contatto.
`status`	queued \| sending \| sent \| error \| unknown	Facoltativo	Filtra per stato di invio.
`limit`	Integer	Facoltativo	Dimensione pagina da 1 a 100; default 50.
`cursor`	Integer	Facoltativo	Usa paging.next_cursor per recuperare messaggi più vecchi.

Esempio di richiesta

CURL

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

Esempio di risposta

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}}

Vuoi eseguire questa richiesta?Collegare il tasto API nella parte superiore della pagina per sbloccare il tester interattivo.

Collegare la chiave

Buono a sapersi

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 significa che Telegram ha accettato il messaggio dall'account connesso; la consegna al destinatario e le ricevute di lettura non vengono riportate.
unknown significa che l'esito dell'invio non ha potuto essere confermato. Non reinviare automaticamente un messaggio in questo stato.

OTTENERE

Download a sent Telegram attachment

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

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

Quando usarlo

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

Parametri

Nome	Tipo	Requisito	Descrizione
`message_id`	Integer	Necessario	Message ID returned by /telegram/send/.

Esempio di richiesta

CURL

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

Esempio di risposta

JSON

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

Vuoi eseguire questa richiesta?Collegare il tasto API nella parte superiore della pagina per sbloccare il tester interattivo.

Collegare la chiave

Buono a sapersi

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.

Risoluzione dei problemi

Errori e ritiri sicuri

Leggi lo stato HTTP e il campo di errore JSON prima di riprovare. Non riprovare i guasti di convalida o di autenticazione senza correggere prima la richiesta.

HTTP	Codice	Cosa fare
401	`api_key_required / invalid_api_key`	Invia un header X-SMSMobileAPI-Key valido.
402	`subscription_expired`	Renew the SMSMobileAPI subscription linked to the API key. Telegram API access resumes after renewal.
403	`API_ENDPOINT_DISABLED`	Abilita lo Telegram API o questo specifico endpoint in My API Key.
404	`contact_not_found`	Sincronizza i contatti e usa un ID dalla tua connessione Telegram.
409	`telegram_not_connected / idempotency_conflict`	Connetti Telegram o scegli una nuova chiave di idempotenza per contenuti modificati.
422	`invalid_message / invalid_pagination`	Correggi il messaggio, l'ID contatto o i parametri di paginazione.
429	`queue_full / rate_limited`	Attendi che le code di invio o il limite per minuto si liberino.
503	`sending_unavailable / service_unavailable`	Il worker di invio o lo storage sono temporaneamente non disponibili; riprova più tardi.
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.

Regola di riprovaRecuperare solo risposte transitorie 429 e 5xxx. Inizia dopo 1 secondo, poi torna a 2, 4 e 8 secondi.

Hai bisogno di aiuto?

Portare il contesto della richiesta, non i tuoi segreti.

Condividi il punto finale, timestamp, stato HTTP e risposta igienica. Non includere mai chiavi API, gettoni o contenuti di messaggi privati.

Contatto API supporto →

L'app mobile SMSMobileAPI sicura che collega un telefono al cruscotto web e REST API per operazioni SMS e chiamate — Connessione crittografata mobile-to-piattaforma

Applicazione mobile ufficiale

Il ponte sicuro tra il telefono, il cruscotto e API.

Le operazioni SMS e di chiamata passano attraverso l'app ufficiale SMSMobileAPI installata sul telefono connesso. L'applicazione si abbina in modo sicuro al dispositivo con il tuo account, sincronizza eventi autorizzati e collega la rete mobile al cruscotto e REST API.

1App mobileCoppia il telefono e la sua SIM 2Link crittografatoAutentichezza e protegge i dati in transito 3Dashboard & APIControlli flussi di lavoro e attività

Comunicati firmati distribuiti attraverso gli elenchi ufficiali di Google Play e Apple App Store
Controllo di Google e Apple piattaforma, controllo di firma e distribuzione
Accoppiamento sicuro del dispositivo, trasporto HTTPS e accesso autenticato API
Solo le autorizzazioni richieste per le funzionalità mobili che abilitate

Ottenere l'applicazione ufficiale SMSMobileAPI su Google Play

Scarica l'app ufficiale SMSMobileAPI sull'App Store Apple

Le capacità dipendono dalle autorizzazioni e dall'accesso di sfondo consentito da Android o iOS.

Documentazione Telegram API

La vostra prima richiesta in quattro passi

Collegare

Trova un contatto

Inviare

Traccia

Mantenere le credenziali sul server

Parametri

Esempio di richiesta

Esempio di risposta

Parametri

Esempio di richiesta

Esempio di risposta

Parametri

Esempio di richiesta

Esempio di risposta

Parametri

Esempio di richiesta

Esempio di risposta

Parametri

Esempio di richiesta

Esempio di risposta

Parametri

Esempio di richiesta

Esempio di risposta

Errori e ritiri sicuri

Portare il contesto della richiesta, non i tuoi segreti.

Il ponte sicuro tra il telefono, il cruscotto e API.