Message Templates

For any notifications sent using the WhatsApp Business API, a message template is required. Those templates can be created either in the Business Manager's user interface (https://business.facebook.com/wa/manage/message-templates/?business_id=your-business-id) or through the WhatsApp Business Management API.

WhatsApp Business Account message templates

Some important things to note:

1. We support create and delete. Editing a template is not yet available.
2. The Create API call allows you to add a message template in a specific language.
3. The Delete API call allows you to delete all translations of a message template you specify by name.
4. When you create a message template, make sure to be consistent when providing translations.
   • If you don't do that, you might see a structure unavailable error and notifications won't be delivered.
   • See the Why am I seeing 'structure unavailable' errors in my callback? FAQ for more information about this.

Creating Message Templates

You can use the WhatsApp Business Management API to create new message templates, media message templates, or interactive message templates.

Message Template Request

curl -X POST \ 
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'category=ISSUE_RESOLUTION' \
  -d 'components=[{"type":"BODY", "text":"your-message-text"}]' \
  -d 'name=hello_world_template' \
  -d 'access_token=your-access-token' \
  -d 'language=en_US'

Media Message Template Request

curl -X POST \ 
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'category=ISSUE_RESOLUTION' \
  -d 'components=[{"type":"BODY", "text":"your-message-text"}, {"type":"HEADER", "format":"IMAGE", "example": {"header_handle":["your-file-handle"]}}]' \
  -d 'name=hello_world_template' \
  -d 'access_token=your-access-token' \
  -d 'language=en_US'

Note: File handles can be generated using the Resumable Upload API.

Interactive Message Template Request

curl -X POST \ 
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'category=ISSUE_RESOLUTION' \
  -d 'components: [{"type":"BODY","text":"your-body-text {{1}} {{2}} {{3}}","example":{"body_text":[["your-body-example-1","your-body-example-2","your-body-example-3"]]}},{"type":"HEADER","format":"TEXT","text":"your-header-text {{1}}","example":{"header_text":["your-header-example"]}},{"type":"FOOTER","text":"your-footer-text"},{"type":"BUTTONS","buttons":[{"type":"PHONE_NUMBER","text":"your-phone-button-text","phone_number":"+1(650) 555-1111"},{"type":"URL","text":"your-url-button-text","url":"https://www.website.com/{{1}}","example":["https://www.website.com/dynamic-url-example"]}]}]' \
  -d 'name=hello_world_template' \
  -d 'access_token=your-access-token' \
  -d 'language=en_US'

Parameters

The components parameter

The BUTTONS component type

Response

{
  "id": "952305634918767"
}

You can then use the returned id in a GET call to obtain information about this message template.

Retrieving Message Templates

You can use the WhatsApp Business Management API to get a list of your existing message templates. Please note that the limit parameter is optional.

Request

curl -i -X GET \
'https://graph.facebook.com/v3.3/your-whatasapp-business-account-id/message_templates?limit=3&access_token=your-access-token'

Response

{
  "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"
    }
  }

Pagination

Looping through all the message templates from a WhatsApp Business Account may require more than one API call. The mechanism for this pagination is described in the Graph API documentation and uses the paging field in the response. For message templates, there are a few differences:

1. When a message template is returned, we always include all its translations (if any). Message templates are grouped by the name field.
2. The Graph API limit parameter defines the maximum number of objects returned in a single API call. For message templates, the difference is this limit applies to the maximum number of message template names that may be returned, not the maximum number of objects. If a message template has translations, the number of objects will be larger, as every translation is included in the API response.

Retrieving the Message Template Namespace

The message template namespace is required to send messages using the message templates in the WhatsApp business account.

Request

curl -i -X GET "https://graph.facebook.com/v8.0/your-whatsapp-business-account-id?fields=message_template_namespace&access_token=your-system-user-access-token"

Response

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

Deleting Message Templates

You can use the WhatsApp Business Management API to delete your message templates 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 (e.g., if the customer's device is offline) will attempt to be delivered for 30 days.
• 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.

Request

curl -X DELETE \
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'name=hello_world_template' \
  -d 'access_token=your-access-token' 

Response

{
  "success": true
}

Reference

For a list of all possible values for each field, refer to the Graph API reference of the message_templates endpoint.