Overview
There are important differences between sending WhatsApp template messages using Legacy Templates and Content Templates (Templates submitted via the Twilio Content API/Template Builder). These differences include changes to code.
This guide details the main differences between the two systems and what users need to be aware of when implementing Content Templates in their WhatsApp workflow.
What You Need To Know
Key terms 🔗
- Legacy Templates: Templates submitted in the Twilio Console under Messaging > Senders > WhatsApp Templates.
- Content API: API that enables users to create and send rich messaging content over any Twilio-supported messaging channel, not just WhatsApp. Documentation can be found here.
- Content Template Builder: Interactive Template Builder that enables users to create, approve, and manage templates from the Twilio Console. Templates can be used on any supported channel, not just WhatsApp. Accessible via Messaging > Content Template Builder. Documentation can be found here.
Sending a message using legacy templates 🔗
To send a legacy template, users need to match the message body in the “body” parameter of their API call exactly with the template body as it was created via the Twilio console. This can cause problems with special characters, right to left languages and newlines, leading to error 63016. Often encoded characters or trailing spaces are present in the template body but are missed when sending the message body.
Example of sending a Legacy Template
Raw Template Body:
“Hi {{1}}, thanks for joining our business. \nWe're looking forward to seeing you again soon in store. “
Sending the template with cURL:
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/{account_sid}/Messages.json" \
--data-urlencode "From=whatsapp:+1234567890" \
--data-urlencode "Body=Hi Joe, thanks for joining our business.
We're looking forward to seeing you again soon in store. " \
--data-urlencode "To=whatsapp:+0987654321" \
-u {account_sid}:{auth_token}
Legacy template required API parameters:
- Body
- From
- To
Sending a message with Content Templates 🔗
To send a template message using a Content Template, users only need to supply the SID of the template, a From number, To number, and the placeholder values, if any. This prevents template mismatch errors that frequently occur using the legacy template system.
Example of sending a Content Template
Raw Template Body:
“Hi {{1}} thanks for reaching out. \nHow can I help you today? “
Code Snippet:
curl -X POST https://api.twilio.com/2010-04-01/Accounts/{account_sid}/Messages \
--data-urlencode "To=whatsapp:+1234567890" \
--data-urlencode "From=whatsapp:+0987654321" \
--data-urlencode "ContentSid={template_sid}" \
--data-urlencode 'ContentVariables={"1": "Josephine"}' \
-u {account_sid}:{auth_token}
Content template required parameters:
- From
- To
- Content SID
- Content Variables
Helper libraries 🔗
The Content API is partially supported by our helper libraries for all endpoints that don’t use a JSON body. Users must make sure their helper library is up to date to ensure all features are available for use.
Parameter comparison table 🔗
| API Parameter | Legacy Templates | Content Templates |
| Messaging Service | ||
| From | ||
| To | ||
| Content SID | ||
| Content Variables | ||
|
Body |
||
|
Media URL |
Frequently Asked Questions
Can I use Legacy Templates and Content Templates at the same time?
Templates submitted through the Legacy Template console cannot be sent in the same way that Content Templates and vice versa. You can utilize both in your code at the same time, but you will have to differentiate between the two types at send time.
Can I migrate all my legacy templates to content templates?
Yes! Please refer to the steps here for Self-Service template copy.
Where can I find documentation for Content API and Content Template Builder?
You can find Content API docs here and Content Template Builder docs here.