SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Upgrading WhatsApp Templates to Content Templates

On November 1st, 2024, Twilio will migrate the usage of templates from the WhatsApp Template Console and Templates API to Content Template Builder (formerly known as Content API and Content Editor). The WhatsApp Template Console Tab and Templates API will be deprecated on the same date. 

Content Template Builder is an omnichannel template platform that supports both text only and rich content. All existing WhatsApp templates will become omnichannel Content Templates and will be available for use in WhatsApp and other channels, including SMS, MMS, Google Business Messages and Facebook Messenger. Your Content Templates can be found in the Content Template Builder in Twilio console.

Contents

WhatsApp Templates Deprecation Timeline

Timeline with colored intervals (8).png

What Twilio products are affected and what do I need to change?

For all products:

  • Starting November 1st, 2024, all new templates must be created using Content Template Builder.
  • Starting November 1st, 2024, all templates must be sent with a Content SID and Content Variables instead of Body. The mapping between your current WhatsApp Templates and their new Content Template SID can be found with this endpoint.

Specific details for separate products are available in the table below:

Twilio Product Changes Required? Details
WhatsApp Programmable Messaging API Yes

Using "Body" to match a template will no longer work.

Changes Required to API Request to send a WhatsApp Template:

  • Stop using "Body" and "MediaUrl" parameters
  • Use the template's "ContentSid" parameter
  • If your template has placeholders, use the "ContentVariables" parameter to programmatically insert those key:values
  • Include a "MessagingServiceSid" parameter. This requirement will be removed before the final deprecation date.
Flex Yes

Using the "Body" parameter to identify the WhatsApp Template will break if you are using one of the following methods:

  1. Plugin Canned Responses
  2. Plugin Outbound CBM or similar
  3. Via agent UI (manual copy/paste)

You will need to adapt your plugins:

  • To use the template's "ContentSid" parameter
  • If your template has placeholders, use the "ContentVariables" parameter to programmatically insert those key:values
  • Include a "MessagingServiceSid" parameter. This requirement will be removed before the final deprecation date.
Studio Yes

Flows that contain WhatsApp templates that match the "Body" parameter will fail.

You will need to:

  • Update all "Send" and "Send & Reply" widgets that send a WhatsApp Template to use Content SID and Content Variables (if your template uses placeholders).
  • Include a Messaging Service SID in the "Advanced Configuration -> Send message from" parameter. This requirement will be removed before the final deprecation date.

More information can be found in our product documentation here.

Conversations Yes

Using "Body" to match a template will no longer work.

Changes Required to API Request to send a WhatsApp Template:

  • Stop using "Body" and "MediaUrl" parameters
  • Use the template's "ContentSid" parameter
  • If your template has placeholders, use the "ContentVariables" parameter to programmatically insert those key:values

Read more in our product documentation here.

Verify No Verify will start using Content Templates prior to the deprecation of WhatsApp Templates. No change will be required for customers.
WhatsApp Sandbox No New customers using the sandbox when we reach the deprecation of WhatsApp Templates will learn to send WhatsApp business initiated messages using a Content SID and Content Variables.
 

 

Sending Messages with Content Templates versus WhatsApp Templates

Sending a message using WhatsApp Templates

To send a WhatsApp 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. Often, encoded characters or trailing spaces are present in the template body but are missed or encoded incorrectly when sending the message body, leading to error 63016

Sending a message with Content Templates

To send a template message using a Content Template, users only need to supply the template SID, a Messaging Service SID and the placeholder values, if any (The mapping between your current WhatsApp Templates and their new Content Template SID can be found with this endpoint). This prevents template mismatch errors that frequently occur using the WhatsApp Template system.

Comparison of API Requests to Send With Content Templates and WhatsApp Templates

Example template body containing a newline and trailing whitespace:

“Hi {{1}}, thanks for joining our business. \nWe're looking forward to seeing you again soon in store. “

 

WhatsApp Templates Content Templates
Screenshot 2023-10-24 at 16.12.11.png Screenshot 2023-10-24 at 16.13.22.png
Message body risks failing with a mismatch error due to trailing whitespace at the end of the message and the newline not being encoded correctly Message only needs to match the template SID and variable parameters are programmatically added to the message

API parameters:

  • Body
  • From
  • To

API parameters:

  • Messaging Service SID. This requirement will be removed before the final deprecation date.
  • From
  • Content SID
  • Content Variables
  • To

API Parameter Comparison Table

480px-Eo_circle_light-blue_checkmark.svg.png Supported but not required 480px-Eo_circle_green_checkmark.svg.png Required 480px-Eo_circle_red_no-entry.svg.png Not supported

 

API Parameter WhatsApp Templates Content Templates
Messaging Service 480px-Eo_circle_light-blue_checkmark.svg.png 480px-Eo_circle_green_checkmark.svg.png This requirement will be removed in before the final deprecation date.
From 480px-Eo_circle_green_checkmark.svg.png 480px-Eo_circle_green_checkmark.svg.png
To 480px-Eo_circle_green_checkmark.svg.png 480px-Eo_circle_green_checkmark.svg.png
Content SID 480px-Eo_circle_red_no-entry.svg.png 480px-Eo_circle_green_checkmark.svg.png
Content Variables 480px-Eo_circle_red_no-entry.svg.png 480px-Eo_circle_light-blue_checkmark.svg.png

Body

480px-Eo_circle_green_checkmark.svg.png 480px-Eo_circle_red_no-entry.svg.png

Media URL

480px-Eo_circle_light-blue_checkmark.svg.png 480px-Eo_circle_red_no-entry.svg.png Included in the Template

 

Helper Libraries and Messaging Services in Content Template Builder

Helper Libraries

Content Template Builder is partially supported by our helper libraries for all endpoints that don’t use a JSON body but users must make sure their helper library is up to date to ensure all features are available for use. 

Messaging Services Requirement

Content Templates require a ​​Messaging Service to work but the sender does not necessarily need to be part of the Sender Pool. This requirement will be removed before the final deprecation date.

There are two options available to send Content Templates depending on your use case:

  1. Add your WhatsApp Sender(s) to the Messaging Service Sender Pool for automatic sender selection

    You can add one or multiple WhatsApp Senders to a Messaging Service and the Sender Pool logic will select a Sender automatically. You can include the Messaging Service in your API call using either the “From” parameter or the “MessagingServiceSID” parameter.

  2. Chose a specific WhatsApp Sender

    You can decide which WhatsApp Sender you want to use to send your Content Templates. Add the Sender in the “From” parameter of your API call. You will need to include a ​​Messaging Service SID in the “MessagingServiceSID” parameter, but the WhatsApp Sender does not need to be added to the Sender Pool.

FAQS and Key Terms

Key Terms:
WhatsApp Templates: Templates submitted in the Twilio Console under Messaging > Senders > WhatsApp Templates.
Templates API: Beta product providing WhatsApp template creation and management via API.

Content Template Builder: Formerly known as Content API and Content Editor, Content Template Builder provides an API and Console Editor that enables users to create and send rich messaging content over any Twilio-supported messaging channel, not just WhatsApp. Documentation can be found here.

In the lead up to the deprecation date, can I use WhatsApp Templates and Content Templates at the same time?

Templates submitted through the WhatsApp Template console cannot be sent in the same way as Content Templates and vice versa. You can utilise 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 WhatsApp Templates to Content Template Builder?

Twilio will perform a sync of all current WhatsApp Templates three times before the deprecation date. After each sync, all templates will be available as both Content Templates and WhatsApp Templates. The mapping between your current WhatsApp Templates and their new Content Template SID can be found with this endpoint

Syncs will take place at the following times:

  • Jan 9th-11th 2024
  • End of Q1 2024
  • 1 week prior to Nov 1st

Where can I find documentation for Content Template Builder?

You can find Content Template Builder docs here.

Have more questions? Submit a request
Powered by Zendesk