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

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 è una tecnologia all'avanguardia per le comunicazioni aziendali che consente agli sviluppatori di incorporare funzionalità voce, VoIP e di messaggistica nelle applicazioni. Consente di virtualizzare tutta l'infrastruttura necessaria in un ambiente globale basato su cloud, esponendolo attraverso la piattaforma API per le comunicazioni Twilio. Le applicazioni sono scalabili e facili da compilare. Offre flessibilità, grazie a un modello di prezzi con pagamento al consumo, e l'affidabilità del cloud.

Twilio Voice consente alle applicazioni di effettuare e ricevere chiamate telefoniche. Twilio SMS consente alle applicazioni di inviare e ricevere messaggi di testo. Twilio Client consente di effettuare chiamate VoIP da qualsiasi telefono, tablet o browser e supporta WebRTC.

Prezzi e offerte speciali di Twilio

I clienti di Azure ricevono un'offerta speciale: $ 10 di credito Twilio quando si esegue l'aggiornamento dell'account Twilio. Il credito Twilio può essere applicato a qualsiasi utilizzo di Twilio ($ 10 di credito equivalgono all'invio di 1.000 SMS o a 1.000 minuti voce per le chiamate in entrata, a seconda della località del numero di telefono, del messaggio o della destinazione della chiamata). Riscattare il credito Twilio e iniziare a usare il servizio.

Twilio è un servizio con pagamento in base al consumo. Non prevede spese iniziali ed è possibile chiudere l'account in qualsiasi momento. Per altre informazioni, vedere la pagina Twilio Pricing (Prezzi di Twilio).

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. Per altre informazioni su altri verbi e funzionalità, vedere la documentazione relativa al linguaggio di markup Twilio.

  • <Dial>: connette il chiamante a un altro telefono.
  • <Gather>: raccoglie i numeri digitati sulla tastiera del telefono.
  • <Hangup>: termina una chiamata.
  • <Pause>: attende in modo silenzioso per un numero di secondi specificato.
  • <Play>: riproduce un file audio.
  • <Queue>: aggiunge l'elemento a una coda di chiamanti.
  • <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 .

<?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 generare le risposte TwiML. In alternativa, usare 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 relativa alla registrazione gratuita di 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 riceveranno il SID 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. Il SID dell'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 Python

Un'applicazione Python che usa il servizio Twilio e viene eseguita in Azure non è diversa da qualsiasi altra applicazione Python che usa il servizio Twilio. Benché i servizi Twilio siano basati su REST e possano essere chiamati da Python in diversi modi, questo articolo illustra solo come usare i servizi Twilio con la libreria Twilio per Python da GitHub. Per altre informazioni sull'uso della libreria Twilio per Python, vedere http://readthedocs.org/docs/twilio-python/en/latest/index.html.

In primo luogo, [configurare una nuova macchina virtuale Linux in Azure][azure_vm_setup] che funga da host per la nuova applicazione Web Python. Quando la macchina virtuale è in esecuzione, è necessario esporla su una porta pubblica, come descritto di seguito.

Aggiungere una regola in ingresso

  1. Passare alla pagina [Gruppo di sicurezza di rete][azure_nsg].
  2. Selezionare il gruppo di sicurezza di rete corrispondente alla macchina virtuale.
  3. Aggiungere una Regola in uscita per la porta 80. Verificare di consentire l'ingresso da qualsiasi indirizzo.

Impostare l'etichetta del nome DNS

  1. Passare alla pagina [Indirizzi IP pubblici][azure_ips].
  2. Selezionare l'indirizzo IP corrispondente alla macchina virtuale.
  3. Impostare Etichetta del nome DNS nella sezione Configurazione. Nel caso di questo esempio, verrà visualizzata una dicitura simile a etichetta-dominio.centralus.cloudapp.azure.com.

Quando si è in grado di connettersi alla macchina virtuale tramite SSH, è possibile installare il framework Web scelto. In Python i due framework più noti sono Flask e Django. Per installarne uno è sufficiente eseguire il comando pip install.

Tenere presente che la macchina virtuale è stata configurata per consentire il traffico solo sulla porta 80. Di conseguenza, verificare di configurare l'applicazione per l'uso di questa porta.

Configurare l'applicazione per l'uso delle librerie Twilio

È possibile configurare l'applicazione per l'uso della libreria Twilio per Python in due modi:

  • Installare la libreria Twilio per Python come pacchetto Pip. È possibile eseguire l'installazione tramite i comandi seguenti:

      $ pip install twilio
    

    -OPPURE-

  • Scaricare la libreria Twilio per Python da GitHub (https://github.com/twilio/twilio-python) e installarla nel modo seguente:

      $ python setup.py install
    

Dopo avere installato la libreria Twilio per Python, è possibile usare il comando import per importarla nei file Python:

    import twilio

Per altre informazioni, vedere https://github.com/twilio/twilio-python/blob/master/README.md.

Procedura: Effettuare una chiamata in uscita

Di seguito è illustrato come effettuare una chiamata in uscita. 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.

from urllib.parse import urlencode

# Import the Twilio Python Client.
from twilio.rest import TwilioRestClient

# Set your account ID and authentication token.
account_sid = "your_twilio_account_sid"
auth_token = "your_twilio_authentication_token"

# The number of the phone initiating the the call.
# This should either be a Twilio number or a number that you've verified
from_number = "NNNNNNNNNNN"

# The number of the phone receiving call.
to_number = "NNNNNNNNNNN"

# Use the Twilio-provided site for the TwiML response.
url = "http://twimlets.com/message?"

# The phone message text.
message = "Hello world."

# Initialize the Twilio client.
client = TwilioRestClient(account_sid, auth_token)

# Make the call.
call = client.calls.create(to=to_number,
                           from_=from_number,
                           url=url + urlencode({'Message': message}))
print(call.sid)

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 Come fornire risposte TwiML dal proprio sito Web.

Procedura: Inviare un messaggio SMS

La schermata seguente mostra come inviare un messaggio SMS tramite la classe TwilioRestClient. Il numero riportato in from_number per l'invio di messaggi SMS con gli account di valutazione è fornito da Twilio. Il numero riportato in to_number deve essere verificato per l'account Twilio prima di eseguire il codice.

# Import the Twilio Python Client.
from twilio.rest import TwilioRestClient

# Set your account ID and authentication token.
account_sid = "your_twilio_account_sid"
auth_token = "your_twilio_authentication_token"

from_number = "NNNNNNNNNNN"  # With trial account, texts can only be sent from your Twilio number.
to_number = "NNNNNNNNNNN"
message = "Hello world."

# Initialize the Twilio client.
client = TwilioRestClient(account_sid, auth_token)

# Send the SMS message.
message = client.messages.create(to=to_number,
                                 from_=from_number,
                                 body=message)

Procedura: Fornire risposte TwiML dal proprio sito Web

Quando l'applicazione avvia una chiamata all'API Twilio, 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 è stato progettato per essere usato da Twilio, è possibile visualizzarlo 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 per visualizzare un elemento <Response> contenente un elemento <Say>.

Anziché utilizzare l'URL fornito da Twilio, è possibile creare un sito personalizzato che restituisce risposte HTTP. È possibile creare il sito in qualsiasi linguaggio che restituisca risposte XML. In questo argomento si presuppone che per la creazione di TwiML venga usato Python.

Negli esempi seguenti viene generata una risposta TwiML Hello World nella chiamata.

Con Flask:

from flask import Response
@app.route("/")
def hello():
    xml = '<Response><Say>Hello world.</Say></Response>'
    return Response(xml, mimetype='text/xml')

Con Django:

from django.http import HttpResponse
def hello(request):
    xml = '<Response><Say>Hello world.</Say></Response>'
    return HttpResponse(xml, content_type='text/xml')

Come si evince dal codice riportato sopra, la risposta TwiML è semplicemente un documento XML. La libreria Twilio per Python contiene le classi che consentono di generare automaticamente le istruzioni TwiML. Nell'esempio seguente viene generata la stessa risposta descritta sopra, ma usando il modulo twiml nella libreria Twilio per Python:

from twilio import twiml

response = twiml.Response()
response.say("Hello world.")
print(str(response))

Per altre informazioni su TwiML, vedere https://www.twilio.com/docs/api/twiml.

Dopo aver configurato l'applicazione Python in modo da fornire risposte TwiML, usare l'URL di tale applicazione come URL trasmesso nel metodo client.calls.create. Se, ad esempio, si dispone di un'applicazione Web denominata MyTwiML distribuita in un servizio ospitato in Azure, è possibile usare il relativo URL come webhook, come mostrato nell'esempio seguente:

from twilio.rest import TwilioRestClient

account_sid = "your_twilio_account_sid"
auth_token = "your_twilio_authentication_token"
from_number = "NNNNNNNNNNN"
to_number = "NNNNNNNNNNN"
url = "http://your-domain-label.centralus.cloudapp.azure.com/MyTwiML/"

# Initialize the Twilio client.
client = TwilioRestClient(account_sid, auth_token)

# Make the call.
call = client.calls.create(to=to_number,
                           from_=from_number,
                           url=url)
print(call.sid)

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

A questo punto, dopo aver appreso le nozioni di base del servizio Twilio, usare i collegamenti seguenti per altre informazioni: