Come usare Twilio per le funzionalità voce ed SMS in Java

In questa guida viene illustrato come eseguire attività di programmazione comuni con il servizio API Twilio in Azure. Gli scenari presentati includono la composizione di una chiamata telefonica e l'invio di un messaggio SMS (Short Message Service). Per altre informazioni su Twilio e sull'utilizzo delle funzionalità voce ed SMS nelle applicazioni, vedere la sezione Passaggi successivi .

Informazioni su Twilio

Twilio è un'API per servizi Web di telefonia che consente di usare le competenze e i linguaggi Web esistenti per sviluppare applicazioni SMS e vocali. Twilio è un servizio di terze parti. Non si tratta di una funzionalità di Azure, né di un prodotto Microsoft.

Twilio Voice consente alle applicazioni di effettuare e ricevere chiamate telefoniche. Twilio SMS consente alle applicazioni di inviare e ricevere SMS. Twilio Client consente alle applicazioni di abilitare le comunicazioni vocali utilizzando le connessioni Internet esistenti, comprese le connessioni mobili.

Prezzi e offerte speciali di Twilio

Per altre informazioni, vedere la pagina Twilio Pricing (Prezzi di Twilio). Per i clienti di Azure è disponibile un'offerta speciale: un credito gratuito per 1000 SMS o 1000 minuti di connessioni in entrata. Per avvalersi dell'offerta o per altre informazioni, visitare il sito Web all'indirizzo http://ahoy.twilio.com/azure.

Concetti

L'API Twilio è un'API RESTful che fornisce funzionalità voce ed SMS per le applicazioni. Le librerie client sono disponibili in più lingue. Per un elenco, vedere Twilio API Libraries (Librerie dell'API Twilio).

I concetti principali dell'API Twilio sono costituiti dai verbi Twilio e dal linguaggio di markup Twilio (Twilio Markup Language, TwiML).

Verbi Twilio

Nell'API vengono usati i verbi di Twilio: il verbo <Say>, ad esempio, indica a Twilio di recapitare un messaggio acustico in una chiamata.

Di seguito è riportato un elenco dei verbi Twilio.

  • <Dial>: connette il chiamante a un altro telefono.
  • <Gather>: raccoglie i numeri digitati sulla tastiera del telefono.
  • <Hangup>: termina una chiamata.
  • <Play>: riproduce un file audio.
  • <Queue>: aggiunge l'elemento a una coda di chiamanti.
  • <Pause>: attende in modo silenzioso per un numero di secondi specificato.
  • <Record>: registra la voce del chiamante e restituisce l'URL del file contenente la registrazione.
  • <Redirect>: trasferisce il controllo di una chiamata o di un SMS al codice TwiML presso un URL diverso.
  • <Reject>: rifiuta una chiamata in arrivo al numero Twilio senza alcun addebito.
  • <Say>: effettua la sintesi vocale del testo durante una chiamata.
  • <Sms>: invia un SMS.

TwiML

TwiML è un set di istruzioni basate su XML e sui verbi Twilio che indicano a Twilio come elaborare una chiamata o un SMS.

Ad esempio, il codice TwiML seguente effettua la sintesi vocale del testo Hello World! sintesi vocale.

    <?xml version="1.0" encoding="UTF-8" ?>
    <Response>
       <Say>Hello World!</Say>
    </Response>

Quando l'applicazione chiama l'API Twilio, uno dei parametri dell'API è l'URL che restituisce la risposta TwiML. Ai fini dello sviluppo, è possibile utilizzare gli URL offerti da Twilio per fornire le risposte TwiML utilizzate dalle applicazioni. È inoltre possibile ospitare gli URL per produrre le risposte TwiML oppure utilizzare l'oggetto TwiMLResponse .

Per altre informazioni sui verbi Twilio, i relativi attributi e il codice TwiML, vedere TwiML. Per altre informazioni sull'API Twilio, vedere Twilio API (API Twilio).

Creare un account Twilio

Se si desidera creare un account Twilio, iscriversi nella pagina Try Twilio (Provare Twilio). È possibile iniziare con un account gratuito ed eseguire l'aggiornamento in un secondo momento.

Quando si effettua l'iscrizione a un account Twilio, si riceverà un ID account e un token di autenticazione. Entrambe queste informazioni sono necessarie per effettuare chiamate all'API Twilio. Per prevenire accessi autorizzati all'account, conservare il token di autenticazione in un luogo sicuro. L'ID account e il token di autorizzazione sono visualizzabili nella console di Twilio, rispettivamente nei campi ACCOUNT SID (SID ACCOUNT) e AUTH TOKEN (TOKEN AUTORIZZAZIONE).

Creare un'applicazione Java

  1. Ottenere il file JAR di Twilio e aggiungerlo al percorso di compilazione Java e all'assembly di distribuzione del file WAR. Dall'indirizzo https://github.com/twilio/twilio-java è possibile scaricare i file di origine disponibili in GitHub e creare un file JAR personalizzato o scaricarne uno precompilato, con o senza dipendenze.
  2. Verificare che l'archivio chiavi cacerts del JDK contenga il certificato Equifax Secure Certificate Authority con ID digitale MD5 67:CB:9D:C0:13:24:8A:82:9B:B2:17:1E:D1:1B:EC:D4 (il numero di serie è 35:DE:F4:CF e l'ID digitale SHA1 è D2:32:09:AD:23:D3:14:23:21:74:E4:0D:7F:9D:62:13:97:86:63:3A). Si tratta del certificato dell'Autorità di certificazione (CA) per il servizio https://api.twilio.com, che viene chiamato quando si usano le API Twilio. Per informazioni su come verificare che l'archivio chiavi cacerts del JDK contenga il certificato CA corretto, vedere Aggiunta di un certificato all'archivio certificati CA Java.

Per istruzioni dettagliate sull'uso della libreria client Twilio per Java, vedere Come effettuare una chiamata tramite Twilio in un'applicazione Java in Azure.

Configurare l'applicazione per l'uso delle librerie Twilio

All'interno del codice è possibile aggiungere istruzioni import nella parte superiore dei file di origine per i pacchetti o le classi Twilio da utilizzare nell'applicazione.

Per i file di origine Java:

    import com.twilio.*;
    import com.twilio.rest.api.*;
    import com.twilio.type.*;
    import com.twilio.twiml.*;

Per i file di origine JSP (Java Server Page):

    import="com.twilio.*"
    import="com.twilio.rest.api.*"
    import="com.twilio.type.*"
    import="com.twilio.twiml.*"

Le istruzioni import possono variare in base ai pacchetti o alle classi Twilio che si desidera utilizzare.

Procedura: Effettuare una chiamata in uscita

Di seguito è illustrato come effettuare una chiamata in uscita usando la classe Call. Questo codice utilizza inoltre un sito fornito da Twilio per restituire la risposta TwiML (Twilio Markup Language). Sostituire i valori di from_number e to_number relativi ai numeri di telefono e, prima di eseguire il codice, verificare il numero di telefono specificato in from_number per l'account Twilio.

    // Use your account SID and authentication token instead
    // of the placeholders shown here.
    String accountSID = "your_twilio_account_SID";
    String authToken = "your_twilio_authentication_token";

    // Initialize the Twilio client.
    Twilio.init(accountSID, authToken);

    // Use the Twilio-provided site for the TwiML response.
    URI uri = new URI("http://twimlets.com/message" +
            "?Message%5B0%5D=Hello%20World%21");

    // Declare To and From numbers
    PhoneNumber to = new PhoneNumber("NNNNNNNNNN");
    PhoneNumber from = new PhoneNumber("NNNNNNNNNN");

    // Create a Call creator passing From, To and URL values
    // then make the call by executing the create() method
    Call.creator(to, from, uri).create();

Per altre informazioni sui parametri passati al metodo Call.creator, vedere http://www.twilio.com/docs/api/rest/making-calls.

Come indicato in precedenza, questo codice utilizza un sito fornito da Twilio per restituire la risposta TwiML. Per fornire la risposta TwiML è inoltre possibile usare il proprio sito. Per altre informazioni, vedere Procedura per fornire risposte TwiML in un'applicazione Java in Azure.

Procedura: Inviare un messaggio SMS

La schermata seguente mostra come inviare un messaggio SMS usando la classe Message. Il numero riportato in from_number, 4155992671, è fornito da Twilio per l'invio di messaggi SMS con gli account di valutazione. Il numero riportato in to_number deve essere verificato per l'account Twilio prima dell'esecuzione del codice.

    // Use your account SID and authentication token instead
    // of the placeholders shown here.
    String accountSID = "your_twilio_account_SID";
    String authToken = "your_twilio_authentication_token";

    // Initialize the Twilio client.
    Twilio.init(accountSID, authToken);

    // Declare To and From numbers and the Body of the SMS message
    PhoneNumber to = new PhoneNumber("+14159352345"); // Replace with a valid phone number for your account.
    PhoneNumber from = new PhoneNumber("+14158141829"); // Replace with a valid phone number for your account.
    String body = "Where's Wallace?";

    // Create a Message creator passing From, To and Body values
    // then send the SMS message by calling the create() method
    Message sms = Message.creator(to, from, body).create();

Per altre informazioni sui parametri passati al metodo Message.creator, vedere http://www.twilio.com/docs/api/rest/sending-sms.

Procedura: Fornire risposte TwiML dal proprio sito Web

Quando l'applicazione avvia una chiamata all'API Twilio, ad esempio tramite il metodo CallCreator.create, Twilio invia la richiesta a un URL che deve restituire una risposta TwiML. Nell'esempio precedente viene usato l'URL fornito da Twilio http://twimlets.com/message. Poiché TwiML è progettato per essere usato da servizi Web, è possibile visualizzare il codice TwiML nel browser. Ad esempio, fare clic su http://twimlets.com/message per visualizzare un elemento <Response> vuoto oppure fare clic su http://twimlets.com/message?Message%5B0%5D=Hello%20World%21 per visualizzare un elemento <Response> contenente un elemento <Say>.

Anziché utilizzare l'URL fornito da Twilio, è possibile creare un sito Web personalizzato che restituisce risposte HTTP. È possibile creare il sito in qualsiasi linguaggio che restituisca risposte XML. In questo argomento si presuppone che l'URL sarà ospitato in una pagina JSP.

La pagina JSP seguente genera una risposta TwiML Hello World! nella chiamata.

    <%@ page contentType="text/xml" %>
    <Response>
        <Say>Hello World!</Say>
    </Response>

La pagina JSP seguente crea una risposta TwiML che pronuncia del testo, contiene diverse pause e pronuncia informazioni sulla versione dell'API Twilio e sul nome del ruolo di Azure.

    <%@ page contentType="text/xml" %>
    <Response>
        <Say>Hello from Azure!</Say>
        <Pause></Pause>
        <Say>The Twilio API version is <%= request.getParameter("ApiVersion") %>.</Say>
        <Say>The Azure role name is <%= System.getenv("RoleName") %>.</Say>
        <Pause></Pause>
        <Say>Good bye.</Say>
    </Response>

Il parametro ApiVersion è disponibile nelle richieste vocali Twilio, non nelle richieste SMS. Per visualizzare i parametri di richiesta disponibili per le richieste vocali e SMS di Twilio, vedere rispettivamente https://www.twilio.com/docs/api/twiml/twilio_request e https://www.twilio.com/docs/api/twiml/sms/twilio_request. La variabile di ambiente RoleName è disponibile come parte di una distribuzione Azure. Se si vuole aggiungere variabili di ambiente personalizzate in modo che possano essere recuperate da System.getenv, vedere la sezione relativa alle variabili di ambiente in Impostazioni varie di configurazione dei ruoli.

Dopo aver configurato la pagina JSP in modo che vengano fornite risposte TwiML, usare l'URL della pagina JSP come URL passato nel metodo Call.creator. Se, ad esempio, si dispone di un'applicazione Web denominata MyTwiML distribuita in un servizio ospitato in Azure e il nome della pagina JSP è mytwiml.jsp, è possibile passare l'URL a Call.creator come illustrato nell'esempio di codice seguente:

    // Declare To and From numbers and the URL of your JSP page
    PhoneNumber to = new PhoneNumber("NNNNNNNNNN");
    PhoneNumber from = new PhoneNumber("NNNNNNNNNN");
    URI uri = new URI("http://<your_hosted_service>.cloudapp.net/MyTwiML/mytwiml.jsp");

    // Create a Call creator passing From, To and URL values
    // then make the call by executing the create() method
    Call.creator(to, from, uri).create();

Un'altra possibilità per rispondere con TwiML consiste nell'usare la classe VoiceResponse, disponibile nel pacchetto com.twilio.twiml.

Per altre informazioni sull'uso di Twilio in Azure con Java, vedere Come effettuare una chiamata tramite Twilio in un'applicazione Java in Azure.

Procedura: Utilizzare servizi Twilio aggiuntivi

Oltre agli esempi illustrati in questa pagina, Twilio offre API basate su Web che è possibile utilizzare per sfruttare altre funzionalità di Twilio dall'applicazione Azure. Per informazioni dettagliate, vedere la documentazione sull'API Twilio.

Passaggi successivi

Dopo aver appreso le nozioni di base sul servizio Twilio, utilizzare i collegamenti seguenti per ulteriori informazioni: