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
- WhatsApp Templates Deprecation Timeline
- Self-Service Template Copy
- What Twilio products are affected and what do I need to change?
-
Sending Messages with Content Templates versus WhatsApp Templates
- Helper Libraries and Messaging Services in Content Template Builder
- FAQS and Key Terms
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
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:
|
Flex | Yes |
Using the "Body" parameter to identify the WhatsApp Template will break if you are using one of the following methods:
You will need to adapt your plugins:
|
Studio | Yes |
Flows that contain WhatsApp templates that match the "Body" parameter will fail. You will need to:
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:
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 |
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:
|
API parameters:
|
API Parameter Comparison Table
Supported but not required | Required | Not supported |
API Parameter | WhatsApp Templates | Content Templates |
Messaging Service | ||
From | ||
To | ||
Content SID | ||
Content Variables | ||
Body |
||
Media URL |
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.