Creating & Sending WhatsApp Authentication Message Template

Create and send a WhatsApp authentication message template with a copy-code one-time password (OTP) button.

Authentication message templates with OTP buttons include:

A fixed body message defined by Meta: "<VERIFICATION_CODE> is your verification code."
An optional security recommendation in the body: "For your security, do not share this code."
An optional footer expiration warning: "This code expires in <NUM_MINUTES> minutes."
A required copy-code OTP button. The button copies the verification code to the user’s clipboard so they can paste it into your app.

📘
Unsupported Elements
URLs, media, and emojis are not supported. Because authentication message templates with OTP buttons only consist of preset (fixed) text and buttons, their risk of being paused is significantly minimized.

Create a new authentication message template if you currently send authentication templates without an OTP button.

Use the following example as a reference:

Create an authentication message template

To create an authentication message template with the Message Templates API, provide either the WhatsApp Business Account ID (WABA) or the sender’s unique identifier in the request body.

🚧
Single Parameter Rule
Type only one of the required parameters (not both):

wabaId

senderId

HTTP Request: POST /whatsapp/templates

Required Parameter	Description
wabaId	WhatsApp Business Account ID (WABA).
senderId	Unique identifier of the Sender.

The following example includes a body, footer, and OTP button.

{
  "name": "dev_authentication_template",
  "category": "AUTHENTICATION",
  "templateLanguages": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "securityRecomendation": true
        },
        {
          "type": "FOOTER",
          "expirationMinutes": 5
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "OTP",
              "otp_type": "COPY_CODE",
              "text": "Copy Code"
            }
          ]
        }
      ]
    }
  ]
}

Include the following parameters in the POST request to create an authentication message template:

Parameter	Required	Description
name	Yes	Name of the message template created in your WhatsApp Business Account. The name of each message template you create cannot be the same.
category	Yes	Type of message template. Supported Message Template Categories for WhatsApp Authentication Message Template. `"AUTHENTICATION"`: Send codes that allow your customers to securely access their accounts.
templateLanguages	Yes	Array of languages objects containing the language that message template may be rendered in and the components.
templateLanguages. language	Yes	Language of the message template. Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send message templates in languages other than English. English: `"en"` Spanish: `"es"` Portuguese: `"pt_BR"`, `"pt_PT"`
templateLanguages. components	Yes	The parts of the message template. Array of components objects containing the different types of options you can include in the message.
templateLanguages. components. type	Yes	Type of component of the message template you want to send. There are three optional main message template components you can include in the message template: `"BODY"`: Content of the message template. `"FOOTER"` Short line of text to the bottom of your message. `"BUTTONS"`Button type located at the end of the message.
templateLanguages. components. securityRecomendation	No	Only applies to the `"BODY"` type. Boolean. Set `true` if you want the message template to include the string: `"For your security, do not share this code."` Set `false` to exclude the string.
templateLanguages. components. expirationMinutes	No	Only applies to the `"FOOTER"` type. Integer. Indicates the number of minutes the password or code is valid. If omitted, the code expiration warning will not be displayed in the delivered message. Minimum 1, maximum 90.
templateLanguages. components. buttons	Yes	Only applies to the `"BUTTONS"` type. Array of Buttons type options you can include to the message template.
templateLanguages. components. buttons. type	Yes	Only applies to the `"BUTTONS"` type. Buttons Type option. The buttons object contains the following option: `"OTP"`: one-time password button (OTP) to deliver the password or code.
templateLanguages. components. buttons. otp_type	Yes	Only applies to the `"BUTTONS"` type. Set to `"COPY_CODE"` value if you want the message template to use a copy code button
templateLanguages. components. buttons. text	Yes	Only applies to the `"BUTTONS"` type. Copy code button text. Maximum 25 characters.

The response includes the WhatsApp Business Account ID ("wabaId") and message template ID ("id"). Use these values to retrieve, delete, list, or send the template.

📘
Retrieving the Status of a WhatsApp Message Template
After creating a WhatsApp message template, it is important to monitor its approval status, as this determines whether the message template can be used in messaging communications. We provide two API endpoints that allow users to retrieve the current status of each message template created:

Get Message Template: Returns the status of a specific message template.

List Message Templates: Returns a list of all message templates associated with the WABA, including the current status of each.

These endpoints help you verify whether a message template has been approved by WhatsApp, is under review, or requires further action.
Below are the possible statuses a WhatsApp message template can return, along with their meanings:

Status Description
APPROVED The message template has been reviewed and accepted by Meta. It is now active and can be used in outbound communications.
PENDING The message template has been submitted and is awaiting initial processing.
PENDING_APPROVAL The message template is under review by Meta and is waiting for final approval.
REJECTED The message template was reviewed and not approved due to content violations or formatting issues. A new version may need to be submitted.
IN_APPEAL An appeal has been submitted for a previously rejected message template. It is under re-evaluation.
PAUSED The message template has been temporarily paused and cannot be used until reactivated.
LIMIT_EXCEEDED The message template has reached usage or submission limits as defined by Meta. Further use is restricted until limits reset or are adjusted.
DISABLED The message template has been disabled and is no longer available for use.
DELETED The message template has been permanently deleted from the account.
PENDING_DELETION The message template is in the process of being deleted and will no longer be available once deletion is completed.

Status	Description
`APPROVED`	The message template has been reviewed and accepted by Meta. It is now active and can be used in outbound communications.
`PENDING`	The message template has been submitted and is awaiting initial processing.
`PENDING_APPROVAL`	The message template is under review by Meta and is waiting for final approval.
`REJECTED`	The message template was reviewed and not approved due to content violations or formatting issues. A new version may need to be submitted.
`IN_APPEAL`	An appeal has been submitted for a previously rejected message template. It is under re-evaluation.
`PAUSED`	The message template has been temporarily paused and cannot be used until reactivated.
`LIMIT_EXCEEDED`	The message template has reached usage or submission limits as defined by Meta. Further use is restricted until limits reset or are adjusted.
`DISABLED`	The message template has been disabled and is no longer available for use.
`DELETED`	The message template has been permanently deleted from the account.
`PENDING_DELETION`	The message template is in the process of being deleted and will no longer be available once deletion is completed.

Send an authentication message template

After the template is created and approved, send it to end users through the Messages API.

🚧
OTP Placement Rule
The one-time password or verification code to be delivered to the customer must appear twice in the payload.
When sending a WhatsApp Authentication message template through the API, the user is responsible for including the required authentication code as part of the request payload. This code must be placed in the request body, mapped into two specific parameters: placeholders.code, templateButtons.values.value.
The client may choose to generate and manage the authentication codes independently. This can be done either through an internal system or by integrating with a third-party service.
Regardless of the generation method:

The authentication code must be present in the request when sending the message template.

If the code is missing or empty, the API will return a failure or the delivery will be marked as INCOMPLETE, as the message cannot be rendered correctly.

📘
Message Throughput (TPS)
To know about delivery throughput and how TPS is applied across channels (WhatsApp), go to the Message throughput and rate limits section.

HTTP Request: POST /whatsapp/messages

{
    "from": "1000000001",
    "to": "+1000000002",
    "templateName": "dev_authentication_template",
    "placeholders": {
        "code": "982012"
    },
    "templateLanguage": "en_US",
    "templateButtons": [
       {
          "type": "cta",
          "values": [
              {
                  "index": 0,
                  "value": "982012"
              }
          ]
      }
    ]
}

The following parameters are included in the request body for an authentication message template:

Parameter	Required	Description
from	Yes	Phone number of the sender. Phone number provided during the WABA account setup will be used as the sender of the notification message. Only accepts numeric characters. Do not include the "+" sign.
to	Yes	Determines the destination phone number for your authentication message template. Numbers are specified in E.164 format → (‘+’ and a country code).
templateName	Yes	Name of the message template created in your WhatsApp Business Account.
placeholders	Yes	Object of personalized field (placeholder) containing the verification code placeholder.
placeholders. code	Yes	The one-time password or verification code to be delivered to the customer.
templateLanguage	Yes	Message Template Language you set when creating the message template. Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send message templates in languages other than English. English: `"en"`, `"en_GB"`, `"en_US"` Spanish: `"es"`, `"es_AR"`, `"es_ES"` Portuguese: `"pt_BR"`, `"pt_PT"`
templateButtons	Yes	Array that contains the copy code button for a Call To Action Button.
templateButtons. type	Yes	Button type. One-time password button (OTP) is equivalent to a Call To Action button (`"cta"`).
templateButtons. values	Yes	Array that contains the Message Template button values.
templateButtons. values. index	Yes	Set `0` as the position index of the button.
templateButtons. values. value	Yes	The one-time password or verification code to be delivered to the customer.

A successful request returns the following response body:

{
  "meta": {
    "timestamp": 170562,
    "transactionId": "ca811177-8e36-46e6-aec"
  },
  "data": {
    "id": "65a9cf4736e18",
    "body": null,
    "from": "1000000001",
    "to": "+1000000002",
    "date": "2024-01-19T01:24:23.510578992Z",
    "statusDate": "2024-01-19T01:24:23.510361335Z",
    "externalId": null,
    "owner": "[email protected]",
    "operator": "[email protected]",
    "status": "QUEUED",
    "providerId": null
  }
}

The following fields are included in the response body:

Parameter	Description
data	Data contained in the Message object.
data. id	Unique identifier of the WhatsApp message.
data. body	Content of the authentication message template that will be sent to the end user. For Authentication Message Templates the body is `null`
data. from	Phone number of the sender. Phone number provided during the WABA account setup will be used as the sender of the notification message. Only accepts numeric characters. Do not include the "+" sign.
data. to	Determines the destination phone number for your message. Numbers are specified in E.164 format → (‘+’ and a country code).
data. date	Date when the message has been sent.
data. statusDate	Date when the last update or status change.
data. externalId	Alphanumeric identifier used for reporting purposes.
data. owner	Owner or creator of the message.
data. operator	User who is a member of the owner or creator’s Workspace.
data. status	When a Message is sent, the system assigns one of the following possible statuses to an WhatsApp message: `"CODE_NOT_ALLOWED"`: The platform suggests that the WhatsApp Business Account (WABA) used is either not activated on the platform or lacks the capability to message the recipient. Additionally, it could be because the owner does not have a WABA assigned , which is required to send the message. Contact our support team to verify the WABA. `"INCOMPLETE"`: The platform indicates that a personalized WhatsApp message was sent without the necessary placeholder data filled in. Please note, personalized messages are those that feature dynamic fields—like "Name", "Phone Number", "Last Name", and similar—which need to be populated before sending. `"BLACKLISTED"`: The platform indicates that the intended recipient's phone number is on a blacklist, preventing any messages from being sent to that number. When a number is blacklisted, it is essentially blocked from receiving any further communications from the sender's number or broadcast, ensuring that no messages are delivered to that recipient. `"QUOTA_EXCEEDED"`: The WhatsApp Business Account (WABA) has surpassed the allowed limit for sending messages within a specified period, as defined by WhatsApp's messaging policies or limits. `"SENT"`: Indicates that the message has been successfully dispatched from our system and is en route to META. This status means that the message is on its way to the recipient but does not confirm that the message has been delivered to the end user. It signifies a successful handoff to the next stage in the message delivery process. `"DELIVERED"`: The platform has received confirmation of message delivery from META. The message has successfully reached the recipient's device. This status confirms that the message not only was sent and processed by META but also was received by the intended recipient's WhatsApp application, ensuring that the communication was successfully completed. `"READ"`: Indicates that the recipient has opened and seen the message. `"FAILED"`: Indicates that META could not deliver the message to the recipient's device.
data. providerId	Unique identifier of the provider. The support team provides this Id once the account has been approved.