Setting and modifying Headers and Cookies

You can 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 are also 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 can also set cookies using 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 can 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)

Calling appendHeader multiple times with the same header name

If Response.appendHeader is called with a header name that already exists, the header value is converted from a string to an array and the provided value is 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)

Commands are only available in Runtime Handler v1.2.0 or later

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?)`

Add a cookie to your Function's response with this method. 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)

Cookie attributes

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)`

Use this method to remove a specific cookie from the Function response. 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. After the client receives this response, it removes tz from its cookie store and no longer sends the cookie 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};

Next steps

Now that you know 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.