Prima dell’invio
Invia un SMS o un MMS supportato utilizzando un numero mittente configurato per il tuo account. È un’operazione in produzione che può contattare i destinatari e generare addebiti. Utilizza solo destinatari autorizzati e traffico approvato; i numeri e il riferimento dell’esempio seguente sono fittizi.
Il tuo account deve essere approvato per la messaggistica in uscita e disporre delle autorizzazioni applicabili a mittente, paese e traffico. Le credenziali dirette degli utenti Personal/Consumer non sono ammesse per questa API. Le credenziali API dedicate e approvate seguono un percorso di ammissione separato; i mittenti mobili P2P possono richiedere ulteriori autorizzazioni P2P e per Stati Uniti/Canada. Verifica con MultiTEL la corretta configurazione dell’account, senza considerare una credenziale API come un’autorizzazione automatica a inviare qualsiasi tipo di traffico.
Richiesta di invio
Autenticati tramite HTTPS con un account API abilitato, dal relativo indirizzo IP di origine consentito. Conserva le credenziali in un archivio di segreti lato server. Utilizza POST con campi codificati come modulo oppure un oggetto JSON quando non vengono forniti campi di modulo o di query. Non inserire credenziali o testo dei messaggi in un URL.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| Campo | Obbligatorio | Significato |
|---|---|---|
| from | Sì | Il numero mittente configurato per il tuo account, preferibilmente con tutte le cifre del numero internazionale. |
| to | Sì | Una destinazione, più destinazioni separate da virgole oppure un array JSON. È preferibile utilizzare tutte le cifre dei numeri internazionali. Una richiesta di gruppo può essere rifiutata in base ai limiti P2P o nazionali applicabili; questa non è un’API per invii massivi senza restrizioni. |
| text | Per gli SMS | Testo del messaggio in UTF-8. È necessario fornire almeno del testo non vuoto oppure contenuti multimediali. Invia caratteri effettivi e interruzioni di riga, anziché HTML o testo con codifica percentuale. Alcuni percorsi degli operatori normalizzano le sequenze di escape presenti come testo letterale. |
| media | Per gli MMS con soli contenuti multimediali | Contenuti multimediali codificati in Base64, non un URL o un percorso di file. La disponibilità degli MMS, il formato e le dimensioni dipendono dal percorso configurato. Verifica con MultiTEL quali contenuti multimediali sono supportati; questo gestore non stabilisce un limite universale alle dimensioni dei contenuti multimediali. |
| reference | Consigliato | La tua etichetta di correlazione, conservata nei record e nei callback. Includine una per agevolare la risoluzione dei problemi. Non è una chiave di idempotenza. |
| notifyurl | No | Il tuo endpoint HTTPS per la ricezione dei callback. Il gestore può inviare un risultato iniziale tramite POST dopo l’elaborazione. Deve essere un endpoint sotto il tuo controllo e non deve essere un URL di un servizio interno. |
Per un array JSON, utilizza un vero array in to; non inserire una stringa contenente un array JSON in un campo di modulo. Utilizza l’invio a un singolo destinatario come prova iniziale dell’integrazione. Il supporto per i gruppi e per gli MMS varia a seconda del percorso: verifica quindi la combinazione supportata prima di utilizzarli.
Leggere il risultato completo
Sono mostrati solo alcuni campi a scopo illustrativo; il costo visualizzato non è un preventivo.
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}Controlla insieme lo stato HTTP, il campo JSON status.code e i campi status/message della risposta. I codici di risultato possono essere stringhe. Conserva sms_log_id_ori e i valori restituiti per messaggio e riferimento, per consentire all’assistenza di correlare i dati. I valori legacy uniqueid e pid variano a seconda del percorso; non dedurne il formato e non presumere che siano token di idempotenza del client.
Success o Message queued indica normalmente l’accettazione da parte del percorso selezionato, non la ricezione sul telefono di una persona. Uno stato del callback iniziale come sent non dimostra da solo la consegna finale.
Segmenti e addebiti
Utilizza Analisi della lunghezza degli SMS sul testo finale completo prima dell’invio. I prezzi degli SMS dipendono dalla destinazione e dal servizio dell’account; le commissioni applicabili degli operatori vengono aggiunte per ogni segmento. Il percorso di invio somma i prezzi relativi ai destinatari e le commissioni applicabili, quindi moltiplica il risultato per il numero calcolato di segmenti SMS. Ai fini di questo calcolo, una richiesta MMS viene considerata come un solo messaggio.
cost e permsg sono stringhe monetarie formattate nella risposta legacy. carrier_fee_usd riporta la componente delle commissioni dell’operatore in USD ed è già inclusa nel totale di invio calcolato; non aggiungerla una seconda volta. Occorre verificare le tariffe effettive e la disponibilità dei percorsi per il tuo account. La richiesta non è un’operazione che si limita a ottenere un prezzo.
Il codice esaminato effettua l’addebito dopo il completamento con esito positivo del percorso di invio all’operatore, ma l’accettazione da parte dell’operatore, la memorizzazione persistente locale e la fatturazione non costituiscono un’unica transazione. Un errore o un timeout può verificarsi dopo che una richiesta a monte è stata accettata. Non viene esposta alcuna chiave di idempotenza del client: ripetere lo stesso riferimento può causare un nuovo invio e un nuovo addebito.
Consegna locale e risultati misti
I numeri ospitati localmente possono essere ammessi, con stato accepted, nel flusso di messaggistica in entrata di MultiTEL senza un invio tramite un operatore esterno. Per una richiesta interamente locale, la risposta può includere accepted, message_id, provider e delivery_status. L’accettazione locale non garantisce che la destinazione di inoltro configurata dal destinatario abbia funzionato.
Esamina local_delivery_results e partial quando sono presenti. Un destinatario può mostrare accepted con valore true anche se l’inoltro non è riuscito. Una richiesta mista può avere destinatari presso operatori con stato accepted e una parte locale non riuscita. Non ripetere automaticamente l’intero invio in blocco: verifica prima l’esito per ciascun destinatario.
In questo percorso, l’accettazione interamente locale riporta un costo in uscita pari a zero, mentre ai destinatari possono comunque essere applicati i normali addebiti per la messaggistica in entrata. Non interpretare un costo in uscita pari a zero come una garanzia che nessun account riceva addebiti.
Callback e correlazione
Quando viene fornito notifyurl, il callback iniziale contiene una struttura esterna status e campi di risposta che includono message_id, reference, from, to, status, status_text, error_code, timestamp e accepted. Possono essere presenti anche risultati locali. Conserva le informazioni di correlazione senza registrare nei log le credenziali API o contenuti dei messaggi non necessari.
Questo gestore non aggiunge un campo di firma al callback iniziale. Non utilizzare un callback non verificato come unica autorizzazione per un’altra azione. Consulta la configurazione di integrazione/webhook supportata per il tuo account e chiarisci gli esiti incerti confrontandoli con i record del portale o rivolgendoti all’assistenza. Non presumere che i callback arrivino una sola volta o nell’ordine delle consegne finali.
Errori e recupero sicuro
Gli errori di convalida possono utilizzare il codice API 403. I rifiuti dovuti all’approvazione dell’account o alle regole P2P e nazionali possono anche impostare HTTP 403 e includere un campo response.code leggibile dalle macchine. I limiti di frequenza possono utilizzare 429 con informazioni per un nuovo tentativo. L’indisponibilità di una regola o un errore di invio o di memorizzazione persistente locale può utilizzare 503 o 500; anche la gestione legacy del saldo insufficiente può restituire 500.
In caso di 429, rispetta Retry-After e l’eventuale valore di response.retry_after. In caso di rifiuto relativo ad account, mittente, paese o destinatario, correggi la causa prima di riprovare. In caso di timeout o di esito dell’invio poco chiaro, conserva l’ora della richiesta, il riferimento e gli identificatori restituiti, controlla il portale e contatta l’assistenza prima di inviare nuovamente. L’assenza di una voce nel registro, da sola, non dimostra che nessun operatore abbia accettato la richiesta.