Create and Manage Message Templates

For any notifications sent using the WhatsApp Business Platform, a message template is required. These templates can be created either in the Business Management API or through the WhatsApp Business Manager's.

This document explains how to create, retrieve, 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
• A URL for any document, image, or video file to be included in a medai template. Media files need to be uploaded to the Meta Social Graph before they can be used in a template. Learn more.

Limitations

• The message template name field is limited to 512 characters.
• The message template content field is limited to 1024 characters.
• A template can not be updated. We recommend using a test account when learning how to create templates.
• A WhatsApp Business Account can only create 100 message templates per hour.
• WhatsApp Business Account 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 proces, 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.

curl -X POST "https://graph.facebook.com/v13.0/{whatsapp-business-account-ID}/message_templates
  ?name={template-name}
  &language=en_US
  &category=ISSUE_RESOLUTION,
  &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.

curl -X POST "https://graph.facebook.com/v13.0/{whatsapp-business-account-ID}/message_templates
  ?name={template-name}
  &language=en_US
  &category=ISSUE_RESOLUTION,
  &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}"
}

Parameters

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

curl -i -X GET "https://graph.facebook.com/v13.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": "ISSUE_RESOLUTION",
      "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": "TICKET_UPDATE",
      "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": "TICKET_UPDATE",
      "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

curl -i -X GET "https://graph.facebook.com/v13.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" 
}

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

curl -X DELETE "https://graph.facebook.com/v13.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