3 |
4 |
5 | # Twilio Voice JavaScript SDK Quickstart for Python
6 |
7 | 
8 |
9 | > This template is part of Twilio CodeExchange. If you encounter any issues with this code, please open an issue at [github.com/twilio-labs/code-exchange/issues](https://github.com/twilio-labs/code-exchange/issues).
10 |
11 | ## About
12 |
13 | This application should give you a ready-made starting point for writing your own voice apps with the Twilio Voice JavaScript SDK (formerly known as Twilio Client).
14 |
15 | This application uses the lightweight [Flask Framework](http://flask.pocoo.org/). Once you set up the application, you will be able to make and receive calls from your browser. You will also be able to switch between audio input/output devices, and see dynamic volume levels on the call.
16 |
17 | 
18 |
19 | Implementations in other languages:
20 |
21 | | .NET | Java | Node | PHP | Ruby |
22 | | :--- | :--- | :----- | :-- | :--- |
23 | | [Done](https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-csharp) | [Done](https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-java) | [Done](https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-node) | [Done](https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-php) | [Done](https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-ruby) |
24 |
25 | ## Set Up
26 |
27 | ### Requirements
28 |
29 | - [Python](https://www.python.org/) **3.6**, **3.7**, **3.8**, or **3.9** version.
30 | - [ngrok](https://ngrok.com/download)
31 |
32 | ### Twilio Account Settings
33 |
34 | Before we begin, we need to collect all the config values we need to run the application.
35 |
36 | | Config Value | Description |
37 | | :------------- |:------------- |
38 | `TWILIO_ACCOUNT_SID` | Your primary Twilio account identifier - find this [in the console here](https://www.twilio.com/console).
39 | `TWILIO_TWIML_APP_SID` | The TwiML application with a voice URL configured to access your server running this app - create one [in the console here](https://www.twilio.com/console/voice/twiml/apps). Also, you will need to configure the Voice "REQUEST URL" on the TwiML app once you've got your server up and running.
40 | `TWILIO_CALLER_ID` | A Twilio phone number in [E.164 format](https://www.twilio.com/docs/glossary/what-e164) - you can [get one here](https://www.twilio.com/console/phone-numbers/incoming)
41 | `API_KEY` / `API_SECRET` | Your REST API Key information needed to create an [Access Token](https://www.twilio.com/docs/iam/access-tokens) - create [an API key here](https://www.twilio.com/console/project/api-keys). The `API_KEY` value should be the key's `SID`.
42 |
43 | ### Local development
44 |
45 | 1. First, clone this repository and `cd` into it.
46 |
47 | ```bash
48 | git clone https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-python.git
49 | cd voice-javascript-sdk-quickstart-python
50 | ```
51 |
52 | 2. Run `make install`. This command will create a Python virtual environment, load it, and install the Python dependencies.
53 |
54 | ```bash
55 | make install
56 | ```
57 |
58 | 3. Download the Twilio Voice JavaScript SDK code from GitHub.
59 |
60 | In a production environment, we recommend using `npm` to install the SDK. However, for the purposes of this quickstart,
61 | we are not introducing Node or build tools, and are instead getting the SDK code directly from GitHub.
62 |
63 | See the instructions [here](https://github.com/twilio/twilio-voice.js#github) for downloading the SDK code from GitHub.
64 | You will download a zip or tarball for a specific release version of the Voice JavaScript SDK (ex: `2.0.0`), extract the
65 | files, and retrieve the `twilio.min.js` file from the `dist/` folder. Move that `twilio.min.js` file into this project's `static/` directory.
66 |
67 | 4. Create a configuration file for your application by copying the `.env.example` file to a new file called `.env`. Then, edit the `.env` file to include your account and application details.
68 |
69 | ```bash
70 | cp .env.example .env
71 | ```
72 |
73 | See [Twilio Account Settings](#twilio-account-settings) to locate the necessary environment variables.
74 |
75 | #### Windows (PowerShell)
76 |
77 | Begin by creating a configuration file for your application:
78 | ```powershell
79 | cp .env.example.ps1 .env.ps1
80 | ```
81 |
82 | Edit `.env.ps1` with the four configuration parameters we gathered from above.
83 | "Dot-source" the file in PowerShell like so:
84 | ```powershell
85 | . .\.env.ps1
86 | ```
87 | This assumes you will run the application in the same PowerShell session. If not,
88 | edit the `.env.ps1` and uncomment the `[Environment]::SetEnvironmentVariable` calls.
89 | After re-running the script, the environment variables will be peramently set for
90 | your user account.
91 |
92 | 5. Run the application. It will run locally on port 5000.
93 |
94 | ```bash
95 | make serve
96 | ```
97 |
98 | 6. Navigate to [http://localhost:5000](http://localhost:5000)
99 |
100 | 7. Expose your application to the wider internet using [ngrok](https://ngrok.com/download). You can click [here](https://www.twilio.com/blog/2015/09/6-awesome-reasons-to-use-ngrok-when-testing-webhooks.html) for more details. This step **is important** and your application won't work if you only run the server on localhost.
101 |
102 | ```bash
103 | ngrok http 5000
104 | ```
105 |
106 | 8. When ngrok starts up, it will assign a unique URL to your tunnel.
107 | It might be something like `https://asdf456.ngrok.io`. Take note of this.
108 |
109 | 9. [Configure your TwiML app](https://www.twilio.com/console/voice/twiml/apps)'s
110 | Voice "REQUEST URL" to be your ngrok URL plus `/voice`. For example:
111 |
112 | 
113 |
114 | > **Note:** You must set your webhook urls to the `https` ngrok tunnel created.
115 |
116 | You should now be ready to rock! Make some phone calls or receiving incoming calls in the application.
117 | Note that Twilio Client requires WebRTC enabled browsers, so Edge and Internet Explorer will not work for testing.
118 | We'd recommend Google Chrome or Mozilla Firefox instead.
119 |
120 | ## Your Web Application
121 |
122 | When you navigate to `localhost:5000`, you should see the web application containing a "Start up the Device" button. Click this button to initialize a `Twilio.Device`.
123 |
124 | 
125 |
126 | When the `Twilio.Device` is initialized, you will be assigned a random client name, which will appear in the top left corner of the homepage.
127 | This client name is used as the identity field when generating an access token for the client, and is also used to route incoming calls to the correct client device.
128 |
129 | ### To make an outbound call to a phone number:
130 |
131 | Under "Make a Call", enter a phone number in [E.164 format](https://www.twilio.com/docs/glossary/what-e164) and press the "Call" button.
132 |
133 | ### To make a browser-to-browser call:
134 |
135 | Open two browser windows to `localhost:5000` and click "Start up the Device" button in both windows. You should see a different client name in each window.
136 |
137 | Enter one client's name in the other client's "Make a Call" input field, and press the "Call" button.
138 |
139 | 
140 |
141 | ### Receiving incoming calls from a non-browser device:
142 |
143 | You will first need to configure your Twilio Voice phone number (the phone number you used as the `TWILIO_CALLER_ID` configuration value) to route incoming calls to your TwiML app. This tells Twilio how to handle an incoming call directed to your Twilio Voice number.
144 |
145 | 1. Log in to the [Twilio Console](https://www.twilio.com/console)
146 | 2. Navigate to your [Active Number list](https://www.twilio.com/console/phone-numbers/incoming)
147 | 3. Click on the number you are using as your `TWILIO_CALLER_ID`.
148 | 4. Scroll down to find the "Voice & Fax" section and look for "CONFIGURE WITH".
149 | 5. Select "TwiML App".
150 | 6. Under "TwiML App", choose the TwiML App you created earlier for this quickstart.
151 | 7. Click the "Save" button at the bottom of the browser window.
152 |
153 | 
154 |
155 | You can now call your Twilio Voice phone number from your phone.
156 |
157 | **Note:** Since this is a quickstart with limited functionality, incoming calls will only be routed to your most recently created `Twilio.Device`.
158 |
159 | ### Unknown Devices
160 |
161 | If you see "Unknown Audio Output Device 1" in the "Ringtone" or "Speaker" devices lists, click the button below the boxes (Seeing "Unknown" Devices?) to have your browser identify your input and output devices.
162 | 
163 |
164 | ### Docker
165 |
166 | If you have [Docker](https://www.docker.com/) already installed on your machine, you can use our `docker-compose.yml` to setup your project.
167 |
168 | 1. Make sure you have the project cloned and that Docker is running on your machine.
169 | 2. Retrieve the `twilio.min.js` file and move it to the `static` directory as outlined in Step 3 of the [Local Development](#local-development) steps.
170 | 3. Setup the `.env` file as outlined in Step 4 of the [Local Development](#local-development) steps.
171 | 4. Run `docker-compose up`.
172 | 5. Follow the steps in [Local Development](#local-development) on how to expose your port to Twilio using [ngrok](https://ngrok.com/) and configure the remaining parts of your application.
173 |
174 | ### Tests
175 |
176 | You can run the tests locally with the following command. Before running, make sure the virtual environment is activated.
177 |
178 | ```bash
179 | source venv/bin/activate
180 | python3 -m pytest
181 | ```
182 |
183 | ### Cloud deployment
184 |
185 | Additionally to trying out this application locally, you can deploy it to a variety of host services. Here is a small selection of them.
186 |
187 | Please be aware that some of these might charge you for the usage or might make the source code for this application visible to the public. When in doubt research the respective hosting service first.
188 |
189 | | Service | |
190 | | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
191 | | [Heroku](https://www.heroku.com/) | [](https://heroku.com/deploy) |
192 |
193 | ## Resources
194 |
195 | - The CodeExchange repository can be found [here](https://github.com/twilio-labs/code-exchange/).
196 |
197 | ## Contributing
198 |
199 | This template is open source and welcomes contributions. All contributions are subject to our [Code of Conduct](https://github.com/twilio-labs/.github/blob/master/CODE_OF_CONDUCT.md).
200 |
201 | ## License
202 |
203 | [MIT](http://www.opensource.org/licenses/mit-license.html)
204 |
205 | ## Disclaimer
206 |
207 | No warranty expressed or implied. Software is as is.
208 |
209 | [twilio]: https://www.twilio.com
210 |
--------------------------------------------------------------------------------
/app.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python
2 |
3 | import os
4 | import re
5 |
6 | from dotenv import load_dotenv
7 | from faker import Faker
8 | from flask import Flask, Response, jsonify, redirect, request
9 | from twilio.jwt.access_token import AccessToken
10 | from twilio.jwt.access_token.grants import VoiceGrant
11 | from twilio.twiml.voice_response import Dial, VoiceResponse
12 |
13 | load_dotenv()
14 |
15 | app = Flask(__name__)
16 | fake = Faker()
17 | alphanumeric_only = re.compile("[\W_]+")
18 | phone_pattern = re.compile(r"^[\d\+\-\(\) ]+$")
19 |
20 | twilio_number = os.environ.get("TWILIO_CALLER_ID")
21 |
22 | # Store the most recently created identity in memory for routing calls
23 | IDENTITY = {"identity": ""}
24 |
25 |
26 | @app.route("/")
27 | def index():
28 | return app.send_static_file("index.html")
29 |
30 |
31 | @app.route("/token", methods=["GET"])
32 | def token():
33 | # get credentials for environment variables
34 | account_sid = os.environ["TWILIO_ACCOUNT_SID"]
35 | application_sid = os.environ["TWILIO_TWIML_APP_SID"]
36 | api_key = os.environ["API_KEY"]
37 | api_secret = os.environ["API_SECRET"]
38 |
39 | # Generate a random user name and store it
40 | identity = alphanumeric_only.sub("", fake.user_name())
41 | IDENTITY["identity"] = identity
42 |
43 | # Create access token with credentials
44 | token = AccessToken(account_sid, api_key, api_secret, identity=identity)
45 |
46 | # Create a Voice grant and add to token
47 | voice_grant = VoiceGrant(
48 | outgoing_application_sid=application_sid,
49 | incoming_allow=True,
50 | )
51 | token.add_grant(voice_grant)
52 |
53 | # Return token info as JSON
54 | token = token.to_jwt()
55 |
56 | # Return token info as JSON
57 | return jsonify(identity=identity, token=token)
58 |
59 |
60 | @app.route("/voice", methods=["POST"])
61 | def voice():
62 | resp = VoiceResponse()
63 | if request.form.get("To") == twilio_number:
64 | # Receiving an incoming call to our Twilio number
65 | dial = Dial()
66 | # Route to the most recently created client based on the identity stored in the session
67 | dial.client(IDENTITY["identity"])
68 | resp.append(dial)
69 | elif request.form.get("To"):
70 | # Placing an outbound call from the Twilio client
71 | dial = Dial(caller_id=twilio_number)
72 | # wrap the phone number or client name in the appropriate TwiML verb
73 | # by checking if the number given has only digits and format symbols
74 | if phone_pattern.match(request.form["To"]):
75 | dial.number(request.form["To"])
76 | else:
77 | dial.client(request.form["To"])
78 | resp.append(dial)
79 | else:
80 | resp.say("Thanks for calling!")
81 |
82 | return Response(str(resp), mimetype="text/xml")
83 |
84 |
85 | if __name__ == "__main__":
86 | app.run(debug=True, host="0.0.0.0")
87 |
--------------------------------------------------------------------------------
/docker-compose.yml:
--------------------------------------------------------------------------------
1 | version: "3.8"
2 | services:
3 | app:
4 | container_name: app
5 | restart: always
6 | build: .
7 | ports:
8 | - "5000:5000"
9 |
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
1 | flask~=2.1.3
2 | twilio~=6.38.1
3 | faker~=4.0.3
4 | python-dotenv==0.13.0
5 | pytest==5.4.1
6 |
--------------------------------------------------------------------------------
/screenshots/BrowserToBrowserCall.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TwilioDevEd/voice-javascript-sdk-quickstart-python/37d091663c0758d58f09c88040d5ba3ce3878407/screenshots/BrowserToBrowserCall.png
--------------------------------------------------------------------------------
/screenshots/ConfigurePhoneNumber.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TwilioDevEd/voice-javascript-sdk-quickstart-python/37d091663c0758d58f09c88040d5ba3ce3878407/screenshots/ConfigurePhoneNumber.png
--------------------------------------------------------------------------------
/screenshots/ConfigurePhoneNumberWithTwiMLApps.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TwilioDevEd/voice-javascript-sdk-quickstart-python/37d091663c0758d58f09c88040d5ba3ce3878407/screenshots/ConfigurePhoneNumberWithTwiMLApps.png
--------------------------------------------------------------------------------
/screenshots/Homepage.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TwilioDevEd/voice-javascript-sdk-quickstart-python/37d091663c0758d58f09c88040d5ba3ce3878407/screenshots/Homepage.png
--------------------------------------------------------------------------------
/screenshots/InitializeDevice.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TwilioDevEd/voice-javascript-sdk-quickstart-python/37d091663c0758d58f09c88040d5ba3ce3878407/screenshots/InitializeDevice.png
--------------------------------------------------------------------------------
/screenshots/UnknownDevices.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TwilioDevEd/voice-javascript-sdk-quickstart-python/37d091663c0758d58f09c88040d5ba3ce3878407/screenshots/UnknownDevices.png
--------------------------------------------------------------------------------
/screenshots/UpdateRequestURL.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TwilioDevEd/voice-javascript-sdk-quickstart-python/37d091663c0758d58f09c88040d5ba3ce3878407/screenshots/UpdateRequestURL.png
--------------------------------------------------------------------------------
/static/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | 39 | Incoming Call from 40 |
41 | 42 | 43 | 44 |> ${message}
`; 214 | logDiv.scrollTop = logDiv.scrollHeight; 215 | } 216 | 217 | function setClientNameUI(clientName) { 218 | var div = document.getElementById("client-name"); 219 | div.innerHTML = `Your client name: ${clientName}`; 220 | } 221 | 222 | function resetIncomingCallUI() { 223 | incomingPhoneNumberEl.innerHTML = ""; 224 | incomingCallAcceptButton.classList.remove("hide"); 225 | incomingCallRejectButton.classList.remove("hide"); 226 | incomingCallHangupButton.classList.add("hide"); 227 | incomingCallDiv.classList.add("hide"); 228 | } 229 | 230 | // AUDIO CONTROLS 231 | 232 | async function getAudioDevices() { 233 | await navigator.mediaDevices.getUserMedia({ audio: true }); 234 | updateAllAudioDevices.bind(device); 235 | } 236 | 237 | function updateAllAudioDevices() { 238 | if (device) { 239 | updateDevices(speakerDevices, device.audio.speakerDevices.get()); 240 | updateDevices(ringtoneDevices, device.audio.ringtoneDevices.get()); 241 | } 242 | } 243 | 244 | function updateOutputDevice() { 245 | const selectedDevices = Array.from(speakerDevices.children) 246 | .filter((node) => node.selected) 247 | .map((node) => node.getAttribute("data-id")); 248 | 249 | device.audio.speakerDevices.set(selectedDevices); 250 | } 251 | 252 | function updateRingtoneDevice() { 253 | const selectedDevices = Array.from(ringtoneDevices.children) 254 | .filter((node) => node.selected) 255 | .map((node) => node.getAttribute("data-id")); 256 | 257 | device.audio.ringtoneDevices.set(selectedDevices); 258 | } 259 | 260 | function bindVolumeIndicators(call) { 261 | call.on("volume", function (inputVolume, outputVolume) { 262 | var inputColor = "red"; 263 | if (inputVolume < 0.5) { 264 | inputColor = "green"; 265 | } else if (inputVolume < 0.75) { 266 | inputColor = "yellow"; 267 | } 268 | 269 | inputVolumeBar.style.width = Math.floor(inputVolume * 300) + "px"; 270 | inputVolumeBar.style.background = inputColor; 271 | 272 | var outputColor = "red"; 273 | if (outputVolume < 0.5) { 274 | outputColor = "green"; 275 | } else if (outputVolume < 0.75) { 276 | outputColor = "yellow"; 277 | } 278 | 279 | outputVolumeBar.style.width = Math.floor(outputVolume * 300) + "px"; 280 | outputVolumeBar.style.background = outputColor; 281 | }); 282 | } 283 | 284 | // Update the available ringtone and speaker devices 285 | function updateDevices(selectEl, selectedDevices) { 286 | selectEl.innerHTML = ""; 287 | 288 | device.audio.availableOutputDevices.forEach(function (device, id) { 289 | var isActive = selectedDevices.size === 0 && id === "default"; 290 | selectedDevices.forEach(function (device) { 291 | if (device.deviceId === id) { 292 | isActive = true; 293 | } 294 | }); 295 | 296 | var option = document.createElement("option"); 297 | option.label = device.label; 298 | option.setAttribute("data-id", id); 299 | if (isActive) { 300 | option.setAttribute("selected", "selected"); 301 | } 302 | selectEl.appendChild(option); 303 | }); 304 | } 305 | }); 306 | -------------------------------------------------------------------------------- /static/site.css: -------------------------------------------------------------------------------- 1 | @import url(https://fonts.googleapis.com/css?family=Share+Tech+Mono); 2 | 3 | body, 4 | p { 5 | padding: 0; 6 | margin: auto; 7 | font-family: Arial, Helvetica, sans-serif; 8 | } 9 | 10 | h1 { 11 | text-align: center; 12 | } 13 | 14 | h2 { 15 | margin-top: 0; 16 | border-bottom: 1px solid black; 17 | } 18 | 19 | button { 20 | margin-bottom: 10px; 21 | } 22 | 23 | label { 24 | text-align: left; 25 | font-size: 1.25em; 26 | color: #777776; 27 | display: block; 28 | } 29 | 30 | header { 31 | text-align: center; 32 | } 33 | 34 | main { 35 | padding: 3em; 36 | max-width: 1200px; 37 | margin: 0 auto; 38 | display: flex; 39 | justify-content: space-between; 40 | align-items: flex-start; 41 | } 42 | 43 | .left-column, 44 | .center-column, 45 | .right-column { 46 | width: 30%; 47 | min-width: 16em; 48 | margin: 0 1.5em; 49 | text-align: center; 50 | } 51 | 52 | /* Left Column */ 53 | #client-name { 54 | text-align: left; 55 | margin-bottom: 1em; 56 | font-family: "Helvetica Light", Helvetica, sans-serif; 57 | font-size: 1.25em; 58 | color: #777776; 59 | } 60 | 61 | select { 62 | width: 250px; 63 | height: 60px; 64 | margin-bottom: 10px; 65 | } 66 | 67 | /* Center Column */ 68 | input { 69 | font-family: Helvetica-LightOblique, Helvetica, sans-serif; 70 | font-style: oblique; 71 | font-size: 1em; 72 | width: 100%; 73 | height: 2.5em; 74 | padding: 0; 75 | display: block; 76 | margin: 10px 0; 77 | } 78 | 79 | div#volume-indicators { 80 | padding: 10px; 81 | margin-top: 20px; 82 | width: 500px; 83 | text-align: left; 84 | } 85 | 86 | div#volume-indicators > div { 87 | display: block; 88 | height: 20px; 89 | width: 0; 90 | } 91 | 92 | /* Right Column */ 93 | .right-column { 94 | padding: 0 1.5em; 95 | } 96 | 97 | #log { 98 | text-align: left; 99 | border: 1px solid #686865; 100 | padding: 10px; 101 | height: 9.5em; 102 | overflow-y: scroll; 103 | } 104 | 105 | .log-entry { 106 | color: #686865; 107 | font-family: "Share Tech Mono", "Courier New", Courier, fixed-width; 108 | font-size: 1.25em; 109 | line-height: 1.25em; 110 | margin-left: 1em; 111 | text-indent: -1.25em; 112 | width: 90%; 113 | } 114 | 115 | /* Other Styles */ 116 | .hide { 117 | position: absolute !important; 118 | top: -9999px !important; 119 | left: -9999px !important; 120 | } 121 | 122 | button:disabled { 123 | cursor: not-allowed; 124 | } 125 | -------------------------------------------------------------------------------- /tests/conftest.py: -------------------------------------------------------------------------------- 1 | import os 2 | 3 | import pytest 4 | 5 | from app import app as flask_app 6 | 7 | 8 | @pytest.fixture 9 | def app(): 10 | yield flask_app 11 | 12 | 13 | @pytest.fixture 14 | def client(app): 15 | return app.test_client() 16 | -------------------------------------------------------------------------------- /tests/test_routes.py: -------------------------------------------------------------------------------- 1 | from unittest.mock import patch 2 | 3 | 4 | def test_index(app, client): 5 | res = client.get('/') 6 | assert res.status_code == 200 7 | assert 'Make a Call' in res.get_data(as_text=True) 8 | 9 | 10 | def test_voice_has_to_parameter(app, client): 11 | res = client.post('/voice', data=dict(phone='+593XXXXXXX')) 12 | assert res.status_code == 200 13 | assert '