WhatsApp Business Platform > Business Management API > Guides

Create and Manage Message Templates

A message template is required for any notifications sent using the WhatsApp Business Platform. These templates can be created either in the Business Management API or through the WhatsApp Business Managers.

This document explains how to create, retrieve, edit, and delete message templates.

Before You Start

You will need:

A System User access token that is linked to the business
The whatsapp_business_management permission
The WhatsApp Business Account ID for the business
The media asset handle for any document, image, or video file to be used in a media template. To get a media asset handle you must upload the media asset using the Resumable Upload API.

Limitations

The message template name field is limited to 512 characters.
The message template content field is limited to 1024 characters.
A template can only be edited when it is in a state of Approved, Rejected, or Paused. A template can be edited once per day, up to 10 times per month.
WhatsApp Business Accounts can only create 100 message templates per hour.
WhatsApp Business Accounts can have up to 250 message templates. That means 250 message template names, each of them can have multiple language translations. For example, a message template called hello_world translated into two languages counts as a single message template in regards to this limit.

Localization

You can add a message template in a specific language when creating a template
Be consistent when providing translations. Learn more – Why am I seeing 'structure unavailable' errors in my callback?

Create Message Templates

You can create text message templates, media message templates, or interactive message templates.

To help us during the review and approval process, you can include example data. This can help us understand what kind of message you plan to send and showcase the customer experience. For example, you could include an image that could represent a customer's profile picture to personalize the experience. Make sure these are examples and do not include any confidential or personal information.

Message, Media, & Interactive Templates

To create a text message template, send a POST request to the /{whatsapp-business-account-ID}/message_templates endpoint and include the name, category, language, components with type set to BODY and text set to the content for message, name, and language fields.

Add another type array in components for the media you are including in the template. The array will include a type set to HEADER, format set to the media type, and can include optional information for text and examples.

Example Media Template Request

The following example creates a template with an image that customers can use to ask help to resolve an issue.

Formatted for readability.

curl -X POST "https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}/message_templates
  ?name={template-name}
  &language=en_US
  &category=TRANSACTIONAL,
  &components=[{
       type:BODY, 
       text:{message-text}
     }, 
     {
       type:HEADER, 
       format:IMAGE, 
       example:{header_handle:[{uploaded-image-file-url}]}
     }],
  &access_token={system-user-access-token}"

Example Interactive Template Request

The following example creates a template with a button that customers can use to call a business' phone number for help resolving an issue.

Formatted for readability.

curl -X POST "https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}/message_templates
  ?name={template-name}
  &language=en_US
  &category=TRANSACTIONAL,
  &components: [{
       type:BODY,
       text:body-text {{1}} {{2}} {{3}},
       example:{body_text:[[body-example-1,body-example-2,body-example-3]]}
     },
     {
       type:HEADER,
       format:TEXT,
       text:{header-text} {{1}},
       example:{ header_text:[{header-text}] }
     },
     {
       type:FOOTER,
       text:{footer-text}
     },
     {
       type:BUTTONS,
       buttons:[{type:PHONE_NUMBER,text:{phone-button-text},phone_number:+1(650) 555-1111}],
     },
     {
       type:URL,
       text:{url-button-text},
       url:https://www.website.com/{{1}},
       example:[https://www.website.com/dynamic-url-example]
     }]
  &access_token={system-user-access-token}"

On success, a JSON object containing the message template ID is returned:

{
  "id": "{message-template-id}"
}

For a complete list of parameters, visit the WhatsAppBusinessAccount/message_templates Reference .

Retrieve Templates

When a message template is returned, the response will include all its translations (if any). Message templates are grouped by the name field. You can use the limit parameter to define the number of items returned. This limit applies to the maximum number of message template names that may be returned, not the maximum number of objects.

To get a list of a business' message templates, send a GET request to the /{whatsapp-business-account-ID}/message_templates endpoint. In this example request we are limiting the number of templates returned to 3.

Example Request

Formatted for readability.

curl -i -X GET "https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}/message_templates
  ?limit=3
  &access_token={system-user-access-token}"

On success, a JSON object is returned:

{
  "data": [
    {
      "name": "hello_world",
      "components": [{
          "type": "BODY",
          "text": "Hello, {{1}}"
      }],
      "language": "en_US",
      "status": "APPROVED",
      "category": "TRANSACTIONAL",
      "id": "409119052980796"
    },
    {
      "name": "case_opened",
      "components": [{
          "type": "BODY",
          "text": "Seu caso {{1}} foi aberto. Entraremos em contato em breve."
      }],
      "language": "pt_BR",
      "status": "APPROVED",
      "category": "TRANSACTIONAL",
      "id": "718173718589371"
    },
    {
      "name": "case_opened",
      "components": [{
          "type": "BODY",
          "text": "Your case {{1}} was opened. We will get in touch soon."
      }],
      "language": "en_US",
      "status": "APPROVED",
      "category": "TRANSACTIONAL",
      "id": "755551981307120"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MjQZD"
    }
  }

Retrieve a Template Namespace

The message template namespace is required to send messages using the message templates.

To get the namespace for a template, send a GET request to the /{whatsapp-business-account-ID} endpoint and include the message_template_namespace field.

Example Request

Formatted for readability.

curl -i -X GET "https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}
  ?fields=message_template_namespace
  &access_token={system-user-access-token}"

On success, a JSON object with the WhatsApp Business Account ID and namespace is returned:

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

Edit a Message Template

Available September 7, 2022

You can edit a message template by sending a POST request to the /{message_template-id} endpoint and include the name, language, category, components, with type set to BODY and text set to the content for the message, name, and language fields.

Some things to keep in mind before editing a message template.

A message template can only be edited when it is in a state of Approved, Rejected, or Paused.
When editing a live template, templates will be eligible for auto-approval. Templates that pass formatting and Business and Commerce Policy checks will go live again immediately, without any additional action needed to continue sending messages.
When editing a paused template, templates will be eligible for auto-approval. Templates that pass formatting checks and Business and Commerce Policy checks will be able to go live again. In order to begin sending messages again, businesses will have to call the messaging APIs.
Edits should be minor to correct small errors like spelling and grammar, or small tweaks to content. Edits should not change the category of the template (e.g. transactional vs promotional). For major edits which may change the template category, a new template should be created instead.
A message template can be edited once per day, up to 10 times a month.

Example Request

Formatted for readability.

curl -X POST "https://graph.facebook.com/v14.0/{message-template-ID}
  ?name={template-name}
  &language=en_US
  &category=MARKETING,
  &components=[{
       type:BODY, 
       text:{original-or-edited-message-text}
     }, 
     {
       type:HEADER, 
       format:IMAGE, 
       example:{header_handle:[{original-or-new-uploaded-image-file-url}]}
     }],
  &access_token={system-user-access-token}"

On success, a JSON object is returned:

{
  "success": true
}

Delete a Message Template

You can delete a message template by providing the message template name. Some things to keep in mind before deleting a message template:

If that message template name exists in multiple languages, all languages will be deleted.
Messages that have been sent but not delivered will attempt to be delivered for 30 days. An example of this is when the customer's device is offline.
If a message from an approved message template is sent 30 days after deletion, you will receive a "Structure Unavailable" error and the customer will not receive the message.
Once deleted, the name of an approved template cannot be used again for 30 days. Use a different name to create future templates.

To delete a template, send a DELETE request to the /{whatsapp-business-account-ID}/message_templates endpoint and include the name parameter set to the template name to be deleted.

Example Request

Formatted for readability.

curl -X DELETE "https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}/message_templates
  ?name=hello_world_template
  &access_token={system-access-token}"

On success, a JSON object is returned:

{
  "success": true
}

Learn More

Next Steps

Get Started with the Cloud API to start sending messages

WhatsApp Business Platform | Cloud API | On-Premises API | Business Management API