WhatsApp Business Platform > Business Management API > Guides

Create and Manage Message Templates

A message template is required for any business-initiated messages sent using the WhatsApp Business Platform. These templates can be created using the Business Management API or the WhatsApp Business Manager.

The number of templates a WhatsApp Business Account can have is determined by its parent business. If a parent business is unverified, each of its WhatsApp Business Accounts is limited to 250 templates. However, if the parent business is verified and at least one of its WhatsApp Business Accounts has a business phone number with an approved display name, each of its WhatsApp Business Accounts can have up to 6,000 templates.

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.

Localization

You can add a message template in a specific language when creating a template. These templates count against your limit. Be consistent when providing translations. See the Why am I seeing 'structure unavailable' errors in my callback? help center article for more information.

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.

Valid values for category are: TRANSACTIONAL, MARKETING, OTP.

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/v15.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/v15.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 .

Best Practices for Marketing Templates

Marketing Opt-Out Button

We recommend that you add an opt-out button to your marketing templates. This will give users an option to opt out of your marketing messages without having to block your business. As a result, you may be able to scale messaging volume faster on WhatsApp. Please refer to this article for further details on the benefits of the marketing opt-out button and guidance on when to add it.

The following POST request demonstrates how to incorporate this button into your message templates.

curl -X POST "https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}/message_templates
{ 
  "name": "promotional_message",
  "language": "en_US",
  "category": "TRANSACTIONAL",
  "components": [{
           "type":"BODY",
           "text":"Hi {{1}}, get an extra 10% off every order above $300.",
           "example":{"body_text":[["Sonia"]]}
         },
         {
           "type":"HEADER",
           "format":"TEXT",
           "text": "Bonus Tuesday starts now!"
         },
         {
           "type":"FOOTER",
           "text":"Not interested? Tap Stop promotions"
         },
         {
           "type":"BUTTONS",
           "buttons":[{"type":"QUICK_REPLY", "text": "Shop now"},
            {"type":"QUICK_REPLY", "text": "Stop promotions"}]
         }]  
}

On success, a JSON object with the message template id is returned:

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

Your business must take the necessary steps to stop sending marketing messages to customers who have chosen to opt-out of receiving them. Not doing so will negatively impact your block rate and quality score.

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/v15.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/v15.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

You can edit a message template by sending a POST request to the /{message_template-id} endpoint. Editing a template replaces its old contents entirely, so include any components you wish to preserve as well as components you wish to update using the components parameter.

Notes:

Message templates can only be edited when in an Approved, Rejected, or Paused state.
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.
Message templates in an Approved state can be edited up to 10 times in a 30 day window, or 1 time in a 24 hour window. Messages in Rejected or Paused states can be edited an unlimited number of times.

Example Request

Formatted for readability.

curl -X POST "https://graph.facebook.com/v15.0/{message-template-id}
  &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/v15.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