└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Getting started with Twilio at Global Hack Week 2 | 3 | Hello hackers! Learn how to use REST APIs with Twilio during Global Hack Week by following the steps in this repository. You can submit the challenges each day at [https://ghw.mlh.io](https://ghw.mlh.io). In this README, you will find instructions to follow for each day. 4 | 5 | ## Contents 6 | - [Getting started with Twilio at Global Hack Week](#getting-started-with-twilio-at-global-hack-week) 7 | - [Contents](#contents) 8 | - [Getting Help](#getting-help) 9 | - [Daily challenges](#daily-challenges) 10 | - [What is an API? What is a REST API?](#what-is-an-api-what-is-a-rest-api) 11 | - [Day 1: Get ready to hack with Twilio.](#day-1-get-ready-to-hack-with-twilio) 12 | - [Step 1: Create an account](#step-1-create-an-account) 13 | - [Step 2: Upgrading your account](#step-2-upgrading-your-account) 14 | - [Step 3: Buy Two Twilio numbers](#step-3-buy-two-twilio-numbers) 15 | - [Step 4: Installing the Twilio CLI](#step-4-installing-the-twilio-cli) 16 | - [Step 5: Installing the Dev Phone](#step-5-installing-the-dev-phone) 17 | - [Step 6: Installing `curl`](#step-6-installing-curl) 18 | - [Step 7: Daily challenge complete! Time to submit.](#step-7-daily-challenge-complete-time-to-submit) 19 | - [Day 2: Receive your first phone call using TwiML bins and Dev Phone.](#day-2-receive-your-first-phone-call-using-twiml-bins-and-dev-phone) 20 | - [Step 1: Create a TwiML bin to handle a phone call](#step-1-create-a-twiml-bin-to-handle-a-phone-call) 21 | - [Step 2: Link your TwiML bin to your Twilio number](#step-2-link-your-twiml-bin-to-your-twilio-number) 22 | - [Step 3: Test it using Dev Phone](#step-3-test-it-using-dev-phone) 23 | - [Step 4: Daily challenge complete! Time to submit.](#step-4-daily-challenge-complete-time-to-submit) 24 | - [Day 3: Make your first outbound phone call using `curl`.](#day-3-make-your-first-outbound-phone-call-using-curl) 25 | - [Step 1: Check out the Twilio documentation on making calls](#step-1-check-out-the-twilio-documentation-on-making-calls) 26 | - [Step 2: Understanding the `curl` command](#step-2-understanding-the-curl-command) 27 | - [Step 3: Building our `curl` request](#step-3-building-our-curl-request) 28 | - [Step 4: Make the request](#step-4-make-the-request) 29 | - [Step 5: Daily challenge complete! Time to submit.](#step-5-daily-challenge-complete-time-to-submit) 30 | - [Day 4: Setting up a web application with ngrok and webhooks.](#day-4-setting-up-a-web-application-with-ngrok-and-webhooks) 31 | - [Step 1: Create a Node.js or Python web application](#step-1-create-a-nodejs-or-python-web-application) 32 | - [Step 2: Install ngrok](#step-2-install-ngrok) 33 | - [Step 3: Set your Twilio webhook](#step-3-set-your-twilio-webhook) 34 | - [Step 4: Daily challenge complete! Time to submit.](#step-4-daily-challenge-complete-time-to-submit-1) 35 | - [Day 5: Receiving SMS messages with our web application.](#day-5-receiving-sms-messages-with-our-web-application) 36 | - [Step 1: Add a new endpoint](#step-1-add-a-new-endpoint) 37 | - [Step 2: Getting the message contents](#step-2-getting-the-message-contents) 38 | - [Step 3: Send an SMS from the Dev Phone](#step-3-send-an-sms-from-the-dev-phone) 39 | - [Step 4: Daily challenge complete, time to submit!](#step-4-daily-challenge-complete-time-to-submit-2) 40 | - [Day 6: Replying to SMS messages with our web application.](#day-6-replying-to-sms-messages-with-our-web-application) 41 | - [Step 1: Writing a response](#step-1-writing-a-response) 42 | - [Day 7: Deploy from the Twilio Code Exchange](#day-7-deploy-from-the-twilio-code-exchange) 43 | - [Frequently Asked Questions](#frequently-asked-questions) 44 | - [I have an existing account with Twilio credit, what do I do?](#i-have-an-existing-account-with-twilio-credit-what-do-i-do) 45 | - [My Twilio account was suspended](#my-twilio-account-was-suspended) 46 | ## Getting Help 47 | 48 | If you have questions about Twilio or the Global Hack Week challenges, visit the `#twilio` channel in the [MLH Discord](https://discord.mlh.io/). 49 | 50 | # Daily challenges 51 | 52 | ## What is an API? What is a REST API? 53 | 54 | An Application Programming Interface (API) is provided by a service owner so that others may use the features and functions enabled by the service. APIs describe how a consumer will make requests of the service, and what they will receive in return. [Read more](https://www.twilio.com/docs/glossary/what-is-an-api). 55 | 56 | A REST API allows software programs to expose functionality and data to other programs over the Internet in a consistent format. Generally speaking, when people use the term REST API, they are referring to an API that is accessed via the HTTP protocol at a predefined set of URLs (uniform resource locators) representing the various resources with which interactions can occur. [Read more](https://www.twilio.com/docs/glossary/what-is-a-rest-api). 57 | 58 | Twilio is an example of a REST API. Twilio's communication APIs let you do things like send text messages and emails, make phone calls, and stream video. You can see all of the things you can do with Twilio on the [Twilio docs](https://www.twilio.com/docs). 59 | 60 | During Global Hack Week, you will learn how to **send and receive text messages** and **make and receive phone calls** with Twilio. 61 | 62 | ## Day 1: Get ready to hack with Twilio. 63 | 64 | To complete the week's challenges, there's some setup we need to do first. Today you will: 65 | 66 | - Create and upgrade your Twilio account with some free credit. 67 | - Use your free credit to buy two Twilio numbers. 68 | - Set up the Twilio Dev Phone to help test your Twilio number. 69 | - Install `curl` to make requests to the Twilio API from the command line. 70 | 71 | ### Step 1: Create an account 72 | 73 | If you don't already have a Twilio account, create one by visiting [this link](https://www.twilio.com/try-twilio?promo=mlh-twilio). 74 | 75 | ### Step 2: Upgrading your account 76 | 77 | When you create an account with the above link, you will create a trial account. To complete the Twilio challenges during Global Hack Week, you will need to use 2 Twilio numbers, which requires an upgraded account. To upgrade your account: 78 | 79 | - Visit the #twilio channel in the MLH Discord. 80 | - Check the pinned messages for the channel. 81 | - Find the promo code shared in the pinned message. 82 | - Follow [this guide](https://www.twilio.com/blog/apply-promo-code) to apply the promo code to your account. 83 | 84 | When you use this code, you will also get some free credit. If you did not create a new account, and are using an account you created in the past, you can still use this code to get extra credit to complete the Global Hack Week daily challenge. 85 | 86 | ### Step 3: Buy Two Twilio numbers 87 | 88 | With your free credit, you can now buy your first Twilio numbers! With a Twilio number, you can send and receive calls and SMS. 89 | 90 | We will buy two numbers: 91 | 92 | - One number to use in our application. 93 | - One number to test the other number, using the Dev Phone. 94 | 95 | To buy a number, follow [this guide](https://support.twilio.com/hc/en-us/articles/223135247-How-to-Search-for-and-Buy-a-Twilio-Phone-Number-from-Console). 96 | 97 | Buy a number with both SMS and Voice capabilities, so you can send/receive messages and phone calls. Phone numbers may not be available in your country, or may require extra identity documentation for your country. If this is the case, you can buy US numbers. This won't cost you any extra during testing, as we'll be using the Dev Phone to call/message the number, and not your local mobile number. 98 | 99 | ### Step 4: Installing the Twilio CLI 100 | 101 | The Twilio CLI makes it easy to use Twilio from our command line interface. We will need the Twilio CLI to use the Dev Phone, which makes it easy (and free) to test our Twilio services from anywhere in the world. 102 | 103 | To install the CLI, follow [this guide](https://www.twilio.com/docs/twilio-cli/quickstart). 104 | 105 | ### Step 5: Installing the Dev Phone 106 | 107 | The Dev Phone lets us test our Twilio applications using a Twilio number, rather than your own mobile number. This means you can test your applications using only your Twilio credit, from anywhere in the world. 108 | 109 | To install the Dev Phone, follow [this guide](https://www.twilio.com/docs/labs/dev-phone). 110 | 111 | ### Step 6: Installing `curl` 112 | 113 | The last step today is to install `curl`. `curl` is a command line tool for getting data from URLs, and we'll use it to interact with the Twilio REST API. 114 | 115 | You can learn more about `curl` [here](https://curl.se/). 116 | 117 | To install `curl`, follow [this guide](https://everything.curl.dev/get). 118 | 119 | `curl` comes pre-installed on Windows, and can be accessed through Powershell. Use `curl.exe` when giving commands, i.e. `curl.exe --version`. 120 | 121 | ### Step 7: Daily challenge complete! Time to submit. 122 | 123 | You've completed the challenge for the day, high five! To submit the challenge, type `curl --version` into your terminal, and submit a screenshot [on the DevPost](https://ghw-september-day-2.devpost.com/) 124 | 125 | ## Day 2: Receive your first phone call using TwiML bins and Dev Phone. 126 | 127 | [TwiML](https://www.twilio.com/docs/glossary/what-is-twilio-markup-language-twiml) (Twilio Markup Language) is a special markup language which you can use to program actions in Twilio. 128 | 129 | Today you will: 130 | 131 | - Create a TwiML bin to handle a phone call. 132 | - Assign it to your Twilio number. 133 | - Make a call using Dev Phone. 134 | 135 | ### Step 1: Create a TwiML bin to handle a phone call 136 | 137 | A TwiML bin is a container for TwiML. We can fill the bin with TwiML to program Twilio to do certain actions, and then connect the bin to our phone number. Follow the instructions [here](https://www.twilio.com/docs/serverless/twiml-bins/getting-started#create-a-new-twiml-bin) to create a new TwiML bin to respond to a phone call with "hello world". 138 | 139 | ### Step 2: Link your TwiML bin to your Twilio number 140 | 141 | Now that we have some TwiML to say "hello world", we need to connect it to our phone number. Choose one of the two numbers you purchased in day 1, and follow [this guide](https://www.twilio.com/docs/serverless/twiml-bins/getting-started#wire-your-twiml-bin-up-to-an-incoming-phone-call) to do that. 142 | 143 | Remember which number you chose! In the next step, we will use the other number. 144 | 145 | ### Step 3: Test it using Dev Phone 146 | 147 | Open your terminal and start the Dev Phone with `twilio dev-phone`. 148 | 149 | After starting up, the terminal will tell you the address of the Dev Phone interface, usually `https://localhost:3001`. Go here in your browser to use the Dev Phone. 150 | 151 | From here, you can select a phone number. Choose the number that you didn't use in the previous step. The Dev Phone will then show you a dialler to call a number. Enter your other phone number, the one with the TwiML bin, and hit call. You should hear "Hello World" spoken back to you. 152 | 153 | ### Step 4: Daily challenge complete! Time to submit. 154 | 155 | You've completed day 2, high five! To submit, take a screenshot of your Dev Phone call history and submit to [DevPost](https://hackp.ac/dailydevpost). 156 | 157 | ## Day 3: Make your first outbound phone call using `curl`. 158 | 159 | Yesterday, we set up our Twilio number to RECEIVE phone calls. Today we will make an outbound phone call, from our Twilio number. 160 | 161 | Today you will: 162 | 163 | - Learn how to use `curl` to make HTTP requests. 164 | - Build a `curl` request that will make a phone call using the Twilio API. 165 | - Make a call from your Twilio number to your Dev Phone. 166 | 167 | ### Step 1: Check out the Twilio documentation on making calls 168 | 169 | The [Twilio documentation for making calls](https://www.twilio.com/docs/voice/make-calls) offers examples in several languages and tools. This is useful if you are using the Twilio API from your favourite programming language, but it also has examples in `curl`, making it easy for us to test each endpoint from the command line. 170 | 171 | In the code editor on the right of the page, select `curl` to bring up the example. It will look like this: 172 | 173 | ``` 174 | curl -X POST https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json \ 175 | --data-urlencode "Url=http://demo.twilio.com/docs/voice.xml" \ 176 | --data-urlencode "To=+14155551212" \ 177 | --data-urlencode "From=+15017122661" \ 178 | -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN 179 | ``` 180 | 181 | Let's break this down. 182 | 183 | ### Step 2: Understanding the `curl` command 184 | 185 | Let's go through the example command bit by bit. 186 | 187 | - `curl`: we're using the command curl! That bit is easy. 188 | - `-X POST`: `-X` specifies the method for the request to the URL. By default, `curl` makes a `GET` request, to simply fetch the contents of the URL. Here we are making a `POST` request, as we want to send some data to the Twilio API with our request. 189 | - `https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json`: this is the URL we are sending the request to, it is an endpoint on the Twilio API for making calls. 190 | - `$TWILIO_ACCOUNT_SID`: This is not actually part of the URL, we can tell from the leading `$` that this is a variable that our command line will substitute when it makes the request. We will have to set this variable before we make the request, we'll deal with that in the next step! 191 | - `--data-urlencode`: This lets us encode data for `curl` to send in the `POST` body. We are sending 3 pieces of data to the API with our POST request: 192 | - `Url`: This is the URL of the TwiML that we want to use in the call. We can use a TwiML bin URL for this! 193 | - `To`: This is the number we want to call, we'll set this to the number of our Dev Phone. 194 | - `From`: This is the number we want to use to make the call. This will be our other Twilio number. 195 | - `-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN`: It's those variables again! `-u` sets the authentication method. This is where we tell the Twilio API to make the request from our account. There are two variables here: 196 | - `TWILIO_ACCOUNT_SID`: This is the unique identifier for our account, kind of like a username. 197 | - `TWILIO_AUTH_TOKEN`: The auth token is kind of like the password for our account when we make an API request. You want to keep this secret! 198 | 199 | Phew! That was a lot. Some of that might be confusing. Don't forget that you can ask questions, or ask for help, in the `#twilio` channel in the MLH Discord. 200 | 201 | ### Step 3: Building our `curl` request 202 | 203 | We can use this example from the docs almost as is, there is just a couple of things we need to do: 204 | 205 | 1. Set our `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` variables. 206 | 2. Replace the `To` and `From` numbers with our Twilio numbers. 207 | 3. Replace the `Url` with the URL of our TwiML bin. 208 | 209 | It will be easier to edit the `curl` command if you copy it into a text editor. 210 | 211 | **To set your environment variables:** 212 | 213 | - Go to your [Twilio console](https://console.twilio.com), and check out account info. Copy the account SID and auth token. 214 | - Follow [this guide](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) to set those as environment variables in your shell, for MacOS, Linux, and Windows. 215 | 216 | **To replace the numbers:** 217 | 218 | - Set the `To` number to the Twilio phone number that you are using in the Dev Phone. NOT the number that we have used for the TwiML bin earlier in the week. 219 | - Set the `From` number to be the Twilio phone number that you have used for the TwiML bins in previous days. 220 | 221 | **To replace the URL:** 222 | 223 | - In day 2, we set up a TwiML bin to say "hello world" when we called our phone number. We can reuse that TwiML bin for our outbound call, so that when we phone someone, it will say "hello world". 224 | - In your [Twilio console](https://console.twilio.com), find the TwiML bin you created yesterday. At the top of the page, you will see a `url` field. Copy this URL. 225 | - Set the `Url` in our `curl` request to the TwiML bin URL. 226 | 227 | Once you've done those three things, our `curl` request is ready to go! 228 | 229 | ### Step 4: Make the request 230 | 231 | Make sure your Twilio Dev Phone is running and open it in your browser. In a new terminal, paste the edited `curl` command, and press enter. Your Dev Phone should ring and you should hear "hello world". 232 | 233 | ### Step 5: Daily challenge complete! Time to submit. 234 | 235 | Congratulations on completing the day 3 challenge! To submit, take a screenshot of your Dev Phone call log to show you received the call. 236 | 237 | ## Day 4: Setting up a web application with ngrok and webhooks. 238 | 239 | So far, we have used Twilio via TwiML bins and `curl`. That makes it really easy to experiment with the API or to complete small tasks, like forwarding a number, but at some point you might want to use Twilio in a bigger application. Over the next three days, we'll learn to use Twilio from a Node.js or Python web application. 240 | 241 | Today you will: 242 | 243 | - Set up a basic Node.js or Python web application. 244 | - Download ngrok to make the application accessible from the web. 245 | - Set up a Twilio webhook to the application. 246 | 247 | ### Step 1: Create a Node.js or Python web application 248 | 249 | Node.js `express` and Python `flask` are both great choices for web applications. Follow the guides below to create an application in whichever you prefer: 250 | 251 | - [Node.js](https://www.twilio.com/docs/usage/tutorials/how-to-set-up-your-node-js-and-express-development-environment) 252 | - [Python](https://www.twilio.com/docs/usage/tutorials/how-to-set-up-your-python-and-flask-development-environment) 253 | 254 | ### Step 2: Install ngrok 255 | 256 | To use Twilio with our web application, Twilio will have to be able to send a HTTP request to the application. 257 | 258 | When we create a web application on our own machine, it will use the `localhost` URL. This is a URL accessible only from the machine, usually for testing purposes, and so will be inaccessible to Twilio. We can expose our web applications to the internet, but it can be complicated, and insecure once we're done. `ngrok` is an easier way to expose our web applications to the internet, temporarily. 259 | 260 | If you followed the guides in step 1, you may have seen instructions to install `ngrok` already. Continue following those instructions. `ngrok` has recently made some changes in a newer version, if you experience any problems, check out [this guide](https://www.twilio.com/blog/using-ngrok-2022). 261 | 262 | ### Step 3: Set your Twilio webhook 263 | 264 | When you have installed and started `ngrok`, it will create a URL for your application. This is the URL that Twilio will be able to reach. 265 | 266 | We will use this URL to set what is called a "webhook". This is a HTTP request that Twilio will send in response to an event. For the rest of the week, we are going to be adding the ability to receive and reply to SMS messages to our application, so the event we will want to set a webhook for is when a new message is received. 267 | 268 | Go to your [Twilio console](https://console.twilio.com), and go to the settings for your Twilio number, in "Phone Numbers" -> "Manage" -> "Active numbers". Find the "Messaging" section, and look for the dropdown that says "When a message comes in". Select "Webhook", and insert your URL in the box. Save your settings. 269 | 270 | With your web application and ngrok running, if you now send a message to your Twilio number, you will see a request come from Twilio to your web app. This won't do anything yet, as we haven't written the code to handle the request. That's a job for tomorrow! 271 | 272 | ### Step 4: Daily challenge complete! Time to submit. 273 | 274 | Congratulations on completing day 4, high five! To submit, take a screenshot of your `ngrok` or application terminal showing the receipt of a request from Twilio. 275 | 276 | ## Day 5: Receiving SMS messages with our web application. 277 | 278 | The web application we created yesterday does not currently handle the webhook from Twilio. Today we will add a new endpoint to handle the webhook, and receive SMS messages. 279 | 280 | Today you will: 281 | 282 | - Add an endpoint to your web application to handle Twilio webhooks. 283 | - Handle a webhook containing an SMS message. 284 | - Send your first SMS from the Dev Phone. 285 | 286 | ### Step 1: Add a new endpoint 287 | 288 | The Twilio webhook will be a `POST` request, so we will need to add a handler for `POST` requests. The below tutorials contain code samples you can use for Node.js and Python: 289 | 290 | - [Node.js](https://www.twilio.com/blog/2017/10/how-to-receive-and-respond-to-a-text-message-with-node-js-express-and-twilio.html) 291 | - [Python](https://www.twilio.com/blog/2016/09/how-to-receive-and-respond-to-a-text-message-with-python-flask-and-twilio.html) 292 | 293 | In Node.js, the endpoint starts with: 294 | 295 | ``` 296 | app.post('/sms', (req, res) => { 297 | ``` 298 | 299 | In Python, it starts with: 300 | 301 | ``` 302 | @app.route('/sms', methods=['POST']) 303 | ``` 304 | 305 | Note the `/sms` in both versions. You will need to add `/sms` to the end of the URL in your webhook configuration for your phone number. 306 | 307 | ### Step 2: Getting the message contents 308 | 309 | Once you have added the `/sms` POST endpoint to your application, you will be able to receive POST requests. A POST request has a body that contains the information sent with the request. The request we are receiving is from Twilio, telling us about a message we have received. The body will contain information about that message. 310 | 311 | Let's get the sender and the message contents out of the request. Add the following to your `/sms` endpoint: 312 | 313 | **Node.js** 314 | 315 | ``` 316 | let number = req.body.From; 317 | let messageBody = req.body.Body; 318 | 319 | console.log(`Message from ${number}, containing ${messageBody}`); 320 | ``` 321 | 322 | **Python** 323 | 324 | ``` 325 | 326 | number = request.form['From'] 327 | message_body = request.form['Body'] 328 | 329 | print('Message from {}, with contents: {}'.format(number, message_body)) 330 | 331 | ``` 332 | 333 | These snippets get the information we're interested in our of the request object, and then print them to the terminal. 334 | 335 | ### Step 3: Send an SMS from the Dev Phone 336 | 337 | Make sure your web application is running without errors, that ngrok is started, and that your phone number in Twilio has the full ngrok URL ending with `/sms`. Then enter your Twilio number in Dev Phone, and send a message! 338 | 339 | In the terminal with the running web application, you should see output containing the sender number and the message body. 340 | 341 | ### Step 4: Daily challenge complete, time to submit! 342 | 343 | Congratulations on completing day 5! To submit the challenge, take a screenshot of your terminal showing the output of receiving a message. 344 | 345 | ## Day 6: Replying to SMS messages with our web application. 346 | 347 | Yesterday we pulled information out of a message we received. Today we will reply to the message! If you followed the linked tutorials yesterday, you may have already done this. If not, it will be a quick addition. 348 | 349 | Today you will: 350 | 351 | - Write TwiML to respond to a text message. 352 | - Return that TwiML in response to a webhook. 353 | - Receive your reply on the Dev Phone. 354 | 355 | ### Step 1: Writing a response 356 | 357 | **Node.js:** 358 | 359 | ``` 360 | 361 | // Start our TwiML response. 362 | const twiml = new MessagingResponse(); 363 | 364 | // Add a text message. 365 | const msg = twiml.message(`Hello ${name}, you sent ${messageBody}`); 366 | 367 | res.writeHead(200, {'Content-Type': 'text/xml'}); 368 | res.end(twiml.toString()); 369 | 370 | ``` 371 | 372 | **Python:** 373 | 374 | ``` 375 | 376 | resp = twiml.Response() 377 | resp.message('Hello {}, you said: {}'.format(number, message_body)) 378 | return str(resp) 379 | 380 | ``` 381 | 382 | ## Day 7: Deploy from the Twilio Code Exchange 383 | 384 | CodeExchange makes it easy to get started with any app. It’s a searchable directory of customizable code samples, written by developers around the world, vetted by Twilio experts, and ready for you to use. We can’t wait to see what you build using CodeExchange code samples. Go ahead and get started by checking it out now. Pick one of the Applications and deploy it to your Twilio account. 385 | [Twilio Code Exchange](https://www.twilio.com/code-exchange?q=&f=serverless). 386 | 387 | # Frequently Asked Questions 388 | 389 | ## I have an existing account with Twilio credit, what do I do? 390 | 391 | If that account is a trial account, using the upgrade code will replace your trial credit with $25 of real credit. If you have trial credit you want to use, it's recommended you use this before using the upgrade code. 392 | 393 | ## My Twilio account was suspended 394 | 395 | Please contact a Twilio team member in the Twilio channel in the GHW Discord. 396 | --------------------------------------------------------------------------------