Twilio with Python

Purpose

This document is a content to learn Twilio, which is a communication API, using Python.

The content consists of the following five.

--Lesson 1. Try to make a call using RestAPI --Lesson 2 Play the original message --Lesson 3. Try using your browser as a phone --Lesson 4. Send voice-recognized content by SMS --Lesson 5. Sending and receiving faxes

For an overview of Twilio, please visit: https://twilio.kddi-web.com

Preparation

Python

Since Python 3.x will be used this time, please prepare the execution environment (working folder) of Python 3. To find out the Python version, use the following command.

$ python --version
Python 3.7.2

Since pip is used to install the library, please make sure that pip can be used together with Python. https://pip.pypa.io/en/stable/installing/

ngrok

To use Twilio, you need a public server that you can access from Twilio. This time, we will not build a server, but use ngrok to make the local environment accessible from the outside. Download ngrok from the following site and extract it. https://ngrok.com/

Twilio

If you don't have a Twilio account, get a trial account first. Please refer to this article for how to sign up for free. [Latest version] Twilio sign-up

You can only purchase one phone number with your trial account. In addition, only the authenticated phone number used when signing up can be used as the destination. If you want to call any phone number or purchase multiple phone numbers, please register your payment information (card information) and purchase points.

• From Lesson 4 of this article, you will need two phone numbers.

Lesson 1 Try making a call using the Rest API

In this lesson, you'll first purchase one phone number using Twilio's admin console. Then install the Python helper library and write the code to make the call. Currently, in order to purchase a Japanese phone number, you need to register your address information in advance. Please refer to the following article for how to register your address information. How to register your address on your phone number on Twilio

Buy a phone number

1. Log in to Twilio's admin console. https://jp.twilio.com/login/kddi-web

2. Click the button icon to open the slide menu and select Phone Number.

3. Select Buy a Number to open the screen for purchasing a phone number.

4. Make sure that "Japan (+81)" is selected for the country, check "Voice call" and "Fax", and press the search button.

5. Select one from the displayed list and press the "Purchase" button.

6. When the Buy This Number dialog appears, press the Buy This Number button.

7. When the Congratulations dialog appears, the number purchase is complete. Click the "Close" button to close the dialog.

• Make a note of the number in a notepad for later use. *

Preparation of Python helper library

Twilio has a helper library for Python, so install it first.

$ pip install twilio

The latest version as of 9/24/2019 is 6.31.0. If a lower version is installed, install it with the -U option. The latest version can be found at the following site. https://github.com/twilio/twilio-python/

Examine AccountSid and AuthToken

1. Log in to Twilio's admin console. https://jp.twilio.com/login/kddi-web

2. Copy the ACCOUNT SID and AUTH TOKEN values displayed in the Account Summary of the Console Dashboard to Notepad.

• AUTH TOKEN is masked, but you can see it by pressing the eye icon. *

coding

1. Open an editor and copy and paste the code below.

from twilio.rest import Client
account_sid = "ACxxxxxxxxx" # Your Account SID from www.twilio.com/console
auth_token  = "xxxxxxxx"  # Your Auth Token from www.twilio.com/console

client = Client(account_sid, auth_token)

call = client.calls.create(
    to="+81xxxxxxx",
    from_="+81xxxxxxx",
    url="http://demo.twilio.com/docs/voice.xml"
)

print(call.sid)

1. For account_sid, enter the AccountSid you wrote down earlier.
2. In auth_token, enter the AuthToken you wrote down earlier.
3. In to, enter your phone number in E.164 format. (Example: +819012345678)
4. In from_, enter the phone number you purchased earlier in E.164 format.
5. Save it as call.py in a folder where you can run Python.

Run

1. Run call.py and verify that your phone is called.

$ python call.py

Commentary

Let's check the code above. To make a call, call calls.create. In this, the source (from_) [* from cannot be used as a reserved word, so it becomes from_ *] and the destination (to) are specified. The point is the part specified by url. Here you specify the XML (called TwiML) that tells you what to do when the other person responds. The TwiML specified this time is an XML file as shown below.

<Response>
  <Say voice="alice">Thanks for trying our documentation. Enjoy!</Say>
  <Play>http://demo.twilio.com/docs/classic.mp3</Play>
</Response>

The verb executes Text to Speech, and the character string specified here (Thanks for trying our documentation. Enjoy!) Is played as speech. The verb is a verb that plays an audio file. In this way, you can specify behavior for Twilio by combining several TwiML.

Lesson 2 Play the original message

In this lesson, you will try to send your own original message. To do this, you'll need to create a TwiML with the message you want to stream and place it in a location that Twilio can access via http or https. There is a document at the following URL about what kind of TwiML is available. https://jp.twilio.com/docs/api/twiml

Flask installation

In order to make it accessible from Twilio, we will use Flask as a web framework this time. You can install Flask by following the steps below.

$ pip install Flask

Create a program to return TwiML in Flask

1. Open an editor and copy and paste the code below.

# say.py
from flask import Flask
from twilio.twiml.voice_response import VoiceResponse

app = Flask(__name__)

@app.route('/say', methods=['GET', 'POST'])
def say():
    #Create TwiML
    resp = VoiceResponse()
    resp.say("Hello. Twirio is a lot of fun.", language="ja-JP", voice="alice")
    return str(resp)

if __name__ == "__main__":
    app.run(port=5000, debug=True)

2. Save it as say.py.
3. Try to run it.

$ python say.py
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 219-682-997

4. Open your browser and enter http: // localhost: 5000 / say. If you see a message like the one above, your Python code is fine for now.

Start ngrok

Use ngrok to publish the created Python program to the outside.

1. Start ngrok with the following command.

$ ngrok http 5000

2. Copy the URL on the https side of Forwarding to Notepad.

Modify outgoing program

1. Open the Call.py created earlier in an editor.

from twilio.rest import Client
account_sid = "ACxxxxxxxxxxx" # Your Account SID from www.twilio.com/console
auth_token  = "xxxxxxxxxxxx"  # Your Auth Token from www.twilio.com/console

client = Client(account_sid, auth_token)

call = client.calls.create(
    to="+81xxxxxxxxxx",
    from_="+8150xxxxxxxx",
    url="https://xxxxxxx.ngrok.io/say"
)

print(call.sid)

1. Rewrite the url field with the URL you wrote down earlier. Don't forget to add / say at the end.

test

1. Try running call.py as in Lesson 1.

$ python call.py

2. If you receive a call and hear a message in Japanese, you are successful.

Commentary

Say.py is creating the original TwiML. Twilio's Python helper library makes it easy to create TwiML as well. To create a Voice-based TwiML, import twilio.twiml.voice_response in advance. To speak Japanese, specify language ='ja-JP' and voice ='alice'. If you write a sentence that is too long, it may not be uttered correctly. In such a case, divide the Say verb into multiple parts. Also, with this sample, I feel that Japanese is terrifying. If you want to speak fluent Japanese, use "Polly.Mizuki" or "Polly.Takumi" for the voice parameter in the part that generates TwiML (see the code below) and speak in relatively clean Japanese. Will do it. It costs a little money, but if you want to use beautiful Japanese, please try it.

~ Abbreviation ~
def say():
    #Create TwiML
    resp = VoiceResponse()
    resp.say("Hello. Twirio is a lot of fun.", language="ja-JP", voice="Polly.Mizuki")
    return str(resp)
~ Abbreviation ~

In addition to this, for example, AI's voice synthesis technology can be combined.

--AI Co., Ltd. "AITalk"

Lesson 3. Try using your browser as a phone

You may not know what you're talking about, but Twilio allows you to use your usual browser as your phone. Yes, you can call with your browser. In this lesson, you will use your browser as a phone and try to make a call through your browser. Sending and receiving via a browser uses a function called Twilio Client, but a mechanism called an access token is required for sending and receiving. An access token is an authentication key that allows you to use Twilio to use phone functions, and can be obtained by requesting Twilio to issue an access token from the user side. It takes time to create these mechanisms from scratch, so this time we will use the quick start prepared in advance. This lesson will use ngrok as before.

Program download

If you can use Git, use the following command to clone the source file to your working directory.

$ git clone https://github.com/TwilioDevEd/client-quickstart-python.git

If you can't use Git, download the Zip file from the URL below and extract it to your working directory. https://github.com/TwilioDevEd/client-quickstart-python/archive/master.zip

Change to the cloned (extracted) directory.

$ cd client-quickstart-python

.env file settings

Create an .env file by copying the sample .env file.

$ cp .env.example .env

For Windows users

$ cp .env.example.ps1 .env.ps1

Open .env or .env.ps1 with an editor and set environment variables.

.env

export TWILIO_ACCOUNT_SID=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
export TWILIO_AUTH_TOKEN=your_auth_token
export TWILIO_TWIML_APP_SID=APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
export TWILIO_CALLER_ID=+1XXXYYYZZZZ

For TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN, enter the AccountSit and AuthToken used in the previous lesson. I don't know TWILIO_TWIML_APP_SID yet at this point, so leave it alone. In TWILIO_CALLER_ID, write the purchased 050 number in E.164 format. After completing the settings, save it by overwriting.

Reading environment variables

Set the environment variables with the following command.

$ source .env

For Windows users, use the following command to set.

. .\.env.ps1

Loading the library

Use the following command to load the required library.

$ pip install -r requirements.txt

The libraries used this time are Flask, twilio, and fake-factory.

Start ngrok

$ ngrok http 5000

When ngrok starts, record the displayed URL (https) in Notepad.

Get application SID

1. Log in to Twilio's admin console.
2. Press the button icon and select Programmable Voice.
3. Select Tools.
4. Press the plus icon to create a new TwiML Apps.
5. Enter Twilio Client Quickstart as the friendly name.
6. In the voice call REQUEST URL, enter the ngrok URL + / voice you recorded earlier. Example: https://xxxxxxx.ngrok.io/voice
7. Press the "Save" button.

1. Select the TwiML Apps you created again and make a note of the Application SID.

2. Post the written Application SID to TWILIO_TWIML_APP_SID in the .env you just edited.

3. Close the running application (app.py) once (Ctrl-C).

4. Reload the environment variables.

$ source .env

Run application

$ python app.py

test

1. Start your browser (Chrome or Firefox) and open the URL starting with https displayed in ngrok.

If you see Twilio Device Ready! As shown on the screen, you can make a call. When making a call, specify the phone number in E.164 format.

Commentary

Open app.py in an editor and check it. There are two large codes in it, one to get an access token called / token and the other to make a call called / voice. In / token, ClientCapbilityToken object is created and allow_client_outgoing (application_sid) and allow_client_incoming (identity) are set. The former is the setting for outgoing tokens, and the latter is the setting for incoming calls. The outgoing token specifies the TwiML Apps SID, which allows Twilio to call / voice when the browser gives you an instruction to make a call. In addition, the token for incoming calls sets its own identity, which enables other clients to specify the identity as the destination to receive a call. / voice is the URL that Twilio calls when you make a call, and the destination number is passed as a To parameter. By returning this as a Dial verb, Twilio will call you. This time, the incoming call with 050 number is not implemented, but if you want to implement it, use Twilio's management console to specify the incoming call processing of 050 number, and use TwiML for the Dial verb destined for identity. It's OK if you return it. The code on the front end side can be found in quickstart.js in the static folder. When the page loads, you'll see that you're using ajax to get an access token. If the token acquisition is successful, the Device will be initialized using the acquired token. When the initialization is complete, the Device.ready event is fired. In addition to ready, Device has some important events. These events are described in the following documents: https://jp.twilio.com/docs/api/client/device

Lesson 4. Send voice-recognized content by SMS

In this lesson, you'll combine Twilio's voice recognition and SMS sending technologies to create a program that, when you receive an incoming call to your 050 number, records your voice and converts it into text and returns it to the caller via SMS. You cannot use the 050 number to send SMS, so purchase a new US number. ** You'll need to upgrade your Twilio trial account. ** **

Buy US number

1. Log in to Twilio's admin console.
2. Select "Phone Number" from the button icon.
3. Select "Buy a Number", select "United States" from the list box of countries, and press the "Search" button.
4. Select one local number that can use SMS and press the "Purchase" button.
5. When the Buy This Number dialog is displayed, press the "Buy This Number" button.
6. When the Congratulations dialog is displayed, press the "Close" button.

Work environment construction and coding

1. In a working directory where Python is available, create a directory named callSMS and change to that directory.
2. Create a file named app.py and paste the following code.

# app.py
from flask import Flask, request, Response
from twilio.rest import Client
from twilio.twiml.voice_response import Gather, VoiceResponse, Say

app = Flask(__name__)

account_sid = "ACxxxxxxxxxxxxxxxxxxxxxx"
auth_token = "xxxxxxxxxxxxxxxxxxxxxxx"

client = Client(account_sid, auth_token)

@app.route('/calling', methods=['GET', 'POST'])
def calling():
    #WebHook called when a call arrives
    response = VoiceResponse()
    gather = Gather(input='speech', language='ja-JP', action='/sendsms', method='POST')
    gather.say('Thank you for calling. Please give me a message.', language='ja-JP', voice='alice')
    response.append(gather)

    return str(response)

@app.route('/sendsms', methods=['POST'])
def sendsms():
    #Get voice recognition results
    result = request.form["SpeechResult"] or ''
    to = request.form["From"] or ''
    if (result != '' and to != ''):
        #Send SMS
        message = client.messages.create(to=to,
            from_="+1XXXXXXXXXXXX",
            body=result)
        print(message.sid)
        resp = VoiceResponse()
        resp.say("I have sent you a message. Thank you very much.", language="ja-JP", voice="alice")
        return str(resp)
    else:
        resp = VoiceResponse()
        resp.say("I'm sorry. Voice recognition was not possible.", language="ja-JP", voice="alice")
        return str(resp)

if __name__ == "__main__":
    app.run(port=5000, debug=True)

3. Rewrite account_sid and auth_token to your own.
4. Replace the from_ phone number with the US number you purchased earlier.

Launch application

$ python app.py

Start ngrok

$ ngrok http 5000

When ngrok starts, record the URL starting with https.

Incoming call setting of 050 number

1. Log in to the Twilio Admin Console.
2. Press the button icon and select "Phone Number".
3. Select the purchased 050 number to open the setting screen.
4. Set the A CALL COMES IN field to "Webhook" and describe the URL that you wrote down when starting ngrok with / calling added.
5. Press the "Save" button to save the settings.

test

1. Call the 050 number for which you have set the incoming call and insert a message after the guidance.
2. After a while, you will hear the guidance that you sent the message, and the voice recognition result will be sent to the SMS.

Commentary

The Gather verb generated by calling is originally a verb for processing DTMF signals (push tone signals), but it is also possible to acquire voice data in addition to DTMF. The voice data is internally passed to the voice recognition engine, and the result is sent to the webhook specified by the action parameter. Voice can be recorded for up to 60 seconds, and an additional charge of 3 yen will be incurred for each conversion (15 seconds unit) in addition to the call charge. This time, we sent the SMS as it was after voice recognition, but it is also possible to create a BOT using voice by using, for example, IBM Watson's conversation API.

Lesson 5. Sending and receiving faxes

In this lesson, you will use the Programmable Fax feature to send and receive faxes. From a global perspective, Japan is still a country where faxes are still heavily used, and there are many possible ways to use them, such as sending faxes from programs and automatically processing received faxes. You can use the 050 number to send and receive faxes, but you cannot receive voice calls or faxes with the same 050 number. This time, I will switch the already purchased 050 number for fax and use it.

Download the program and update the configuration file

1. Clone the sample program from GitHub.

$ git clone https://github.com/twilioforkwc/simpleFAX.git
$ cd simpleFAX

2. Rename example.env to .env.

$ mv example.env .env

3. Edit the .env file and edit ACCOUNT_SID and AUTH_TOKEN according to your environment.
4. Enter the purchased 050 number in FROM and the fax number of the destination in TO. You can also specify the fax number of the destination when sending.
5. Set environment variables.

$ source .env

Run application

1. Run the application.

$ python app.py

2. Start ngrok.

$ ngrok http 3000

Make a note of the URL of the started https.

050 number setting

1. Log in to Twilio's admin console.
2. Click the button icon and select a phone number.
3. Select the purchased 050 number.
4. Switch ACCEPT IN COMING to "Faxes".
5. Rewrite A FAX COMES IN to the URL of ngrok that you wrote down earlier with / receive added.
6. Press the "Save" button to complete the settings.

test

1. Try sending a fax from the fax machine to the 050 number you purchased.
2. If successful, a PDF file will be created in the fax folder.
3. To send a fax, enter ngrok's URL / sendfax in the URL field of your browser. The fax number of the destination is the one specified in .env, but if you want to change it, you can add the to parameter to the URL. Also, sample.pdf in the static folder is used as the PDF to be sent, but if you want to send another file, you can add the pdf parameter to the URL. The fax you want to send must be stored in the static folder in advance.

Example: https://xxxxxx.ngrok.io/sendfax?to=03XXXXXXXX&pdf=xxxxxx.pdf

Commentary

The app.py is large and contains two codes, one for sending (sendfax) and one for receiving (receive, actionReceiver). The sendfax for sending contains the code to send a fax using the Rest API. At the moment, the helper library for Python does not support fax, so it is realized by using the requests library. To determine whether the transmission was successful, it is necessary to specify statusCallback in the RestAPI at the time of transmission, or to call the RestAPI using the FAX SID included in the return value of the RestAPI at the time of transmission, but this process is omitted in this program. doing. Receive for receive is the first webhook to be called when a fax arrives at your Twilio number. Here you need to return either the verb (if you want to receive it) or the verb (if you want to reject it). This time I want to receive it, so I'm returning the verb. The verb can have an action parameter and is called when reception is complete or unsuccessful. In this code, actionReceiver is applicable. In actionReceiver, it is judged whether the reception was successful, and if it is successful, the PDF file written in MediaUrl is downloaded to the FAX folder.

More documentation on Programmable Fax can be found below. https://jp.twilio.com/docs/api/fax

Summary

This time we introduced the case of using Python, but in addition to Python, we also have SDKs for languages such as Node.js, C #, Java, Ruby, PHP, Salesforce. For more information, please see here.

What is Twilio?

https://twilio.kddi-web.com Twilio is a cloud API service that allows you to easily incorporate various communication methods such as voice calls, messaging (SMS / chat), and video into your applications and businesses. It is a pay-as-you-go system that does not require an initial cost and is compatible with various development languages, so it is also used for many hackathon events and startups.