Setting and modifying Headers and Cookies

It is also possible to set headers and cookies on the response that your Twilio Function returns. The Response object exposes the following methods to allow you to customize what headers are sent in response to incoming requests.

Headers

`setHeaders(headers)`

This method allows you to set multiple headers in a single command. It accepts an object of key-value pairs of headers and their corresponding values. You may also set multi-value headers by making the intended header an array.

If you include the Set-Cookie header in this object, cookies will also be set to that value in addition to any other changes. Cookies must be strings with the key and value delimited by an = sign, such as 'Key=Value' or as a list of values such as [‘Key=Value', ‘Agent=Smith'].

Method Parameters

Name	Type
headers	`Object<string, string \| string[]>`

Examples

1exports.handler = (context, event, callback) => {
2  const response = new Twilio.Response();
3  response.setHeaders({
4    // Set a single header
5    'content-type': 'application/json',
6    // You can set a header with multiple values by providing an array
7    'cache-control': ['no-cache', 'private'],
8    // You may also optionally set cookies via the "Set-Cookie" key
9    'set-cookie': 'Foo=Bar',
10  });
11
12  return callback(null, response);
13};

1exports.handler = (context, event, callback) => {
2  const response = new Twilio.Response();
3  response.setHeaders({
4    // You may also set cookie attributes by including a semicolon
5    // (`;`) delimited list of attributes
6    'set-cookie': ['Foo=Bar;Max-Age=86400', 'Agent=Smith;HttpOnly;Secure'],
7  });
8
9  return callback(null, response);
10};

`appendHeader(key, value)`

This method allows you to add a single header to the response. It accepts the name of the header and its intended value.

(information)

Info

If Response.appendHeader is called with the name of a header that already exists, that header will be converted from a string to an array, and the provided value will be concatenated to that array of values.

Method Parameters

Name	Type	Example
key	`string`	`'content-type'`
value	`string \| string[]`	`'application/json'`

Examples

1exports.handler = (context, event, callback) => {
2  const response = new Twilio.Response();
3  response
4    .appendHeader('content-type', 'application/json')
5    // You can append a multi-value header by passing a list of strings
6    .appendHeader('yes', ['no', 'maybe', 'so'])
7    // Instead of setting the header to an array, it's also valid to
8    // pass a comma-separated string of values
9    .appendHeader('cache-control', 'no-store, max-age=0');
10
11  return callback(null, response);
12};

1exports.handler = (context, event, callback) => {
2  const response = new Twilio.Response();
3  response
4    .appendHeader('never', 'gonna')
5    // Appending a header that already exists will convert that header to
6    // a multi-value header and concatenate the new value
7    .appendHeader('never', 'give')
8    .appendHeader('never', 'you')
9    .appendHeader('never', 'up');
10    // The header is now `'never': ['gonna', 'give', 'you', 'up']`
11
12  return callback(null, response);
13};

Cookies

(information)

Info

Commands to set, modify, and delete cookies are only available when your Function is running @twilio/runtime-handler version 1.2.0 or later. Consult the Runtime Handler guide to learn more about the latest version and how to update.

`setCookie(key, value, attributes?)`

This method allows you to add a cookie to your Function's response. It accepts the name of the cookie, its value, and any optional attributes to be assigned to the cookie.

Method Parameters

Name	Type	Example
key	`string`	`'tz'`
value	`string \| string[]`	`'America/Los_Angeles'`
attributes (optional)	`string[]?`	`['HttpOnly', 'Secure', 'SameSite=Strict', 'Max-Age=86400']`

Examples

1exports.handler = (context, event, callback) => {
2  const response = new Twilio.Response();
3  response
4    .setCookie('has_recent_activity', 'true')
5    .setCookie('tz', 'America/Los_Angeles', [
6      'HttpOnly',
7      'Secure',
8      'SameSite=Strict',
9      'Max-Age=86400',
10    ]);
11
12  return callback(null, response);
13};

(information)

Info

Cookie attributes such as HttpOnly and Secure are shown in these examples, however, you don't need to add them yourself. Runtime automatically adds the HttpOnly and Secure attributes to your cookies by default unless you have already manually set those values.

If you do not set a Max-Age or Expires on a cookie, it will be considered a Session cookie. If you set both Max-Age and Expires on a cookie, Max-Age takes precedence.

(error)

Danger

If you set the Max-Age or Expires of a cookie to greater than 24 hours, your Function will return a 400 error: Cookies max-age cannot be greater than a day.

`removeCookie(key)`

This method allows you to effectively remove a specific cookie from the response of your Twilio Function. It accepts the name of the cookie to be removed, and sets the Max-Age attribute of the cookie equal to 0 so that clients and browsers will remove the cookie upon receiving the response.

Method Parameters

Name	Type	Example
key	`string`	`'tz'`

Examples

In the following example, the client may contain a cookie tz and send it along with the request. Upon receiving this response from your Function, tz will be removed from the client's cookie store and not sent with subsequent requests to your Function's domain.

1exports.handler = (context, event, callback) => {
2  const response = new Twilio.Response();
3  response.removeCookie('tz');
4
5  return callback(null, response);
6};

What's next?

Now that you more about how to set and modify the headers in your Function responses, let's go over some of the limitations on headers and cookies so that you don't encounter as many errors.