API SMS Cookbook

Obiettivo

Scopri come utilizzare le diverse combinazioni possibili con l'API per la piattaforma SMS di OVHcloud.

Invio di SMS in tempo reale

L'invio di SMS in tempo reale corrisponde a una chiamata al servizio web per inviare regolarmente SMS uno per uno. Per ogni SMS da inviare effettuiamo quindi una chiamata al servizio web in POST al metodo seguente:

ServiceName corrisponde al tuo account SMS. Puoi recuperarlo dal tuo Spazio Cliente o effettuando una chiamata GET al metodo seguente:

Ecco un esempio: /sms/sms-XXXXXX-1/jobs

Parametri obbligatori:

• ServiceName
• Message (il tuo messaggio; presta attenzione alla sua lunghezza, nonché all'aggiunta dello STOP, alla codifica e ai caratteri speciali, che possono consumare più crediti SMS)

Destinatari:

• Receivers (lista di numeri; per gli SMS in tempo reale è il parametro consigliato con un solo numero)
• receiversDocumentUrl (URL che punta a un file CSV contenente i numeri dei destinatari)
• receiversSlotId (ID che punta a un file CSV precaricato)

Mittente

• sender (selezione del nome del mittente affinché tu sia immediatamente identificato come mittente dell'SMS)
• senderForResponse (utilizzo di un numero breve che consente la risposta via SMS a 2 vie)

Altri

• charset
• class (tipo di SMS inviato)
• coding (codifica su 7 o 8 bit; influisce sul numero di caratteri disponibili per credito SMS)
• differedPeriod (programmazione dell'invio)
• noStopClause (permette di indicare che si tratta di un SMS non commerciale; la dicitura viene rimossa dal messaggio)
• priority (indicazione di priorità)
• tag (contrassegno per categorizzare il messaggio)
• validityPeriod (durata di scadenza del messaggio in caso di problemi di consegna)

Invio massivo

Per inviare uno stesso messaggio a un gran numero di destinatari, riutilizziamo lo stesso metodo POST, ma questa volta importando un file CSV tramite un URL:

Esistono due approcci.

Il primo utilizza direttamente il parametro receiversDocumentUrl (URL che punta a un file CSV contenente i numeri dei destinatari) con il metodo sopra indicato.

Il secondo precarica il file CSV con il metodo seguente, utilizzando i parametri serviceName, csvUrl, description e slotId:

Una volta caricato il file, basta chiamare di nuovo il metodo jobs con il parametro receiversSlotId, indicando il SlotId corretto:

Mailing

L'invio massivo con mailing si basa sull'invio massivo e sulla creazione di un file di contatti CSV specifico collegato a un messaggio. I messaggi potranno incorporare campi variabili. Richiamando il nome di una colonna, ecco un esempio per illustrare questo caso d'uso:

file contacts.csv

number ;lastname ;firstname ;address
0662000000 ;Durant ;Pierre ;xx rue montaigne Paris
0662000001 ;Dupont ;Jean ;xx rue montaigne Paris
...

Il messaggio:

Hello #firstname# #lastname#, your order will be delivered to the following address: #address#. Best regards.

Monitoraggio delle campagne

Al momento della creazione di un invio tramite il metodo POST jobs, puoi indicare un valore per il parametro tag:

Questo parametro ti permetterà poi di tracciare i messaggi inviati con questo tag.

Per recuperare tutti gli identificativi dei messaggi in uscita, utilizza il metodo seguente indicando il parametro tag come filtro della richiesta:

Per recuperare tutti i dettagli di ogni messaggio, utilizza:

Con queste informazioni, puoi creare report di sintesi per ogni campagna. Ecco alcuni esempi di informazioni: tasso di messaggi consegnati, tasso di errori, tempo di diffusione del messaggio, ecc.

Per seguire l'evoluzione dei tuoi STOP SMS e reagire così se una campagna SMS genera un alto tasso di disiscrizione, utilizza:

Risposta via SMS

Per usufruire delle risposte via SMS, dovrai inviare i tuoi SMS con un numero breve utilizzando il parametro senderForResponse.

Per configurare una chiamata Callback a ogni risposta ricevuta, in modo da essere notificato in tempo reale delle risposte, utilizza il metodo seguente:

Con un approccio Pull, puoi scegliere di consultare le risposte ricevute chiamando il metodo seguente:

Ordine di crediti SMS

Per generare automaticamente ordini di SMS, chiama il metodo seguente con, come parametri, l'account SMS da accreditare e l'importo di crediti che desideri acquistare:

In cambio, riceverai tutte le informazioni sui prezzi, IVA esclusa, IVA inclusa, gli sconti, nonché i contratti e il link all'ordine per effettuare il pagamento.

Preliminarmente, puoi ottenere i prezzi in funzione della quantità desiderata con il metodo seguente:

Gestione degli utenti

Per ogni account SMS, puoi creare utenti che potranno avere i propri invii nonché diverse regole di gestione che permettono in particolare di applicare quote di invio.

Il primo passo è creare un utente:

Poi configurare le sue impostazioni (callback, quota, IP, ecc.):

Infine, puoi consultare lo stato di consumo di un utente:

Puoi anche tracciare il consumo utilizzando un tag campagna o l'identità di un sender tramite il metodo seguente, e specificare un periodo, ad esempio per rifatturare il consumo mese per mese:

Trasferimento di crediti

Se gestisci più account SMS (serviceName: sms-XXXX-1, sms-XXXXX-2, ecc.), puoi trasferire crediti tra i tuoi diversi account. A tal fine, utilizza il metodo seguente, indicando l'account SMS da addebitare, quello da accreditare e infine l'importo di crediti da trasferire:

Questo meccanismo è molto utile per gestire più account SMS in modo indipendente, in particolare per la rivendita a diversi attori. Per isolare gli account, devi configurare Token distinti al fine di isolare i diritti. Questa operazione si effettua al momento della creazione dei tuoi Token applicativi: nei diritti, dovrai specificare esplicitamente che una data applicazione ha diritti solo su un ServiceName specificato negli URL autorizzati.

Per saperne di più

Contatta la nostra Community di utenti.