--- title: "API SMS Cookbook" description: "Scopri come utilizzare l'API SMS di OVHcloud: invio in tempo reale e massivo, mailing, monitoraggio delle campagne, risposta via SMS, gestione di utenti e crediti" url: https://docs.ovhcloud.com/it/guides/web-cloud/messaging/sms/api-sms-cookbook lang: it lastUpdated: 2026-06-15 --- # 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: [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) ServiceName corrisponde al tuo account SMS. Puoi recuperarlo dal tuo Spazio Cliente o effettuando una chiamata GET al metodo seguente: [🇪🇺GET/sms](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms) 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: [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) 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`: [🇪🇺POST/sms/{serviceName}/receivers](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/receivers) Una volta caricato il file, basta chiamare di nuovo il metodo jobs con il parametro `receiversSlotId`, indicando il SlotId corretto: [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) ## 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 ```csv number ;lastname ;firstname ;address 0662000000 ;Durant ;Pierre ;xx rue montaigne Paris 0662000001 ;Dupont ;Jean ;xx rue montaigne Paris ... ``` Il messaggio: ```text 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`: [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) 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: [🇪🇺GET/sms/{serviceName}/outgoing](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/outgoing) Per recuperare tutti i dettagli di ogni messaggio, utilizza: [🇪🇺GET/sms/{serviceName}/outgoing/{id}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/outgoing/-id-) 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: [🇪🇺GET/sms/{serviceName}/blacklists](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/blacklists) ## Risposta via SMS :::info La risposta via SMS (numero breve tramite `senderForResponse`) è disponibile solo in Francia. ::: 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: [🇪🇺PUT/sms/{serviceName}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#put-/sms/-serviceName-) Con un approccio `Pull`, puoi scegliere di consultare le risposte ricevute chiamando il metodo seguente: [🇪🇺GET/sms/{serviceName}/incoming](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/incoming) ## 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: [🇪🇺POST/order/sms/{serviceName}/credits](https://eu.api.ovh.com/console/?section=/order&branch=v1#post-/order/sms/-serviceName-/credits) 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: [🇪🇺GET/order/sms/{serviceName}/credits](https://eu.api.ovh.com/console/?section=/order&branch=v1#get-/order/sms/-serviceName-/credits) ## 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: [🇪🇺POST/sms/{serviceName}/users](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/users) Poi configurare le sue impostazioni (callback, quota, IP, ecc.): [🇪🇺PUT/sms/{serviceName}/users/{login}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#put-/sms/-serviceName-/users/-login-) Infine, puoi consultare lo stato di consumo di un utente: [🇪🇺GET/sms/{serviceName}/users/{login}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/users/-login-) 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: [🇪🇺GET/sms/{serviceName}/outgoing](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/outgoing) ## 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: [🇪🇺POST/sms/{serviceName}/transferCredits](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/transferCredits) 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](https://community.ovhcloud.com/).