Skip to content

Latest commit

 

History

History
254 lines (182 loc) · 14.5 KB

partner-twilio-python-how-to-use-voice-sms.md

File metadata and controls

254 lines (182 loc) · 14.5 KB
Raw
title description services documentationcenter author manager editor ms.assetid ms.service ms.workload ms.tgt_pltfrm ms.devlang ms.topic ms.date ms.author
How to Use Twilio for Voice and SMS (Python) | Microsoft Docs
Learn how to make a phone call and send a SMS message with the Twilio API service on Azure. Code samples written in Python.
python
devinrader
twilio
561bc75b-4ac4-40ba-bcba-48e901f27cc3
multiple
na
na
python
article
02/19/2015
MicrosoftHelp@twilio.com

How to Use Twilio for Voice and SMS Capabilities in Python

This guide demonstrates how to perform common programming tasks with the Twilio API service on Azure. The scenarios covered include making a phone call and sending a Short Message Service (SMS) message. For more information on Twilio and using voice and SMS in your applications, see the Next Steps section.

What is Twilio?

Twilio is powering the future of business communications, enabling developers to embed voice, VoIP, and messaging into applications. They virtualize all infrastructure needed in a cloud-based, global environment, exposing it through the Twilio communications API platform. Applications are simple to build and scalable. Enjoy flexibility with pay-as-you go pricing, and benefit from cloud reliability.

Twilio Voice allows your applications to make and receive phone calls. Twilio SMS enables your application to send and receive text messages. Twilio Client allows you to make VoIP calls from any phone, tablet, or browser and supports WebRTC.

Twilio Pricing and Special Offers

Azure customers receive a special offer $10 of Twilio Credit when you upgrade your Twilio Account. This Twilio Credit can be applied to any Twilio usage ($10 credit equivalent to sending as many as 1,000 SMS messages or receiving up to 1000 inbound Voice minutes, depending on the location of your phone number and message or call destination). Redeem this Twilio credit and get started.

Twilio is a pay-as-you-go service. There are no set-up fees and you can close your account at any time. You can find more details at Twilio Pricing.

Concepts

The Twilio API is a RESTful API that provides voice and SMS functionality for applications. Client libraries are available in multiple languages; for a list, see Twilio API Libraries.

Key aspects of the Twilio API are Twilio verbs and Twilio Markup Language (TwiML).

Twilio Verbs

The API makes use of Twilio verbs; for example, the <Say> verb instructs Twilio to audibly deliver a message on a call.

The following is a list of Twilio verbs. Learn about the other verbs and capabilities via Twilio Markup Language documentation.

  • <Dial>: Connects the caller to another phone.
  • <Gather>: Collects numeric digits entered on the telephone keypad.
  • <Hangup>: Ends a call.
  • <Pause>: Waits silently for a specified number of seconds.
  • <Play>: Plays an audio file.
  • <Queue>: Add the to a queue of callers.
  • <Record>: Records the voice of the caller and returns a URL of a file that contains the recording.
  • <Redirect>: Transfers control of a call or SMS to the TwiML at a different URL.
  • <Reject>: Rejects an incoming call to your Twilio number without billing you.
  • <Say>: Converts text to speech that is made on a call.
  • <Sms>: Sends an SMS message.

TwiML

TwiML is a set of XML-based instructions based on the Twilio verbs that inform Twilio of how to process a call or SMS.

As an example, the following TwiML would convert the text Hello World to speech.

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

When your application calls the Twilio API, one of the API parameters is the URL that returns the TwiML response. For development purposes, you can use Twilio-provided URLs to provide the TwiML responses used by your applications. You could also host your own URLs to produce the TwiML responses, and another option is to use the TwiMLResponse object.

For more information about Twilio verbs, their attributes, and TwiML, see TwiML. For additional information about the Twilio API, see Twilio API.

Create a Twilio Account

When you are ready to get a Twilio account, sign up at Try Twilio. You can start with a free account, and upgrade your account later.

When you sign up for a Twilio account, you receive an account SID and an authentication token. Both will be needed to make Twilio API calls. To prevent unauthorized access to your account, keep your authentication token secure. Your account SID and authentication token are viewable in the Twilio Console, in the fields labeled ACCOUNT SID and AUTH TOKEN, respectively.

Create a Python Application

A Python application that uses the Twilio service and is running in Azure is no different than any other Python application that uses the Twilio service. While Twilio services are REST-based and can be called from Python in several ways, this article will focus on how to use Twilio services with Twilio library for Python from GitHub. For more information about using the Twilio library for Python, see http://readthedocs.org/docs/twilio-python/en/latest/index.html.

First, [set-up a new Azure Linux VM][azure_vm_setup] to act as a host for your new Python web application. Once the Virtual Machine is running, you will need to expose your application on a public port as described below.

Add An Incoming Rule

  1. Go to the [Network Security Group][azure_nsg] page.
  2. Select the Network Security Group that corresponds with your Virtual Machine.
  3. Add and Outgoing Rule for port 80. Be sure to allow incoming from any address.

Set the DNS Name Label

  1. Go to the [The Public IP Adresses][azure_ips] page.
  2. Select the Public IP that correspends with your Virtual Machine.
  3. Set the DNS Name Label in the Configuration section. In the case of this example it will look something like this your-domain-label.centralus.cloudapp.azure.com

Once you are able to connect through SSH to the Virtual Machine you can install the Web Framework of your choice (the two most well known in Python being Flask and Django). You can install either of them just by running the pip install command.

Keep in mind that we configured the Virtual Machine to allow traffic only on port 80. So make sure to configure the application to use this port.

Configure Your Application to Use Twilio Libraries

You can configure your application to use the Twilio library for Python in two ways:

  • Install the Twilio library for Python as a Pip package. It can be installed with the following commands:

      $ pip install twilio

    -OR-

  • Download the Twilio library for Python from GitHub (https://github.com/twilio/twilio-python) and install it like this:

      $ python setup.py install

Once you have installed the Twilio library for Python, you can then import it in your Python files:

    import twilio

For more information, see https://github.com/twilio/twilio-python/blob/master/README.md.

How to: Make an outgoing call

The following shows how to make an outgoing call. This code also uses a Twilio-provided site to return the Twilio Markup Language (TwiML) response. Substitute your values for the from_number and to_number phone numbers, and ensure that you've verified the from_number phone number for your Twilio account before running the code.

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)

As mentioned, this code uses a Twilio-provided site to return the TwiML response. You could instead use your own site to provide the TwiML response; for more information, see How to Provide TwiML Responses from Your Own Web Site.

How to: Send an SMS message

The following shows how to send an SMS message using the TwilioRestClient class. The from_number number is provided by Twilio for trial accounts to send SMS messages. The to_number number must be verified for your Twilio account before running the code.

# 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)

How to: Provide TwiML Responses from your own Website

When your application initiates a call to the Twilio API, Twilio will send your request to a URL that is expected to return a TwiML response. The example above uses the Twilio-provided URL http://twimlets.com/message. (While TwiML is designed for use by Twilio, you can view it in your browser. For example, click http://twimlets.com/message to see an empty <Response> element; as another example, click http://twimlets.com/message?Message%5B0%5D=Hello%20World to see a <Response> element that contains a <Say> element.)

Instead of relying on the Twilio-provided URL, you can create your own site that returns HTTP responses. You can create the site in any language that returns XML responses; this topic assumes you will be using Python to create the TwiML.

The following examples will output a TwiML response that says Hello World on the call.

With Flask:

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

With Django:

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

As you can see from the example above, the TwiML response is simply an XML document. The Twilio library for Python contains classes that will generate TwiML for you. The example below produces the equivalent response as shown above, but uses the twiml module in the Twilio library for Python:

from twilio import twiml

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

For more information about TwiML, see https://www.twilio.com/docs/api/twiml.

Once you have your Python application set up to provide TwiML responses, use the URL of the application as the URL passed into the client.calls.create method. For example, if you have a Web application named MyTwiML deployed to an Azure hosted service, you can use its url as webhook as shown in the following example:

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)

How to: Use Additional Twilio Services

In addition to the examples shown here, Twilio offers web-based APIs that you can use to leverage additional Twilio functionality from your Azure application. For full details, see the Twilio API documentation.

Next Steps

Now that you have learned the basics of the Twilio service, follow these links to learn more: