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 April 1st, 2025, 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

Article Change Log

Date

Change Information

8/22/2024

Updated references to MessagingServiceSid requirement for sending messages with Content templates. A MessagingServiceSid parameter is now optional.

7/17/2024

New customers will only be able to use templates on WhatsApp using the Content Template Builder

7/8/2024

Updated EOL date from November 1, 2024 to April 1, 2025.

3/26/2024

Added information about self-service Legacy Template migration. Removed references of second and final "scheduled" template migrations.


WhatsApp Templates Deprecation Timeline

Timeline with colored intervals.png

Self-Service Template Copy

You can now initiate a copy of legacy WhatsApp templates to Content API in Twilio Console.

1. Navigate to the WhatsApp templates page in Twilio Console.

2. Click the "Copy Templates" button. Note, clicking the button will start the template copy immediately, there is not a confirmation or cancellation step after clicking.

3. While the template copy is in progress, the "Copy Templates" button will be greyed out and you will see an information banner indicating that copy is taking place. Note, any new legacy templates created during the copy will not be copied to Content API.

4. Once the template copy has completed, you will see the following banner:

5. Navigate to Content Template Builder or use the API to fetch the mapping between legacy templates and the newly created content templates.

Note: While it will still be possible to create a legacy WhatsApp template until some time in the future, we recommend that you only create Content API templates after you copy all legacy templates to Content API

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

For all products:

  • Starting April 1st, 2025, all new templates must be created using Content Template Builder.
  • Starting April 1st, 2025, 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

    Note: Previous versions of this article described including a MessagingServiceSid parameter. This is now optional as of August 22nd, 2024.
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

    Note: Previous versions of this article described including a MessagingServiceSid parameter. This is now optional as of August 22nd, 2024.
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).

    Note: Previous versions of this article described including a MessagingServiceSid parameter. This is now optional as of August 22nd, 2024.

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

Sending messages with content templates is simple and prevents the mismatch errors that were common when using the WhatsApp Template system.

To send a template message using a Content Template, users only need to supply:

  • From number
  • To number
  • ContentSid (this is the template sid that begins with HX)
  • ContentVariables (if applicable for the template)

A MessagingServiceSid is optional as of August 22nd, 2024. 

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 template-api-example.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:

  • From
  • To
  • Content SID
  • Content Variables

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_light-blue_checkmark.svg.png
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. 

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 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 WhatsApp Templates to Content Template Builder?

Twilio performed an initial migration of all current (at that time) WhatsApp Templates in January 2024 (performed between January 9th and January 11th).

Twilio now supports a self-service template copy feature in Twilio Console. See more details here.

After performing the template copy, 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

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