Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Rate this page:
On this page

whatsapp/card

Whatsapp/card 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 cannot 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 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"}

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

Supported Channels

supported-channels page anchor

WhatsApp

Message Preview

message-preview page anchor
header_textwa.

Data Parameters

data-parameters page anchor

body:

  • Type: string
  • Required: yes
  • Variable Support: yes

  • Description: body of card.

    • Maximum: 1024 characters

footer:

  • Type: string
  • Required: no
  • Variable Support: no

  • Description: footer 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).
    • Cannot be present if header_text is present

header_text:

  • Type: string
  • Required: no
  • Variable Support: yes

  • Description: Bolded header text of card.

    • Maximum: 60 characters
    • Cannot be present if media is present

actions:

  • Type: array
  • Required: Yes
  • Variable Support: Yes
  • Description: Cards can contain buttons which are defined using an actions array.

actions:

(information)

Info

Limitations -

  • Only 1 of the 2 call options can be on a template: PHONE or VOICE_CALL.
  • Up to 2 URL buttons are allowed.
  • VOICE_CALL is currently a private beta in select regions.
  • Up to 5 quick reply buttons are allowed. If the content template is being sent in session over WhatsApp without approval, only 3 buttons are allowed.

QUICK_REPLY:

  • parameters
    • 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 not supported. Max 25 chars.
    • id: Not visible to end user. Appears in ButtonPayload fields in inbound when selected by end user. Variables are supported.

URL:

  • parameters
    • type: URL
    • title: Button text of URL redirect button. Variables are not supported. Max 25 chars.
    • url: URL opened when end user clicks the button. Variables are supported at the end of the url string.

PHONE:

  • parameters
    • type: PHONE
    • title: Button text of URL redirect button. Variables are not supported. Max 25 chars.
    • phone: Phone number to call when the recipient taps the button. E.164 formatted. Variables are not supported.

VOICE_CALL:

  • parameters
    • type: VOICE_CALL
    • title: Button text of VOIP call button. Variables are not supported. Max 25 chars.

COPY_CODE:

  • parameters
    • type: COPY_CODE
    • title: Button text of copy code button. Variables are not supported. Max 25 chars.
    • code: Coupon code that is copied to end user clipboard after clicking button. Variables are supported.

Create a WhatsApp Card Template

create-a-whatsapp-card-template page anchor
C#
Java
curl

_40
// Install the C# / .NET helper library from twilio.com/docs/csharp/install
_40
_40
using System;
_40
using Twilio;
_40
using Twilio.Rest.Content.V1;
_40
_40
TwilioClient.Init(accountSid, authToken);
_40
_40
// define the whatsapp/card
_40
var whatsappCard = new WhatsappCard.Builder();
_40
whatsappCard.WithBody("Congratulations, you have reached Elite status! Add code {{1}} for 10% off.");
_40
whatsappCard.WithHeaderText("This is a {{1}} card");
_40
whatsappCard.WithFooter("To unsubscribe, reply Stop");
_40
var cardAction1 = new CardAction.Builder()
_40
.WithType(CardActionType.Url)
_40
.WithUrl("https://www.twilio.com")
_40
.WithTitle("Order Online")
_40
.Build();
_40
var cardAction2 = new CardAction.Builder()
_40
.WithType(CardActionType.PhoneNumber)
_40
.WithPhone("+15551234567")
_40
.WithTitle("Call Us")
_40
.Build();
_40
whatsappCard.WithActions(new List<CardAction>() { cardAction1, cardAction2 });
_40
_40
// define all the content types to be part of the template
_40
var types = new Types.Builder();
_40
types.WithWhatsappCard(whatsappCard.Build());
_40
_40
// build the create request object
_40
var contentCreateRequest = new ContentCreateRequest.Builder();
_40
contentCreateRequest.WithTypes(types.Build());
_40
contentCreateRequest.WithLanguage("en");
_40
contentCreateRequest.WithFriendlyName("owl_coupon_code");
_40
contentCreateRequest.WithVariables(new Dictionary<string, string>() { {"1", "coupon_code"} });
_40
_40
// create the twilio template
_40
var contentTemplate = await CreateAsync(contentCreateRequest.Build());
_40
_40
Console.WriteLine($"Created Twilio Content Template SID: {contentTemplate.Sid}");

Output

_36
{
_36
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_36
"date_created": "2023-08-03T14:54:47Z",
_36
"date_updated": "2023-08-03T14:54:47Z",
_36
"friendly_name": "owl_coupon_code",
_36
"language": "en",
_36
"links": {
_36
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
_36
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
_36
},
_36
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_36
"types": {
_36
"whatsapp/card": {
_36
"actions": [
_36
{
_36
"title": "Order Online",
_36
"type": "URL",
_36
"url": "https://owlair.example.com/"
_36
},
_36
{
_36
"phone": "+1555554567",
_36
"title": "Call Us",
_36
"type": "PHONE_NUMBER"
_36
}
_36
],
_36
"body": "Congratulations, you have reached Elite status! Add code {{1}} for 10% off.",
_36
"footer": "To unsubscribe, reply Stop",
_36
"header_text": "This is a {{1}} card",
_36
"media": null
_36
}
_36
},
_36
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_36
"variables": {
_36
"1": "coupon_code"
_36
}
_36
}

Rate this page: