Skip to contentSkip to navigationSkip to topbar
Rate this Page:

twilio/card


Twilio/card is a structured template which can be used to send a series of related information. It must include a title and at least one additional field.

(information)

Info

On WhatsApp, a card must be approved as a template before it can be sent. If you use variables with twilio/card, then additional approval steps are required. If a twilio/card template is created with media and with variables and you plan to submit this template to WhatsApp for approval, a valid media sample is required. Static media urls should resolve to publicly hosted media files. Variable media urls should include a valid media URL suffix in the variable declaration.

Only one type of media can be sent per approved variable WhatsApp card template. WhatsApp classifies approved templates into 1 of 3 types of media headers (Image, Video, Document) based on the sample that was submitted. Once the template has been approved another type of media header cannot be sent using the template.

Ex. If a template is approved with an image then a video cannot be sent using the same template.

In the Media field of the template you create, provide the URL of the publicly hosted file.

If you are using a media in the card with a variable. Please submit a sample path of a publicly hosted image URL in the variable array. The combined URL must contain the file type. The combined URL must resolve to a publicly hosted file.

Example:

"media": ["https://twilio-cms-prod.s3.amazonaws.com/{{1}}"] would include a path sample in the variables definition. "variables": {"1": "images/library-logo-resource2x.width-1000.png"}

If you are using a call-to-action URL button in your card, the URL must resolve to a publicly accessible website. If there is a variable, a valid path sample should be included in the variables array. The combined URL should resolve to a publicly accessible website.

Example:

"url": ["https://www.twilio.com/{{1}}"] would include a path sample in the variables definition. "variables": {"1": "docs"}

After you submit the template for approval to WhatsApp, your template should be approved and ready to send in 1 hour. If your template is still pending after 1 business day, please file a support ticket with the ContentSid, the template name you submitted to WhatsApp, and your AccountSid. In the ticket subject please include "[Content API - Card Request]" to ensure timely processing. If the body text of your Media template includes a variable, please also provide a sample message in your email request. For example, if your template states "Hi {{1}}, your order is confirmed", please submit a sample such as "Hi Sam, your order is confirmed."

(warning)

Warning

  • If the template's body starts or ends with a variable or has two variables next to each other, the template will not be approved by WhatsApp without a sample variable. For additional information about variables see here .
  • Update the phone number to a valid phone number in the actions array below when creating your template. This template will fail to send otherwise.
  • WhatsApp footers translate to subtitles in Twilio/cards.

Supported Channels

supported-channels page anchor

WhatsApp, Facebook Messenger


Screen Shot 2022-08-25 at 1.28.57 PM.

title:

  • Type: string
  • Required: yes
  • Variable Support: yes
  • Description: Title of card.

    • Maximum: 1024 characters

subtitle:

  • Type: string
  • Required: no
  • Variable Support: no
  • Description: Subtitle of card.

    • Maximum: 60 characters

media:

  • Type: string[]
  • Required: no
  • Variable Support: yes
  • Description: The URL of the media to send with the message.

    • Supported and Accepted media types can be referenced here (MMS) and here (WhatsApp).

actions:

  • Type: [array actions]
  • Required: no
  • Variable Support: See Common Components: Actions definition
  • Description: Buttons that recipients can tap on to act on the message:

    • Up to 2 buttons for PHONE or URL actions
    • Up to 3 buttons for QUICK_REPLY action

Create Card Template

create-card-template page anchor
curl

_31
curl -X POST 'https://content.twilio.com/v1/Content' \
_31
-H 'Content-Type: application/json' \
_31
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
_31
-d '{
_31
"friendly_name": "owl_coupon_card",
_31
"language": "en",
_31
"variables": {
_31
"1": "coupon_code"
_31
},
_31
"types": {
_31
"twilio/card": {
_31
"title": "Congratulations, you'\''ve reached Elite status! Add code {{1}} for 10% off.",
_31
"subtitle": "To unsubscribe, reply Stop",
_31
"actions": [
_31
{
_31
"url": "https://twilio.com/",
_31
"title": "Order Online",
_31
"type": "URL"
_31
},
_31
{
_31
"phone": "+15551234567",
_31
"title": "Call Us",
_31
"type": "PHONE_NUMBER"
_31
}
_31
]
_31
},
_31
"twilio/text": {
_31
"body": "Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out."
_31
}
_31
}
_31
}'

Output

_39
{
_39
"language": "en",
_39
"date_updated": "2022-08-30T09:19:17Z",
_39
"variables": {
_39
"1": "coupon_code"
_39
},
_39
"friendly_name": "owl_coupon_card_two",
_39
"account_sid": "ACXXXXXXXXXXXXXXXXXXX",
_39
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXX",
_39
"sid": "HXXXXXXXXXXXXXXXXXXX",
_39
"date_created": "2022-08-30T09:19:17Z",
_39
"types": {
_39
"twilio/text": {
_39
"body": "Congratulations, your account reached Elite status, you are now eligible for 10% off any flight! Just add coupon code {{1}} to check out."
_39
},
_39
"twilio/card": {
_39
"body": null,
_39
"media": null,
_39
"subtitle": "To unsubscribe, reply Stop",
_39
"actions": [
_39
{
_39
"url": "https://twilio.com/",
_39
"type": "URL",
_39
"title": "Order Online"
_39
},
_39
{
_39
"phone_number": "+15551234567",
_39
"type": "PHONE_NUMBER",
_39
"title": "Call Us"
_39
}
_39
],
_39
"title": "Congratulations, you have reached Elite status! Add code {{1}} for 10% off."
_39
}
_39
},
_39
"links": {
_39
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXX/ApprovalRequests",
_39
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp"
_39
}
_39
}


Rate this Page: