Skip to contentSkip to navigationSkip to topbar
Page toolsOn this page
Looking for more inspiration?Visit the

Send SMS and MMS


All Functions execute with a pre-initialized instance of the Twilio Node.js SDK available for use. This means you can access and utilize any Twilio SDK method in your Function. For example, sending SMS via Twilio's Programmable SMS from a Function is incredibly accessible, as we'll show in the following example snippets.

These examples are not exhaustive, and we encourage you to peruse the Programmable SMS tutorials for more inspiration on what you can build.


Prerequisites

prerequisites page anchor

Before you start, be sure to complete the following prerequisites. You can skip to "Create and host a Function" if you've already completed these steps and need to know more about Function deployment and invocation, or you can skip all the way to "Send a single SMS" if you're all ready to go and want to get straight to the code.


Create and host a Function

create-and-host-a-function page anchor

Before you run any of the examples on this page, create a Function and paste the example code into it. You can create a Function in the Twilio Console or by using the Serverless Toolkit.

ConsoleServerless Toolkit

If you prefer a UI-driven approach, complete these steps in the Twilio Console:

  1. Log in to the Twilio Console(link takes you to an external page) and navigate to Develop > Functions & Assets. If you're using the legacy Console, open the Functions tab(link takes you to an external page).
  2. Functions are contained within Services. Click Create Service(link takes you to an external page) to create a new Service.
  3. Click Add + and select Add Function from the dropdown.
  4. The Console creates a new protected Function that you can rename. The filename becomes the URL path of the Function.
  5. Copy one of the example code snippets from this page and paste the code into your newly created Function. You can switch examples by using the dropdown menu in the code rail.
  6. Click Save.
  7. Click Deploy All to build and deploy the Function. After deployment, you can access your Function at https://<service-name>-<random-characters>-<optional-domain-suffix>.twil.io/<function-path>
    For example: test-function-3548.twil.io/hello-world.

You can now invoke your Function with HTTP requests, configure it as the webhook for a Twilio phone number, call it from a Twilio Studio Run Function Widget, and more.


How to invoke your Function

how-to-invoke-your-function page anchor

Functions that you create in the UI are protected by default. Set Functions that you deploy with the Serverless Toolkit to protected as well by adding "protected" before the file extension, for example, "send-sms.protected.js". This configuration helps secure your Function and prevents unauthorized access. However, it also adds an extra step when you want to invoke and test the Function manually, as shown in the examples on this page.

To call a protected Function, provide a valid X-Twilio-Signature header in the request. See the documentation for details about the request-validation process.

Generate a valid X-Twilio-Signature header

generate-a-valid-x-twilio-signature-header page anchor

Though you can generate the header manually with HMAC-SHA1, use the convenience utilities exported by Twilio's SDKs instead. Download the SDK for your preferred language from the libraries page.

After you install the SDK, complete these steps:

  1. Set your Auth Token as an environment variable.
  2. If you use the Node.js example, update the request URL to reference your Service and any query parameters you plan to pass. For other languages, see the examples here.
  3. Run the script and copy the generated X-Twilio-Signature value for use in the next step.

The following sections show how to generate a signature for a POST request with a JSON body and for a GET request that passes data as query parameters:

With a JSON bodyWith Query Parameters
1
const { getExpectedTwilioSignature } = require('twilio/lib/webhooks/webhooks');
2
3
// Retrieve your auth token from the environment instead of hardcoding
4
const authToken = process.env.TWILIO_AUTH_TOKEN;
5
6
// Use the Twilio helper to generate your valid signature!
7
// The 1st argument is your Twilio auth token.
8
// The 2nd is the full URL of your Function.
9
// The 3rd is any application/x-www-form-urlencoded data being sent, which is none!
10
const xTwilioSignature = getExpectedTwilioSignature(
11
authToken,
12
'https://example-4321.twil.io/sms/send',
13
{} // <- Leave this empty if sending request data via JSON
14
);
15
16
// Print the signature to the console for use with your
17
// preferred HTTP client
18
console.log('xTwilioSignature: ', xTwilioSignature);
19
20
// For example, the output will look like this:
21
// xTwilioSignature: coGTEaFEMv8ejgNGtgtUsbL8r7c=

Create a valid request

After you generate a valid X-Twilio-Signature value, include it as a header in the request to your Function. You can use tools such as curl(link takes you to an external page) or Postman(link takes you to an external page). Make sure to do the following:

  • Set the full URL of the Function, including the root of your Service and the full path to the deployed Function.
  • Set the X-Twilio-Signature header and content type header (application/json) for your request.
  • Define the JSON body that you're sending to the Function

Using curl, the request looks like this:

1
curl -X POST 'http://test-4321.twil.io/sms/send' \
2
-H 'X-Twilio-Signature: coGTEaFEMv8ejgNGtgtUsbL8r7c=' \
3
-H 'Content-Type: application/json' \
4
--data-raw '{
5
"Body": "Hello, there!"
6
}'

(warning)

Twilio credentials required

For any Function using the built-in Twilio client, the "Add my Twilio Credentials (ACCOUNT_SID) and (AUTH_TOKEN) to ENV" option on the Settings > Environment Variables tab must be enabled.

You can use a Function to send a single SMS from your Twilio phone number via Twilio's Programmable SMS. The To, From, and Body parameters of your message must be specified to successfully send.

You'll tell Twilio which phone number to use to send this message by either providing a From value in your request, or by omitting it and replacing the placeholder default value in the example code with your own Twilio phone number.

Next, specify yourself as the message recipient by either providing a To value in your request, or by omitting it and replacing the default value in the example code with your personal number. The resulting from and to values both must use E.164 formatting ("+" and a country code, e.g., +16175551212).

Finally, the body value determines the contents of the SMS that is being sent. As with the other values, either pass in a Body value in your request to this Function or override the default in the example to your own custom message.

Once you've made any modifications to the sample and have deployed your Function for testing, go ahead and make some test HTTP requests against it. Example code for invoking your Function is described earlier in this document.

Send a single SMS

send-a-single-sms-1 page anchor
1
exports.handler = function (context, event, callback) {
2
// The pre-initialized Twilio client is available from the `context` object
3
const twilioClient = context.getTwilioClient();
4
5
// Query parameters or values sent in a POST body can be accessed from `event`
6
const from = event.From || '+15017122661';
7
const to = event.To || '+15558675310';
8
const body = event.Body || 'Ahoy, World!';
9
10
// Use `messages.create` to generate a message. Be sure to chain with `then`
11
// and `catch` to properly handle the promise and call `callback` _after_ the
12
// message is sent successfully!
13
twilioClient.messages
14
.create({ body, to, from })
15
.then((message) => {
16
console.log('SMS successfully sent');
17
console.log(message.sid);
18
// Make sure to only call `callback` once everything is finished, and to pass
19
// null as the first parameter to signal successful execution.
20
return callback(null, `Success! Message SID: ${message.sid}`);
21
})
22
.catch((error) => {
23
console.error(error);
24
return callback(error);
25
});
26
};

You are not limited to sending a single SMS in a Function. For example, suppose you have a list of users to send messages to at the same time. As long as the list is reasonably short to avoid hitting rate limiting (see Messaging Services for how to send high volume messages), you can execute multiple, parallel calls to create a message and await the result in a Function as shown in the example below:

1
// Note: Since we're using the `await` keyword in this Function, it must be declared as `async`
2
exports.handler = async function (context, event, callback) {
3
// The pre-initialized Twilio client is available from the `context` object
4
const twilioClient = context.getTwilioClient();
5
6
// In this example the messages are inlined. They could also be retrieved from
7
// a private Asset, an API call, a call to a database, etc to name some options.
8
const groupMessages = [
9
{
10
name: 'Person1',
11
to: '+15105550100',
12
body: 'Hello Alan',
13
from: '+15095550100',
14
},
15
{
16
name: 'Person2',
17
to: '+15105550101',
18
body: 'Hello Winston',
19
from: '+15095550100',
20
},
21
{
22
name: 'Person3',
23
to: '+15105550102',
24
body: 'Hello Deepa',
25
from: '+15095550100',
26
},
27
];
28
29
try {
30
// Create an array of message promises with `.map`, and await them all in
31
// parallel using `Promise.all`. Be sure to use the `await` keyword to wait
32
// for the promises to all finish before attempting to log or exit!
33
const results = await Promise.all(
34
groupMessages.map((message) => twilioClient.messages.create(message))
35
);
36
results.forEach((result) => console.log(`Success: ${result.sid}`));
37
// Make sure to only call `callback` once everything is finished, and to pass
38
// null as the first parameter to signal successful execution.
39
return callback(null, 'Batch SMS Successful');
40
} catch (error) {
41
console.error(error);
42
return callback(error);
43
}
44
};

Include MMS in a message

include-mms-in-a-message page anchor

Media, such as images, can be included in your text messages by adding the mediaUrl parameter to the call to client.messages.create. This can either be a single string to a publicly accessible URL or an array of multiple media URLs.

1
exports.handler = function (context, event, callback) {
2
// The pre-initialized Twilio client is available from the `context` object
3
const twilioClient = context.getTwilioClient();
4
5
// Query parameters or values sent in a POST body can be accessed from `event`
6
const from = event.From || '+15017122661';
7
const to = event.To || '+15558675310';
8
const body = event.Body || 'This is the ship that made the Kessel Run in fourteen parsecs?';
9
// Note that the `mediaUrl` value may be a single string, or an array of strings
10
const mediaUrl = event.mediaUrl || 'https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg';
11
12
// Use `messages.create` to generate a message. Be sure to chain with `then`
13
// and `catch` to properly handle the promise and call `callback` _after_ the
14
// message is sent successfully!
15
// Note the addition of the `mediaUrl` value as configuration for `messages.create`.
16
twilioClient.messages
17
.create({ body, to, from, mediaUrl })
18
.then((message) => {
19
console.log('MMS successfully sent');
20
console.log(message.sid);
21
// Make sure to only call `callback` once everything is finished, and to pass
22
// null as the first parameter to signal successful execution.
23
return callback(null, `Success! Message SID: ${message.sid}`);
24
})
25
.catch((error) => {
26
console.error(error);
27
return callback(error);
28
});
29
};