whatsapp/card


The whatsapp/card content type is a structured template which can be used to send a series of related information. It must include a body and at least one additional field.

(information)

Info

WhatsApp card can't have both a Text Header and Media Header

(information)

Info

On WhatsApp, a card must be approved as a template before it can be sent. If you use variables with whatsapp/card, then additional approval steps are required.

If a whatsapp/card content 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 can't be sent using the template.

For example, if a template is approved with an image then a video can't 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.

For 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.

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

(warning)

Warning

  • If the template's body starts or ends with a variable or has two variables next to each other, the template won't be approved by WhatsApp without a sample variable. For additional information about variables see Using Variables with Content Templates.
  • 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

Channels specific information

channels-specific-information page anchor
  • VOICE_CALL is currently a private beta feature in select regions.
  • If the content template is being sent in session over WhatsApp without approval, only three buttons are allowed.
  • On WhatsApp, a card must be approved as a template before it can be sent. Additional approval steps are required if you use variables with twilio/card. A valid media sample is required if a twilio/card content template is created with media and/or variables and you plan to submit this template to WhatsApp for approval. 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 can't be sent using the template.
    • For example, if a template is approved with an image, you can't send a video using that same template.
  • If the template's body starts or ends with a variable or has two variables next to each other, the template won't be approved by WhatsApp without a sample variable. For additional information about variables, see Using Variables with Content Templates.
  • When creating your template, ensure that the phone number in the actions array below is valid. Otherwise, the template will fail to send.
  • WhatsApp footers translate to subtitles in twilio/cards.
  • Template approval is required if multiple buttons are present.

header_textwa.

ParameterTypeRequiredVariable supportDescription
bodystringYesYesThe body of the card.
Maximum length: 1,024 characters
footerstringNoNoThe footer of the card.
Maximum length: 60 characters
mediastring[]NoNoThe URL of the media to send with the message. media can't be present if header_text is present.
To learn more about supported and accepted media types that can be referenced, see Accepted Content Types for Media for MMS and Guidance on WhatsApp Media Messages.
header_textstringNoNoBolded header text of card. header_text can't be present if media is present.
Maximum length: 60 characters
actionsarrayYesYesCards can contain buttons which are defined using an actions array.

To learn more about see [common components], see common components.

(information)

Info

Limitations:

  • VOICE_CALL is currently a private beta in select regions.
  • Only one of the two call options can be on a template:
    • PHONE
    • VOICE_CALL
  • Up to two URL buttons are allowed.
  • Up to five quick reply buttons are allowed. If the content template is being sent in session over WhatsApp without approval, only three buttons are allowed.
PropertyParameters
QUICK_REPLY
  • type: QUICK_REPLY
  • title: Button text of quick reply button. Appears in Body and ButtonText fields in inbound when selected by end user. Variables are supported in session.
    Maximum length: 25 characters
  • id: Not visible to end user. Appears in ButtonPayload fields in inbound when selected by end user. Variables are supported.
URL
  • type: URL
  • title: Button text of URL redirect button. Variables aren't supported.
    Maximum length: 20 characters
  • url: URL opened when end user clicks the button. Variables are supported at the end of the URL string.
PHONE
  • type: PHONE
  • title: Button text of URL redirect button. Variables aren't supported.
    Maximum length: 20 characters
  • phone: E.164 formatted phone number to call when the recipient taps the button. Variables aren't supported.
VOICE_CALL
  • type: VOICE_CALL
  • title: Button text of VoIP call button. Variables aren't supported.
    Maximum length: 20 characters
  • ttl_minutes: Optional parameter. The lifespan of the button in minutes. After this time expires, the button can't be used to start a call to the business. You can use variables. The default is 10,080 minutes (7 days). The expected value is an integer between 1 and 43,200 minutes (30 days).
COPY_CODE
  • type: COPY_CODE
  • title: Button text of copy code button. Variables aren't supported.
    Maximum length: 20 characters
  • code: Coupon code that is copied to end user clipboard after clicking button. Variables are supported.

Code examples and responses

code-examples-and-responses page anchor
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 whatsapp/card
10
var whatsappCard = new WhatsappCard.Builder();
11
whatsappCard.WithBody("Congratulations, you have reached Elite status! Add code {{1}} for 10% off.");
12
whatsappCard.WithHeaderText("This is a {{1}} card");
13
whatsappCard.WithFooter("To unsubscribe, reply Stop");
14
var cardAction1 = new CardAction.Builder()
15
.WithType(CardActionType.Url)
16
.WithUrl("https://www.twilio.com")
17
.WithTitle("Order Online")
18
.Build();
19
var cardAction2 = new CardAction.Builder()
20
.WithType(CardActionType.PhoneNumber)
21
.WithPhone("+15551234567")
22
.WithTitle("Call Us")
23
.Build();
24
whatsappCard.WithActions(new List<CardAction>() { cardAction1, cardAction2 });
25
26
// define all the content types to be part of the template
27
var types = new Types.Builder();
28
types.WithWhatsappCard(whatsappCard.Build());
29
30
// build the create request object
31
var contentCreateRequest = new ContentCreateRequest.Builder();
32
contentCreateRequest.WithTypes(types.Build());
33
contentCreateRequest.WithLanguage("en");
34
contentCreateRequest.WithFriendlyName("owl_coupon_code");
35
contentCreateRequest.WithVariables(new Dictionary<string, string>() { {"1", "coupon_code"} });
36
37
// create the twilio template
38
var contentTemplate = await CreateAsync(contentCreateRequest.Build());
39
40
Console.WriteLine($"Created Twilio Content Template SID: {contentTemplate.Sid}");

Output

1
{
2
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
"date_created": "2023-08-03T14:54:47Z",
4
"date_updated": "2023-08-03T14:54:47Z",
5
"friendly_name": "owl_coupon_code",
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
"whatsapp/card": {
14
"actions": [
15
{
16
"title": "Order Online",
17
"type": "URL",
18
"url": "https://owlair.example.com/"
19
},
20
{
21
"phone": "+1555554567",
22
"title": "Call Us",
23
"type": "PHONE_NUMBER"
24
}
25
],
26
"body": "Congratulations, you have reached Elite status! Add code {{1}} for 10% off.",
27
"footer": "To unsubscribe, reply Stop",
28
"header_text": "This is a {{1}} card",
29
"media": null
30
}
31
},
32
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
33
"variables": {
34
"1": "coupon_code"
35
}
36
}