Skip to contentSkip to navigationSkip to topbar
On this page

twilio/card


The twilio/card content type is a structured template that lets you send a set of related items in a single message. Each card must include either a title or a body plus one additional field.

In the media field of the template, provide the URL of a publicly hosted file.

If you use media with a variable, include a sample path to a publicly hosted image URL in the variables object. The final URL must include the file type and must resolve to a publicly accessible file.

For example:

1
"media": ["https://twilio-cms-prod.s3.amazonaws.com/{{1}}"],
2
"variables": { "1": "images/library-logo-resource2x.width-1000.png" }

If you use a call-to-action URL button, the URL must resolve to a publicly accessible website. When the URL contains a variable, provide a valid sample path in the variables object so the combined URL resolves correctly.

For example:

1
"url": ["https://www.twilio.com/{{1}}"],
2
"variables": { "1": "docs" }

Supported channels

supported-channels page anchor
  • RCS
  • WhatsApp
  • Facebook Messenger

Channel-specific information

channel-specific-information page anchor

RCS

rcs page anchor

Webviews

webviews page anchor

Webviews can work with the Google Wallet API to deliver boarding passes. See the Google Wallet documentation for boarding passes(link takes you to an external page).

Chip list versus rich card

chip-list-versus-rich-card page anchor

Pricing and how twilio renders buttons depends on whether media is present and how many buttons are defined.

Default behavior if media is present ``

  • More than four buttons: The first four buttons appear in the card. Remaining buttons appear in a chip list.
  • Four or fewer buttons: RCS uses a rich card.
Default behavior if media is not present
default-behavior-if-media-is-not-present page anchor
  • RCS uses a chip list.
Differences in RCS resolution
differences-in-rcs-resolution page anchor
Type of MessagePricingAllowed Twilio data parametersPricing Length Limits
Chip ListRich (USA)Either Title or Body. Cannot contain both. URL & Dial CTA buttons except Webviews.Text messages up to 160 UTF-8 characters, including quick replies (chip lists), URL & Dial CTA buttons except webviews.
Chip ListSingle Message (Global except USA)Either Title or Body. Cannot contain both. All button types allowed in RCS.Length limits within data parameters section.
Rich CardRich Media (USA)Title, media, body, and subtitle. All button types allowed in RCS.Length limits within data parameters section.
Rich CardSingle Message (Global except USA)Title, media, body, and subtitle. All button types allowed in RCS.Length limits within data parameters section.
  • VOICE_CALL is in private beta in select regions.
  • When you send a card in-session without prior approval, WhatsApp allows a maximum of three buttons.
  • A card must be approved as a template before it can be sent outside the 24-hour conversation window. If the card uses variables or media, submit a valid sample with the template. Static media URLs must resolve to publicly hosted files. Variable media URLs must include a valid media URL suffix in the variable declaration.
  • A template approved with one media type (Image, Video, or Document) can send only that media type. For example, a template approved with an image header cannot later send a video.
  • If the body starts or ends with a variable, or contains adjacent variables, WhatsApp requires a sample variable. See Using variables with Content API.
  • Update the phone number in the sample actions array to a valid E.164-formatted number before sending the template.
  • WhatsApp footers map to subtitles in twilio/card.
  • Template approval is required when a card contains multiple buttons.
  • Button titles are limited to 20 characters.

Card content template preview 1.
Card content template preview 2.

ParameterTypeRequiredVariable supportDescription
titlestringNoYesTitle of the card.
Maximum length: 1,024 characters.
Required if body is not specified.
If both title and body are specified, the title is limited to 200 characters.
bodystringNoYesBody text of the card.
Maximum length: 2,000 characters.
Required if title is not specified.
subtitlestringNoNoSubtitle of the card.
Maximum length: 60 characters.
mediastring[]NoYesPublic URL of the media to send.
See Accepted content types for media (MMS) and WhatsApp media types.
actionsarrayNoYesDefines buttons that appear on the card.

For an overview of shared button properties, see Common components.

(information)

Info

WhatsApp limitations

  • Only one of the two call options can appear on a template: PHONE or VOICE_CALL.
  • Up to 2 URL buttons are allowed.
  • Up to 10 quick-reply buttons are allowed.
  • A maximum of 10 buttons is allowed per card.

RCS limitations

  • Up to 11 buttons can appear in a chip list.
  • Up to 4 buttons can appear in the rich card itself.
PropertySupported channelsParameters
QUICK_REPLYRCS, WhatsApp, Facebook Messengertype: QUICK_REPLY
title: Text shown on the button. Appears in the Body and ButtonText fields in inbound messages. Variables are supported in-session.
Maximum length: 20 characters.
id: Identifier returned in the ButtonPayload field of inbound messages. Not visible to the user. Variables are supported.
URLRCS, WhatsApp, Facebook Messengertype: URL
title: Text shown on the button. Variables are supported in RCS and for WhatsApp in-session.
Maximum length: 25 characters.
id: (RCS only) Identifier returned in the ButtonPayload field of inbound messages. Variables are supported.
url: URL opened when the user taps the button. Variables are supported at the end of the URL string for WhatsApp outside a 24-hour window and for RCS in-session.
webview_size (RCS only): Controls whether the URL opens in a webview or the device browser. Valid values: NONE, HALF, TALL, FULL. Default is NONE.
PHONE_NUMBERRCS, WhatsApp, Facebook Messengertype: PHONE_NUMBER
title: Text shown on the button. Variables are not supported.
Maximum length: 25 characters.
phone: E.164-formatted number to call when the user taps the button.
VOICE_CALLWhatsApptype: VOICE_CALL
title: Text shown on the VoIP call button. Variables are not supported.
Maximum length: 25 characters.
ttl_minutes: Optional. Lifespan of the button in minutes (default: 10,080 minutes = 7 days). Accepts an integer from 1 to 43,200 (30 days). Variables are supported.
COPY_CODEWhatsApptype: COPY_CODE
title: The button text is translated automatically to the user's language. Variables are not supported.
Maximum length: 25 characters.
code: Coupon code copied to the user's clipboard when the button is tapped. Variables are supported.

Create a card templateLink to code sample: Create a card template
1
// Install the C# / .NET helper library from twilio.com/docs/csharp/install
2
3
using System;
4
using Twilio;
5
using Twilio.Rest.Content.V1;
6
7
TwilioClient.Init(accountSid, authToken);
8
9
// define the twilio/text type for less rich channels (e.g. SMS)
10
var twilioText = new TwilioText.Builder();
11
twilioText.WithBody("Hi {{1}}. Thanks for contacting Owl Air Support. How can we help?");
12
13
// define the twilio/card type for more rich channels
14
var twilioCard = new TwilioCard.Builder();
15
twilioCard.WithTitle("Owl Air Support");
16
var cardAction1 = new CardAction.Builder()
17
.WithType(CardActionType.Url)
18
.WithUrl("https://www.twilio.com")
19
.WithTitle("Contact Us")
20
.Build();
21
twilioCard.WithActions(new List<CardAction>() { cardAction1 });
22
23
// define all the content types to be part of the template
24
var types = new Types.Builder();
25
types.WithTwilioText(twilioText.Build());
26
types.WithTwilioCard(twilioCard.Build());
27
28
// build the create request object
29
var contentCreateRequest = new ContentCreateRequest.Builder();
30
contentCreateRequest.WithTypes(types.Build());
31
contentCreateRequest.WithLanguage("en");
32
contentCreateRequest.WithFriendlyName("owl_air_card");
33
contentCreateRequest.WithVariables(new Dictionary<string, string>() { {"1", "John"} });
34
35
// create the twilio template
36
var contentTemplate = await CreateAsync(contentCreateRequest.Build());
37
38
Console.WriteLine($"Created Twilio Content Template SID: {contentTemplate.Sid}");

Output

1
{
2
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
"date_created": "2022-08-30T09:19:17Z",
4
"date_updated": "2022-08-30T09:19:17Z",
5
"friendly_name": "owl_air_card",
6
"language": "en",
7
"links": {
8
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
10
},
11
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
"types": {
13
"twilio/card": {
14
"actions": [
15
{
16
"title": "Order Online",
17
"type": "URL",
18
"url": "https://www.owlair.com/"
19
},
20
{
21
"phone_number": "+15551234567",
22
"title": "Call Us",
23
"type": "PHONE_NUMBER"
24
}
25
],
26
"body": null,
27
"media": null,
28
"subtitle": "To unsubscribe, reply Stop",
29
"title": "Congratulations, you have reached Elite status! Add code {{1}} for 10% off."
30
},
31
"twilio/text": {
32
"body": "Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out."
33
}
34
},
35
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
36
"variables": {
37
"1": "coupon_code"
38
}
39
}

ComponentDescription
ButtonPaylodID specified in button to identify specific button click. If no ID is specified button text will be in this field.
ButtonTypeWhether the button pressed was a quick reply or call to action button.
ButtonTextText of button clicked.