---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/content/twiliocard#article
headline: twilio/card
description: Learn how to define and send a twilio/card content template, including required fields, supported channels, limitations, and data parameters.
url: https://www.twilio.com/docs/content/twiliocard
inLanguage: en
dateModified: 2026-07-31T17:08:38.000Z
author:
"@type": Organization
name: Twilio Developer Education Team
publisher:
"@type": Organization
name: Twilio
---
# 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, **and at least 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:
```json
"media": ["https://www.example.com/{{1}}"],
"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:
```json
"url": ["https://www.twilio.com/{{1}}"],
"variables": { "1": "docs" }
```
## Supported channels
* RCS
* WhatsApp
* Facebook Messenger
## Channel-specific information
### RCS
#### Parameter mapping
To determine how RCS elements correspond to Twilio data parameters, consult the following table.
| Parameter | RCS element |
| ---------------------- | ------------------------------------------- |
| `title` | Title |
| `body` | Description (Rich Card) or Text (Chip List) |
| `subtitle` | *Not available in RCS* (appended to Body) |
| `media` | Media |
| `actions.QUICK_REPLY` | SuggestedReply |
| `actions.URL` | SuggestedAction.OpenUrlAction |
| `actions.PHONE_NUMBER` | SuggestedAction.DialAction |
#### Webviews
Webviews can work with the Google Wallet API to deliver boarding passes. See the Google Wallet documentation for [boarding passes](https://developers.google.com/wallet/tickets/boarding-passes).
#### Chip list versus rich card
Buttons in RCS can appear within a chip list or a rich card. Both are formats of rich content in RCS. On Android, chip lists appear as a horizontally scrolling list of buttons. Buttons in a rich card appear in a vertically stacked list. On iOS, the experience buttons always appear in a dropdown list of buttons. Chip lists can be attached to a rich card.
Use parameter `chip_list` to choose whether a button appears in a chip list versus a rich card. If not specified Twilio follows the following logic.
**Default behavior when media is present**
* **More than four buttons**: The first four buttons appear in the rich card. Remaining buttons appear in a chip list.
* **Four or fewer buttons**: RCS uses a rich card.
**Default behavior when media is not present**
* RCS uses a chip list.
Pricing depends on the presence of media and buttons. In the United States, pricing also depends on button type and the total length of text in the message. Rendering behavior depends on whether media is present and the number of buttons.
##### Differences in RCS resolution
| Type of message | Pricing (USA) | Allowed Twilio data parameters | Pricing length limits |
| --------------- | ----------------------- | -------------------------------------------------------------------------- | ------------------------------------------------- |
| Chip list | Rich | `body`; Quick reply, URL CTA buttons except Webviews, and Dial CTA buttons | Billed per 160-character UTF-8 segment |
| Rich card | Rich Media | `title`, `media`, and `body`; all button types | See limits in [Data parameters](#data-parameters) |
| Chip list | Single Message (global) | `body`; all button types | See limits in [Data parameters](#data-parameters) |
| Rich card | Single Message (global) | `title`, `media`, `body`; all button types | See limits in [Data parameters](#data-parameters) |
### WhatsApp
* By default, WhatsApp URL buttons open the link inside an in-app webview. For Marketing templates, you can configure the button to open the device's default browser instead. To do so, clear the **Link tracking** checkbox in the Meta template UI.
* 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](/docs/content/using-variables-with-content-api).
* Update the phone number in the sample actions array to a valid [E.164](/docs/glossary/what-e164)-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.
* For unapproved cards used in a session, the following rules apply:
* Only the buttons types `QUICK_REPLY`, `URL`, and `VOICE_CALL` are supported. Templates that include a `PHONE_NUMBER` button type are not supported.
* If you send a Content resource that contains buttons with different action types, the request fails. WhatsApp requires every button in a template to use the same action type. For example, a template that includes both a `voice\_call` button and a`url` button fails validation.
* There can only be one URL button in the Content. For example, a Content with two URL buttons will fail.
## Message preview
|  |  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
## Data parameters
| Parameter | Type | Required | [Variable support](/docs/content/using-variables-with-content-api) | Description |
| ------------------------- | --------- | -------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | string | No | Yes | Title of the card.
Maximum length: 200 characters for RCS; 1,024 characters for WhatsApp.
Required if `body` is not specified. |
| `body` | string | No | Yes | RCS only. Body text of the card.
Maximum length: 1,600 characters.
Required if `title` is not specified.
RCS only. For WhatsApp, include all text in `title` instead. |
| `subtitle` | string | No | No | Subtitle of the card.
Maximum length: 60 characters.
If specified for WhatsApp and the template is used in RCS, the subtitle is appended to the body. |
| `media` | string\[] | No | Yes | Public URL of the media to send.
See [accepted content types for media](/docs/messaging/guides/accepted-mime-types) (MMS) and [WhatsApp media types](/docs/whatsapp/guidance-whatsapp-media-messages#supported-mime-types). |
| `orientation` | string | No | No | RCS only. Will be ignored for other channels. Determines card layout. ENUM Options: `VERTICAL`, `HORIZONTAL`. Defaults to `VERTICAL`. |
| `thumbnailImageAlignment` | string | No | No | RCS only. Will be ignored for other channels. Determines image position in a `HORIZONTAL` card. ENUM Options: `LEFT`, `RIGHT`. Defaults to `LEFT`. |
| `height` | string | No | No | RCS only. Will be ignored for other channels. Determines card proportions for Android devices. ENUM Options: `SHORT`, `MEDIUM`, `TALL`. Defaults to `TALL`. |
| `actions` | array | No | Yes | Defines buttons that appear on the card. |
### `actions` properties
For an overview of shared button properties, see [Common components](/docs/content/content-types-overview#common-components).
> \[!NOTE]
>
> WhatsApp limitations
>
> * Only one of the two call options can appear on a template: `PHONE_NUMBER` 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.
| Property | Supported channels | Parameters |
| -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `QUICK_REPLY` | RCS, WhatsApp, Facebook Messenger | - **`type`**: `QUICK_REPLY`
- **`title`**: Text shown on the button. Appears in the `ButtonText` field 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.
- **`chip_list`** (RCS only): Optional. Controls whether the button appears in a chip\_list or rich card. Valid values: `true`, `false`. If not specified Twilio will use chip\_list when available.
|
| `URL` | RCS, WhatsApp, Facebook Messenger | - **`type`**: `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`.
- **`chip_list`** (RCS only): Optional. Controls whether the button appears in a chip\_list or rich card. Valid values: `true`, `false`. If not specified Twilio will use chip\_list when available.
|
| `PHONE_NUMBER` | RCS, WhatsApp, Facebook Messenger | - **`type`**: `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.
- **`chip_list`** (RCS only): Optional. Controls whether the button appears in a chip\_list or rich card. Valid values: `true`, `false`. If not specified Twilio will use chip\_list when available.
|
| `VOICE_CALL` | WhatsApp | - **`type`**: `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_CODE` | WhatsApp | - **`type`**: `COPY_CODE`
- **`title`**: WhatsApp now overrides this value with `Copy Code` and translates automatically to the template's language. Variables and customization are not supported.
- **`code`**: Coupon code copied to the user's clipboard when the button is tapped. Variables are supported.
|
## Code example
Create a card template
```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
// 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 = twilio(accountSid, authToken);
async function createContent() {
const content = await client.content.v1.contents.create({
friendly_name: "owl_air_card",
variables: {
1: "coupon_code",
},
language: "en",
types: {
"twilio/text": {
body: "Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out.",
},
"twilio/card": {
title:
"Congratulations, you've reached Elite status! Add code {{1}} for 10% off.",
subtitle: "To unsubscribe, reply Stop",
actions: [
{
type: "URL",
title: "Order Online",
url: "https://owlair.com/",
},
{
type: "PHONE_NUMBER",
title: "Call Us",
phone: "+15551234567",
},
],
},
},
});
console.log(content.dateCreated);
}
createContent();
```
```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client
from twilio.rest.content.v1 import ContentList
# Find your Account SID and Auth Token at twilio.com/console
# and set the environment variables. See http://twil.io/secure
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
client = Client(account_sid, auth_token)
content = client.content.v1.contents.create(
content_create_request=ContentList.ContentCreateRequest(
{
"friendly_name": "owl_air_card",
"variables": {"1": "coupon_code"},
"language": "en",
"types": ContentList.Types(
{
"twilio/text": ContentList.TwilioText(
{
"body": "Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out."
}
),
"twilio/card": ContentList.TwilioCard(
{
"title": "Congratulations, you've reached Elite status! Add code {{1}} for 10% off.",
"subtitle": "To unsubscribe, reply Stop",
"actions": [
ContentList.CardAction(
{
"type": "URL",
"title": "Order Online",
"url": "https://owlair.com/",
}
),
ContentList.CardAction(
{
"type": "PHONE_NUMBER",
"title": "Call Us",
"phone": "+15551234567",
}
),
],
}
),
}
),
}
)
)
print(content.date_created)
```
```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install
using System;
using Twilio;
using Twilio.Rest.Content.V1;
using System.Threading.Tasks;
using System.Collections.Generic;
class Program {
public static async Task Main(string[] args) {
// Find your Account SID and Auth Token at twilio.com/console
// and set the environment variables. See http://twil.io/secure
string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");
TwilioClient.Init(accountSid, authToken);
var content = await ContentResource.CreateAsync(
contentCreateRequest: new ContentResource.ContentCreateRequest.Builder()
.WithFriendlyName("owl_air_card")
.WithVariables(new Dictionary() { { "1", "coupon_code" } })
.WithLanguage("en")
.WithTypes(
new ContentResource.Types.Builder()
.WithTwilioText(
new ContentResource.TwilioText.Builder()
.WithBody(
"Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out.")
.Build())
.WithTwilioCard(
new ContentResource.TwilioCard.Builder()
.WithTitle(
"Congratulations, you've reached Elite status! Add code {{1}} for 10% off.")
.WithSubtitle("To unsubscribe, reply Stop")
.WithActions(new List {
new ContentResource.CardAction.Builder()
.WithType("URL")
.WithTitle("Order Online")
.WithUrl("https://owlair.com/")
.Build(),
new ContentResource.CardAction.Builder()
.WithType("PHONE_NUMBER")
.WithTitle("Call Us")
.WithPhone("+15551234567")
.Build()
})
.Build())
.Build())
.Build());
Console.WriteLine(content.DateCreated);
}
}
```
```java
// Install the Java helper library from twilio.com/docs/java/install
import java.util.Arrays;
import java.util.HashMap;
import com.twilio.Twilio;
import com.twilio.rest.content.v1.Content;
public class Example {
// Find your Account SID and Auth Token at twilio.com/console
// and set the environment variables. See http://twil.io/secure
public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");
public static void main(String[] args) {
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
Content.Types types = new Content.Types();
types.setTwilioText(new HashMap() {
{
put("body",
"Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! "
+ "Just add coupon code {{1}} to check out.");
}
});
types.setTwilioCard(new HashMap() {
{
put("title", "Congratulations, you've reached Elite status! Add code {{1}} for 10% off.");
put("subtitle", "To unsubscribe, reply Stop");
put("actions",
Arrays.asList(
new HashMap() {
{
put("type", "URL");
put("title", "Order Online");
put("url", "https://owlair.com/");
}
},
new HashMap() {
{
put("type", "PHONE_NUMBER");
put("title", "Call Us");
put("phone", "+15551234567");
}
}
));
}
});
Content.ContentCreateRequest contentCreateRequest = new Content.ContentCreateRequest();
contentCreateRequest.setFriendlyName("owl_air_card");
contentCreateRequest.setVariables(new HashMap() {
{
put("1", "coupon_code");
}
});
contentCreateRequest.setLanguage("en");
contentCreateRequest.setTypes(types);
Content content = Content.creator(contentCreateRequest).create();
System.out.println(content.getDateCreated());
}
}
```
```go
// Download the helper library from https://www.twilio.com/docs/go/install
package main
import (
"fmt"
"github.com/twilio/twilio-go"
content "github.com/twilio/twilio-go/rest/content/v1"
"os"
)
func main() {
// Find your Account SID and Auth Token at twilio.com/console
// and set the environment variables. See http://twil.io/secure
// Make sure TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN exists in your environment
client := twilio.NewRestClient()
params := &content.CreateContentParams{}
params.SetContentCreateRequest(content.ContentCreateRequest{
FriendlyName: "owl_air_card",
Variables: map[string]string{
"1": "coupon_code",
},
Language: "en",
Types: content.Types{
TwilioText: &content.TwilioText{
Body: "Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out.",
},
TwilioCard: &content.TwilioCard{
Title: "Congratulations, you've reached Elite status! Add code {{1}} for 10% off.",
Subtitle: "To unsubscribe, reply Stop",
Actions: []content.CardAction{
content.CardAction{
Type: "URL",
Title: "Order Online",
Url: "https://owlair.com/",
},
content.CardAction{
Type: "PHONE_NUMBER",
Title: "Call Us",
Phone: "+15551234567",
},
},
},
},
})
resp, err := client.ContentV1.CreateContent(params)
if err != nil {
fmt.Println(err.Error())
os.Exit(1)
} else {
if resp.DateCreated != nil {
fmt.Println(*resp.DateCreated)
} else {
fmt.Println(resp.DateCreated)
}
}
}
```
```php
content->v1->contents->create(
ContentModels::createContentCreateRequest([
"friendlyName" => "owl_air_card",
"variables" => (object) [],
"language" => "en",
"types" => ContentModels::createTypes([
"twilioText" => ContentModels::createTwilioText([
"body" =>
"Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out.",
]),
"twilioCard" => ContentModels::createTwilioCard([
"title" =>
"Congratulations, you've reached Elite status! Add code {{1}} for 10% off.",
"subtitle" => "To unsubscribe, reply Stop",
"actions" => [
ContentModels::createCardAction([
"type" => "URL",
"title" => "Order Online",
"url" => "https://owlair.com/",
]),
ContentModels::createCardAction([
"type" => "PHONE_NUMBER",
"title" => "Call Us",
"phone" => "+15551234567",
]),
],
]),
]),
]),
);
print $content->dateCreated?->format("r");
```
```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'
# Find your Account SID and Auth Token at twilio.com/console
# and set the environment variables. See http://twil.io/secure
account_sid = ENV['TWILIO_ACCOUNT_SID']
auth_token = ENV['TWILIO_AUTH_TOKEN']
@client = Twilio::REST::Client.new(account_sid, auth_token)
content = @client
.content
.v1
.contents
.create(
content_create_request: {
'friendly_name' => 'owl_air_card',
'variables' => {
'1' => 'coupon_code'
},
'language' => 'en',
'types' => {
'twilio/text' => {
'body' => 'Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out.'
},
'twilio/card' => {
'title' => 'Congratulations, you\'ve reached Elite status! Add code {{1}} for 10% off.',
'subtitle' => 'To unsubscribe, reply Stop',
'actions' => [
{
'type' => 'URL',
'title' => 'Order Online',
'url' => 'https://owlair.com/'
},
{
'type' => 'PHONE_NUMBER',
'title' => 'Call Us',
'phone' => '+15551234567'
}
]
}
}
}
)
puts content.date_created
```
```bash
# This endpoint is not currently supported by the Twilio CLI. You can open an issue to request it on https://github.com/twilio/twilio-cli/issues
# For an alternative low-code solution, check out https://www.twilio.com/docs/openapi/using-twilio-postman-collections
```
```bash
EXCLAMATION_MARK='!'
CONTENT_CREATE_REQUEST_OBJ=$(cat << EOF
{
"friendly_name": "owl_air_card",
"variables": {
"1": "coupon_code"
},
"language": "en",
"types": {
"twilio/text": {
"body": "Congratulations, your account reached Elite status, you are now eligible for 10% off any flight$EXCLAMATION_MARK Just add coupon code {{1}} to check out."
},
"twilio/card": {
"title": "Congratulations, you've reached Elite status! Add code {{1}} for 10% off.",
"subtitle": "To unsubscribe, reply Stop",
"actions": [
{
"type": "URL",
"title": "Order Online",
"url": "https://owlair.com/"
},
{
"type": "PHONE_NUMBER",
"title": "Call Us",
"phone": "+15551234567"
}
]
}
}
}
EOF
)
curl -X POST "https://content.twilio.com/v1/Content" \
--json "$CONTENT_CREATE_REQUEST_OBJ" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```
```json
{
"sid": "HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"friendly_name": "owl_air_card",
"language": "en",
"variables": {
"1": "coupon_code"
},
"types": {
"twilio/text": {
"body": "Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out."
},
"twilio/card": {
"title": "Congratulations, you've reached Elite status! Add code {{1}} for 10% off.",
"subtitle": "To unsubscribe, reply Stop",
"actions": [
{
"type": "URL",
"title": "Order Online",
"url": "https://owlair.com/"
},
{
"type": "PHONE_NUMBER",
"title": "Call Us",
"phone": "+15551234567"
}
]
}
},
"url": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"date_created": "2015-07-30T19:00:00Z",
"date_updated": "2015-07-30T19:00:00Z",
"links": {
"approval_create": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ApprovalRequests/whatsapp",
"approval_fetch": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ApprovalRequests"
}
}
```
## Receiving webhooks
### Inbound events
| Component | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ButtonPayload` | ID specified in the button to identify the button click. If no ID is specified, the button text appears in this field. |
| `ButtonType` | Indicates whether the pressed button was a quick-reply or call-to-action button. |
| `ButtonText` | Text of the button that the user clicked. |