Make a request to an external API
At some point in your application development process, you may find yourself wanting to include dynamic or external data in your responses to users or as part of your application logic. A common way to incorporate this into your application is by making requests to APIs and processing their responses.
There are as many potential use cases as there are developers, so we can't possibly document every possible situation. Instead, we'll provide you with some examples and useful strategies that we've found over the years for making API calls in your Functions.
There are a wide variety of npm modules available for making HTTP requests to external APIs, including but not limited to:
For the sake of consistency, all examples will use axios, but the same principles will apply to any HTTP request library. These examples are written assuming that a customer is calling your Twilio phone number and expecting a voice response, but these same concepts apply to any application type.
Create and host a Function
In order to run any of the following examples, you will first need to create a Function into which you can paste the example code. You can create a Function using the Twilio Console or the Serverless Toolkit as explained below:
If you prefer a UI-driven approach, creating and deploying a Function can be done entirely using the Twilio Console and the following steps:
- Log in to the Twilio Console and navigate to the Functions tab. If you need an account, you can sign up for a free Twilio account here!
- Functions are contained within Services. Create a Service by clicking the Create Service button and providing a name such as test-function.
- Once you've been redirected to the new Service, click the Add + button and select Add Function from the dropdown.
- This will create a new Protected Function for you with the option to rename it. The name of the file will be path it is accessed from.
- Copy any one of the example code snippets from this page that you want to experiment with, and paste the code into your newly created Function. You can quickly switch examples by using the dropdown menu of the code rail.
- Click Save to save your Function's contents.
- Click Deploy All to build and deploy the Function. After a short delay, your Function will be accesible from:
https://<service-name>-<random-characters>-<optional-domain-suffix>.twil.io/<function-path>
For example:test-function-3548.twil.io/hello-world.
The Serverless Toolkit enables you with local development, project deployment, and other functionality via the Twilio CLI. To get up and running with these examples using Serverless Toolkit, follow this process:
- From the CLI, run
twilio serverless:init <your-service-name> --emptyto bootstrap your local environment. - Navigate into your new project directory using
cd <your-service-name> - In the
/functionsdirectory, create a new JavaScript file that is named respective to the purpose of the Function. For example,sms-reply.protected.jsfor a Protected Function intended to handle incoming SMS. - Populate the file using the code example of your choice and save.
Note A Function can only export a single handler. You will want to create separate files if you want to run and/or deploy multiple examples at once.
Once your Function(s) code is written and saved, you can test it either by running it locally (and optionally tunneling requests to it via a tool like ngrok), or by deploying the Function and executing against the deployed url(s).
Run your Function in local development
Run twilio serverless:start from your CLI to start the project locally. The Function(s) in your project will be accesible from http://localhost:3000/sms-reply
- If you want to test a Function as a Twilio webhook, run:
twilio phone-numbers:update <your Twilio phone number> --sms-url "http://localhost:3000/sms-reply"
This will automatically generate an ngrok tunnel from Twilio to your locally running Function, so you can start sending texts to it. You can apply the same process but with thevoice-urlflag instead if you want to test with Twilio Voice. - If your code does not connect to Twilio Voice/Messages as a webhook, you can start your dev server and start an ngrok tunnel in the same command with the
ngrokflag. For example:twilio serverless:start --ngrok=""
Deploy your Function
To deploy your Function and have access to live url(s), run twilio serverless:deploy from your CLI. This will deploy your Function(s) to Twilio under a development environment by default, where they can be accessed from:
https://<service-name>-<random-characters>-dev.twil.io/<function-path>
For example: https://incoming-sms-examples-3421-dev.twil.io/sms-reply
Your Function is now ready to be invoked by HTTP requests, set as the webhook of a Twilio phone number, invoked by a Twilio Studio Run Function Widget, and more!
Set a Function as a webhook
In order for your Function to react to incoming SMS and/or voice calls, it must be set as a webhook for your Twilio number. There are a variety of methods to set a Function as a webhook, as detailed below:
You can use the Twilio Console UI as a straigforward way of connecting your Function as a webhook:
- Log in to the Twilio Console's Phone Numbers page.
- Click on the phone number you'd like to have connected to your Function.
- If you want the Function to respond to incoming SMS, find the A Message Comes In option under Messaging. If you want the Function to respond to Voice, find the A Call Comes In option under Voice & Fax.
- Select Function from the A Message Comes In or A Call Comes In dropdown.
- Select the Service that you are using, then the Environment (this will default to
uiunless you have created custom domains), and finally Function Path of your Function from the respective dropdown menus.
- Alternatively, you could select Webhook instead of Function, and directly paste in the full URL of the Function.
- Alternatively, you could select Webhook instead of Function, and directly paste in the full URL of the Function.
- Click the Save button.
You can also use the Twilio CLI to assign the Function as the webhook of you phone number. You will need a few prerequisites:
- Twilio CLI installed and executable from your terminal.
- Either the E.164 formatted value of your Twilio phone number (
+1234567890), or its SID (PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX). - The full URL of your Function (
https://test-1337.twil.io/my-test-function)
Once you have the CLI installed and the necessary information, run the following to connect the Function to respond to incoming SMS:
twilio phone-numbers:update +1234567890 \
--sms-url https://test-1337.twil.io/my-test-functionIf you prefer to have the Function respond to incoming calls instead, run:
twilio phone-numbers:update +1234567890 \
--voice-url https://test-1337.twil.io/my-test-functionYou may also use the SID of your Twilio phone number instead of the E.164 formatted phone number:
twilio phone-numbers:update PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
--sms-url https://test-1337.twil.io/my-test-functionYou can also use any of the avilable Twilio SDKs to assign the Function as the webhook of you phone number. You will need a few prerequisites:
- A local development environment for your language of choice and the associated Twilio SDK installed.
- The SID (
PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) of your Twilio phone number. - The full URL of your Function (
https://test-1337.twil.io/my-test-function).
In JavaScript for example, you could execute the following code to assign the SMS webhook of your Twilio phone number. The same logic would apply for assigining to a voice webhook, except that the modified property instead would be voiceUrl:
// Download the helper library from https://www.twilio.com/docs/node/install
// Find your Account SID and Auth Token at twilio.com/console
// and set the environment variables. See http://twil.io/secure
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = require('twilio')(accountSid, authToken);
client
.incomingPhoneNumbers('PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
.update({ smsUrl: 'https://test-1337.twil.io/my-test-function' })
.then((phoneNumber) => console.log(phoneNumber.smsUrl));
Make a single API request
Before you can make an API request, you'll need to install axios as a Dependency for your Function. Once axios is installed, copy the following code snippet and paste it as the body of a new, public Function, such as /astro-info. Be sure to use the instructions above to connect this Function as the webhook for incoming calls to your Twilio phone number.
This code is:
- Initializing a TwiML Voice Response, for speaking back to the incoming caller
- Using
axiosto perform an API request to theastrosendpoint, which will return the number of people currently in space, and a list of their names - Performing some operations on the data returned by the API, such as isolating the names into a sorted list, and preparing an Intl.ListFormat object for formatting the names
- Generating the message to be returned to the caller, and returning it
- All of this is wrapped in a try/catch block to handle any exceptions, such as a connection error that could be thrown by the API
There are some key points to keep in mind.
Making an HTTP request to an API is what we call an asynchronous operation, meaning the response from the API will come back to us at a later point in time, and that we're free to use computing resources on other tasks in the meantime. Calling axios in this code sample creates a Promise, which will ultimately resolve as the data we want, or reject and throw an exception.
The MDN has an excellent series that introduces asynchronous JavaScript and related concepts.
Note that we've declared this Function as async. This means that we can leverage the await keyword and structure our code in a very readable, sequential manner. The request is still fundamentally a Promise, but we can treat it almost like synchronous code without the need for callback hell or lengthy then chains. You can learn more about this async/await syntax at the MDN.
The other key point is that our code only ever calls callback once our code has successfully completed or if an error has occurred. If the await keyword was removed or we otherwise didn't wait for the API call to complete before invoking the callback method, this would result in incorrect behavior. If we never invoke callback, the Function will run until the 10-second execution limit is reached, resulting in an error and the customer never receiving a response.
Make sequential API requests
Another common situation you may encounter is the need to make one API request, and then a subsequent request which is dependent on having data from the first request. By properly handling Promises in order, and ensuring that callback is not invoked before our requests have finished, you can make any number of sequential requests in your Function as necessary for your use-case (while also keeping in mind that the Function has 10 seconds to complete all requests).
Similar to the previous example, copy the following code snippet and paste it as the body of a new, public Function, such as /detailed-astro-info. In addition, you will need to install the qs module as a Dependency so that we can make an API request that includes search parameters. Also, for the text messaging to work, you'll need to set your Twilio phone number as an environment variable titled TWILIO_PHONE_NUMBER.
This code is:
- Initializing a TwiML Voice Response, for speaking back to the incoming caller
- Using
axiosto perform an API request to theastrosendpoint, which will return the number of people currently in space, and a list of their names - Performing some operations on the data, and randomly selecting one of the astronaut names
- Performing a second API request. This time, querying Wikipedia for any articles about the astronaut, with their name as the search term.
- Generating the message to be returned to the caller, sending the caller a text message containing a Wikipedia article (if one is found), and returning the voice message to the caller
- All of this is wrapped in a try/catch block to handle any exceptions, such as a connection error that could be thrown by either API
Make parallel API requests
Frequently in applications, we also run into situations where we could make a series of requests one after another, but we can deliver a better and faster experience to users if we perform some requests at the same time.
We can accomplish this in JavaScript by initiating multiple requests, and awaiting their results in parallel using a built-in method, such as Promise.all.
To get started, copy the following code snippet and paste it as the body of a new, public Function, such as /space-info.
In addition to the axios and qs dependencies installed for previous examples, you will want to get a free API key from positionstack. This will enable you to perform reverse geolocation on the International Space Station or ISS. Set the value of the API key to an environment variable named POSITIONSTACK_API_KEY.
This code is:
- Initializing a TwiML Voice Response, for speaking back to the incoming caller
- Using
axiosto create two requests to the Open Notify API, one for astronaut information and the other for information about the ISS's location, and storing references to the resulting Promises. awaiting the result of both requests simultaneously usingPromise.all- Performing a second API request, this time to convert the latitude and longitude of the ISS into a human-readable location on earth, such as "North Pacific Ocean"
- Generating the message to be returned to the caller based on all of the data gathered so far, and returning the voice message to the caller
- All of this is wrapped in a try/catch block to handle any exceptions, such as a connection error that could be thrown by any of the APIs
Make a write request to an external API
Just as you may need to request data in your Serverless applications, there are numerous reasons why you may want to send data to external APIs. Perhaps your Function responds to incoming text messages from customers, and attempts to update an internal record about that customer by sending data to an API that manages customer records. Maybe your Function serves as a means to push messages on to a queue, like SQS, so that some other microservice can handle clearing out that queue.
Regardless of the use case, you are free to make write requests to external APIs from your Functions (assuming you have permissions to do so from the API). There are no restrictions imposed on this by Runtime itself.
Depending on the scenario, making a write request will mostly consist of using the same principles from the above examples, but using HTTP verbs such as POST and PUT instead of GET.
The below example demonstrates a simple use case where a Function:
- Receives an incoming text message
- Derives an identifier from the incoming phone number
- Retrieves a record from an API, based on the derived ID
- Writes an update to that API, and responds to the sender once all operations are complete
Make a write request in other formats
Some APIs may not accept write requests that are formatted using JSON (Content-Type: application/json). The approach to handling this situation varies depending on the expected Content-Type and which HTTP library you are using.
One example of a common alternative, which you'll encounter when using some of Twilio's APIs without the aid of a helper library, is Content-Type: application/x-www-form-urlencoded. As detailed in the axios documentation and shown in the example below, this requires some slight modifications to the data that you send, the Headers attached to the request, or a combination of both.
Handling unstable APIs
API requests aren't always successful. Sometimes the API's server may be under too much load and unable to handle your request, or something simply happened to go wrong with the connection between your server and the API.
A standard approach to this situation is to retry the same request but after a delay. If that fails, subsequent retries are performed but with increasing amounts of delay (also known as exponential backoff). You could implement this yourself, or use a module such as p-retry to handle this logic for you. This behavior is also built into got by default.
To see this more explicitly configured, the following code examples implement some previous examples, but while utilizing an unstable API that only sometimes successfully returns the desired data.
V5 and newer versions of p-retry are exported as ES Modules, and Functions currently do not support the necessary import syntax. To utilize p-retry (or any other ES Module package) in the meantime, you will need to import it using dynamic import syntax inside of your handler method, as highlighted in the following examples.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
