[PYTHON] Understanding how it works Twilio # 1-Introduction
Introduction
Twilio is used in various places as an easy and general-purpose telephony service, and I think that brothers and sisters are also using it in various projects.
The official documentation has a wealth of sample code for each language, but until I got tired of it, the focus was on how to call from each language, and there was no information about communication protocols and data structures.
In particular, I couldn't find any detailed information about how to make a call to a Twilio client from an external phone or implement a server that returns TwiML. \ # There was fragmentary information, but I had a hard time combining it to a practical level ...
Therefore, I would like to summarize the necessary information by comparing the results of actual verification and the results of packet capture, etc., with an awareness of how Twilio works.
Please note that information not included in the official documentation has been verified at this time until we get tired of it, and may change in the future.
Composition of this theme
Due to the large volume of this theme, we will divide it into the following four sections. This article corresponds to "1. Introduction".
―― 1. ** Introduction ← Now here ** ―― 1. ** Definition of basic structure and terms when using Twilio ** ―― 2. ** Environment verified this time ** ―― 2. Communication flow data structure ―― 1. Authentication / Capability Token transfer ―― 2. Call from an external phone to your Twilio client (Incoming Call) ―― 3. Call from Twilio client to external phone (OutgoingCall) --3-1. AWS API Gateway + Lambda Implementation Walkthrough (Part 1) ―― 1. Implementation of API Server processing (Python on AWS Lambda) ―― 2. API Gateway settings --3-2. AWS API Gateway + Lambda Implementation Walkthrough (Part 2) --3. Implementing and deploying Twilio Client ―― 4. Operation check!
Assumed reader
This article and related articles are intended for the following readers:
--You have already created a Twilio account (Trial version is acceptable) --I've read the Tutorial in the official Twilio documentation lightly (preferably if you've actually tried it) --You have created an AWS account --Have used AWS
Definition of basic structure and terms when using Twilio
This is the main subject. First, let's check the basic configuration and communication flow that Twilio envisions.
The figure below is taken from the official documentation, but the figure in "Architecture" is very important and should be kept in mind. This is a configuration for making / receiving calls from an Android device using Twilio, but this is typically the configuration.
Twilio Client Android SDK - Architecture
https://www.twilio.com/docs/api/client/android
The main characters are the following three. It seems that there is no official name for each, but in this article we will unify them with the following three names.
- Twilio Client ――This is a device that does not originally have a phone number, such as an Android app or a JavaScript app.
- API Server ――It is a server that you prepare yourself. It is "your server" in the figure. ――First, you need to authenticate with Twilio Client. ――It is also necessary to provide TwiML (* described later) that defines the behavior of the phone application. --Receive an HTTP request from the Twilio Server below and return TwiML. --Therefore, it must be published on the Internet.
- Twilio Server --This is the server operated by Twilio. Details are unknown. ――Intermediate communication from Twilio Client, make TwiML acquisition request to API Server as needed, and perform various processing. —— Part of the Twilio Client authentication and initial setup. --When authentication is successful, the information that the Twilio Client can be connected is also retained (* guess. Not verified.). At this stage, it is logically possible to make calls from other legacy phones. (It depends on TwiML whether you can really make a call)
Keep the Twilio Client as central as possible when explaining where to make a call. In other words, make a call from Twilio Client / receive a call from Twilio Client. \ # By the way, some of the features available in Twilio's SDK and API have incoming and outgoing features, but these are all centered around the Twilio Client.
Other terms used in this article and a series of related articles are defined as follows.
| No | the term | Contents |
|---|---|---|
| 1 | Twilio phone number | Call the phone number you purchased from Twilio and associated with your Twilio Client. Always E.It is expressed in 164 format. |
| 2 | E.164 format | 「+The format starts with ", followed by the country code and telephone number. You can insert hyphens and spaces in the middle. e.g. +81-3-1234-5678 |
| 3 | TwiML | * Please refer to the official document(https://www.twilio.com/docs/api/twiml) |
| 4 | Client Name | A unique name associated with the Twilio Client. Required to receive calls with Twilio Client. |
| 5 | Incoming Call | Make a call to Twilio Client from an external phone. Sometimes written as an inbound call. |
| 6 | Outgoing Call | Make an external call from Twilio Client. Sometimes written as an outbound call. |
Environment verified this time
The Twilio Client we're launching this time aims to be able to do the same thing as a regular phone. The specific specifications are as follows.
――What you can do --From Twilio Client, you can specify any number to make a general call (outbound call) --You can make a call to Twilio Client from a regular phone (inbound call) --Twilio Client specifications --Hold only your Twilio phone number as a value to identify yourself. It does not retain its own Client Name. --Implemented in HTML / JavaScript and placed on S3.
The architecture has the following configuration.
AWS is used as the API Server that you prepare yourself. I implemented it in Python using API Gateway and Lambda. The region is Tokyo (ap-northeast-1). The Twilio Client has been modified based on Twilio's JavaScript tutorial. Place it on S3 and access it from your web browser.
Twilio Client Javascript Quickstart https://www.twilio.com/docs/quickstart/client/javascript
\ # However, the base is around August 2015. \ # As of October 12, 2016, I couldn't find the tutorial I referred to at that time in the official document ...
The API provided by API Server is defined as follows.
| Endpoint | Description | Names in a series of articles |
|---|---|---|
| /twilio/retrieve_capability_token | Return the Capability Token to Twilio Client. | Capability Token acquisition API |
| /twilio/retrieve_twiml/call_incoming | Returns the TwiML used to call the Twilio Client. | TwiML Return API for Incoming Call |
| /twilio/retrieve_twiml/call_outgoing | Returns the TwiML used to make calls from the Twilio Client. | TwiML Return API for Outgoing Call |
Deploying to the prod stage of API Gateway. So the full URL looks like this: The URL configuration will be explained when implementing it in API Gateway, so it will be omitted here.
https://xxxxxxxxxx.execute-api.ap-northeast-1.amazonaws.com/prod/twilio/retrieve_capability_token https://xxxxxxxxxx.execute-api.ap-northeast-1.amazonaws.com/prod/twilio/retrieve_twiml/call_incoming https://xxxxxxxxxx.execute-api.ap-northeast-1.amazonaws.com/prod/twilio/retrieve_twiml/call_outgoing
Opening and preparing a Twilio account
Register for an account from the Twilio site in Japan. Be careful not to register from US sites. http://twilio.kddi-web.com/
Get and set your Twilio phone number
Get the phone number and make the necessary settings. After logging in to Twilio Console, get a new number from "Phone Numbers" in the menu on the left. You can also get one with your Trial account. However, "verification" is required to make a call to the actual phone. Register a phone number to test the call from "Phone Number"-> "Verified Phone Number".
After getting the phone number, set the URL of "A CALL COMES IN". Set the URL of the TwiML return API for Incoming Call here. (The actual URL will be constructed with 3. AWS API Gateway + Lambda Implementation Walkthrough.)
Please refer to the figure below.
This is used when calling this Twilio phone number from a real phone.
Create and configure TwiML App
Create a TwiML App and configure the required settings. After logging in to Twilio Console, go to "Programmable Voice"-> "Tools"-> "TwiML Apps" in the menu on the left. From here you can create a new TwiML App.
Set the "REQUEST URL" of "Voice call". Set the URL of the TwiML return API for Outgoing Call here. (The actual URL will be constructed with 3. AWS API Gateway + Lambda Implementation Walkthrough.)
Please refer to the figure below.
Opening and implementing an AWS account
Open an AWS account. The specific implementation will be explained in 3. AWS API Gateway + Lambda Implementation Walkthrough, so I will omit it here.
Summary
So far, we have explained the outline of this theme and the items to be prepared. The continuation will be the following article.
Understanding from the mechanism Twilio # 2-Communication flow data structure