Create and Manage Templates

Templates are used when sending template messages with either the Cloud API, hosted by Meta, or the On-Premises API. Cloud API reviews templates and variable parameters using machine learning to protect the security and integrity of Cloud API services. When Cloud API reviews templates and variable text, no information is shared with WhatsApp.

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.

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.
• Templates composed of 4 or more buttons, or a quick reply button and one or more buttons of another type, cannot be viewed on WhatsApp desktop clients. WhatsApp users who receive one of these template messages will be prompted to view the message on a phone instead.

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.

Creating Templates

Send a POST request to the WhatsApp Business Account > Message Templates endpoint to create a template.

Request Syntax

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

Post Body

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": <ALLOW_CATEGORY_CHANGE>,
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

Body Properties

Template Categories

Templates must be categorized as one of the following categories. Categories factor into pricing and the category you designate will be validated at the time of template creation.

• AUTHENTICATION
• MARKETING
• UTILITY

Refer to our Template Categorization document to determine which category to use when creating templates.

Template Components

Templates are composed of various text, media, and interactive components, based on your business needs. Refer to the Template Components document for a list of all possible components and their requirements as well as samples and example queries.

When creating a template, define its components by assigning an array of component objects to the components property in the body of the request.

For example, here's an array containing a text body component with two variables and sample values, a phone number button component, and a URL button component:

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
    "example": {
      "body_text": [
        [
          "Pablo","860198-230332"
        ]
      ]
    }
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "PHONE_NUMBER",
        "text": "Call",
        "phone_number": "15550051310"
      },
      {
        "type": "URL",
        "text": "Contact Support",
        "url": "https://www.luckyshrub.com/support"
      }
    ]
  }
]

Refer to the Template Components document for a list of all possible components and their requirements as well as samples and example queries.

Note that templates categorized as AUTHENTICATION have unique component requirements. See Authentication Templates.

Category Validation

When you send a template creation request, we immediately validate its category using our template categorization guidelines.

• If we agree with the category you designated, we create the template and set its status to PENDING. The template then undergoes template review.
• If we disagree with your designation, we create the template, but set its status to REJECTED and trigger a message template status update webhook with reason set to INCORRECT_CATEGORY. We recommend that you listen for this webhook to identify rejected templates, or request the rejected_reason field on newly created templates, which will have the value TAG_CONTENT_MISMATCH.

In both cases, the template's initial status is returned as part of the API response.

If your template status has been set to REJECTED as part of category validation, you have several options:

• Edit the template's components so they align with our guidelines.
• Edit the template's category so it aligns with our guidelines.
• Create a new template.

Automatic Categorization

You can include the allow_category_change property in your request to have us automatically assign a category based on your template's contents and our template categorization guidelines. This can prevent your template's status from immediately being set to REJECTED due to miscategorization.

Note that automatic categorization is only possible when creating a template.

Template Review

Templates with a status of PENDING are undergoing template review. We review the contents of each newly created or edited template to make sure it adheres to our content guidelines and policies. Based upon the outcome of this review, we automatically change its status to APPROVED or REJECTED, which triggers a message template status update webhook.

Template Status

Based on the outcome of category validation and template review, we set or change your template's status to one of the following values:

• APPROVED — The template has passed template review and been approved, and can now be sent in template messages.
• PENDING — The template passed category validation and is undergoing template review.
• REJECTED — The template failed category validation or template review. You can request the rejected_reason field on the template to get the reason.

See that WhatsApp Message Template endpoint reference for all possible fields and statuses.

Response

Upon success, the API responds with the newly created template's ID, status, and category. There are three possible outcomes:

• We agreed with the category you designated and the template is now undergoing template review (status is PENDING).
• We disagreed with the category you designated (status is REJECTED)
• We automatically approved the template (status is APPROVED). This is only possible for authentication templates with one-time password buttons.

{
    "id": "<ID>",
    "status": "<STATUS>",
    "category": "<CATEGORY>"
}

Response Properties

Example Request

Here's an example request to create a seasonal promotion template composed of the following components:

• a text header
• a text body
• a footer
• two quick-reply buttons

For additional examples, see Example Requests.

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Example Response

{
    "id": "572279198452421",
    "status": "PENDING",
    "category": "MARKETING"
}

Sending Templates

Use the Cloud API or On-Premises API to send a template in a template message.

Time-To-Live (TTL): Customization, Defaults, Min/Max Values, and Compatibility

If we are unable to deliver a message to a WhatsApp user, we will retry the delivery for a period of time known as a time-to-live, TTL, or the message validity period.

You can customize the default TTL for authentication, utility, and marketing templates.

We encourage you to set a TTL for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable.

Defaults, Min/Max Values, and Compatibility Table

How to Customize TTL for Your Template

To set a custom TTL on an authentication, utility, or marketing template, include and set the value of the message_send_ttl_seconds property in the POST /<PHONE_NUMBER_ID>/messages call.

TTL can be customized in 1 second increments.

Valid message_send_ttl_seconds property values

• Authentication templates: 30 to 900 seconds (30 secs to 15 mins)
• Utility templates: 30 to 43200 seconds (30 secs to 12 hours)
• Marketing templates: 43200 to 2592000 (12 hours to 30 days)

For authentication and utility templates, you can set the message_send_ttl_seconds property value to -1, which will set a custom TTL of 30 days.

When TTL is exceeded: Dropped messages

Messages that are unable to be delivered within the default or customized TTL are dropped.

If you do not receive a delivered message webhook before the TTL is exceeded, assume the message was dropped.

If you send a message that fails to deliver, there could be a minor delay before you receive the webhook, so you may wish to build in a small buffer before assuming the message was dropped.

Best Practices for Marketing Templates

Marketing Opt-Out Button

We recommend that you add a Quick Reply button to templates categorized as MARKETING that makes it easy for customers to opt-out of your marketing messages. This gives your customers the 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. Please refer to this article for further details on the benefits of adding an opt-out button to your marketing templates.

Getting Templates

Send a GET request to the WhatsApp Business Account > Message Templates endpoint to get a list of templates owned by a WhatsApp Business Account.

Request Syntax

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?fields=<FIELDS>
  &limit=<LIMIT>

Query String Parameters

Example Request

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name,status&limit=3' \
-H 'Authorization: Bearer EAAJB...'

Example Response

{
  "data": [
    {
      "name": "seasonal_promotion_text_only",
      "status": "APPROVED",
      "id": "564750795574598"
    },
    {
      "name": "seasonal_promotion_video",
      "status": "PENDING",
      "id": "1252715608684590"
    },
    {
      "name": "seasonal_promotion_image_header",
      "status": "PENDING",
      "id": "1372429296936443"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
  }
}

Example Request (Rejected Templates)

You can return only templates with specific field values by including the field and the desired value in your request. For example, include status=REJECTED to only get templates that have been rejected.

curl 'https://graph.facebook.com/v21.0/104996122399160/message_templates?fields=name,status&status=REJECTED' \
-H 'Authorization: Bearer EAAJB...'

Example Response

{
  "data": [
    {
      "name": "seasonal_promotion_text_only_v4",
      "status": "REJECTED",
      "id": "564750795574598"
    },
    {
      "name": "discount_qualifier",
      "status": "REJECTED",
      "id": "163917509772674"
    },
    {
      "name": "limited_time_offer_tuscan_getaway_2023",
      "status": "REJECTED",
      "id": "202389039167147"
    },
    {
      "name": "2023_mar_promo_2",
      "status": "REJECTED",
      "id": "1116034925734553"
    },
    {
      "name": "2023_mar_promo",
      "status": "REJECTED",
      "id": "952600926095321"
    }
  ]
}

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/v21.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" 
}

Editing Templates

Send a POST request to the WhatsApp Message Template endpoint to edit a template. You can also edit a template manually using the WhatsApp Manager > Account tools > Message templates panel.

Limitations

• Only templates with an APPROVED, REJECTED, or PAUSED status can be edited.
• You can only edit a template's category or components.
• You cannot edit the category of an approved template.
• Approved templates can be edited up to 10 times in a 30 day window, or 1 time in a 24 hour window. Rejected or paused templates can be edited an unlimited number of times.
• After editing an approved or paused template, it will automatically be approved unless it fails template review.

Request Syntax

POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>

Post Body

{
  "category": "<CATEGORY>",
  "components": [<COMPONENTS>]
}

Properties

Example Request (Editing Components)

Example request to a template's body text which contained both marketing and utility content to only contain marketing content.

curl 'https://graph.facebook.com/v21.0/564750795574598' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubcribe from Promos"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Example Request (Editing Category Only)

Example request to change template's category from UTILITY to MARKETING.

curl 'https://graph.facebook.com/v21.0/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "category": "MARKETING"
}'

Example Response

Example response upon success.

{
  "success": true
}

Deleting Templates

Use the WhatsApp Business Account > Message Templates endpoint to delete a template by name or by ID.

Notes

• If you delete a template that has been sent in a template message but has yet to be delivered (e.g. because the customer's phone is turned off), the template's status will be set to PENDING_DELETION and we will attempt to deliver the message for 30 days. After this time you will receive a "Structure Unavailable" error and the customer will not receive the message.
• Names of an approved template that has been deleted cannot be used again for 30 days.

Deleting by name

Deleting a template by name deletes all templates that match that name (meaning templates with the same name but different languages will also be deleted).

Request Syntax

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>

Example Request

curl -X DELETE 'https://graph.facebook.com/v16.0/102290129340398/message_templates?name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Example Response

{
  "success": true
}

Deleting by ID

To delete a template by ID, include the template's ID along with its name in your request; only the template with the matching template ID will be deleted.

Request Syntax

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?hsm_id=<HSM_ID>,
  &name=<NAME>

Example Request

curl -X DELETE 'https://graph.facebook.com/v21.0/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Example Response

{
  "success": true
}

Learn More

Graph API – Pagination Message Templates Reference Phone Numbers Supported Languages

Upload Files to the Social Graph WhatsApp Business Manager - Message Templates

Next Steps

• Get Started with the Cloud API to start sending messages