Guides

Creating & Sending WhatsApp Authentication Template

Suggest Edits

If your mobile app offers users the option to receive one-time passwords or verification codes via the WhatsApp app or WhatsApp Business app, you must use an authentication template with a one-time password button (OTP) to deliver the password or code.

Authentication templates with OTP buttons consist of the following:

  • The Body message is defined by META. That is, the body is fixed -> "<VERIFICATION_CODE> is your verification code."
  • Next to the Body text message, it is defined a security recommendation message (Security disclaimer message) as a boolean (optional) by META: "For your security, do not share this code."
  • From the Footer, you can add an Expiration warning message (optional): "This code expires in <NUM_MINUTES> minutes."
  • It is mandatory to add an OTP button. Either a copy code button.
    Authentication templates must include either a copy code button. A copy code button copies the one-time password or code to the user's clipboard. The user can then manually switch to your app and paste the password or code into your app's interface.

📘

NOTE

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

Therefore, we recommend you (mandatory) create a new Authentication Template if you are still sending this category type (Authentication) without an OTP button.

Therefore, an authentication template with an OTP button consists of the following content:

  • Fixed preset text:

    • <VERIFICATION_CODE> is your verification code.
    • Security disclaimer (optional): For your security, do not share this code.
    • Expiration warning (optional): This code expires in <NUM_MINUTES> minutes.

  • Button: a copy code.

Let’s replicate the next example:

Creating Authentication Template

If you want to create the authentication template via Templates API, you need to provide the WhatsApp Business Account ID (WABA) or the unique identifier of the sender, and enter the following parameters to the request body:

🚧

WARNING

Enter only one of the required parameters (wabaId or senderId), not both.

HTTP Request: POST /whatsapp/templates

Required ParameterDescription
wabaIdWhatsApp Business Account ID (WABA).

In case you don't have a WABA Id, our support team will provide it to you.
senderIdUnique identifier of the Sender.

The following authentication template 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": 15
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "OTP",
              "otp_type": "COPY_CODE",
              "text": "Copy Code"
            }
          ]
        }
      ]
    }
  ]
}

In your POST call, include the following parameters to create an authentication template:

Parameter Required Description
name Yes

Name of the template created in your WhatsApp Business Account.

The name of each template you create cannot be the same.
category Yes

Type of message template.

Supported Template Categories for WhatsApp Authentication Template.

  • "AUTHENTICATION": Send codes that allow your customers to securely access their accounts.
autoCategory No

Allow to assign or change the selected category according to the rules and content of the template. Avoid being rejected for being wrongly categorized

  • true: authorize META to change the category type if necessary. Costs may vary for the new category.
  • false: not authorize META to change the category type.
templateLanguages Yes

Array of languages objects containing the language that 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 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 template components you can include in the 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 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 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 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.

Regardless of the types of objects you choose to customize the authentication template, the response body provides you with the WhatsApp Business Account ID (WABA) ("wabaId") and the template id ("id"), which will allow you to get information, delete from a specific template, list templates, or send it.

📘

Retrieving the Status of a WhatsApp Template

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

  • Get Template: Returns the status of a specific template.
  • List Templates: Returns a list of all templates associated with the WABA, including the current status of each.

These endpoints help you verify whether a template has been approved by WhatsApp, is under review, or requires further action.

Below are the possible statuses a WhatsApp template can return, along with their meanings:

StatusDescription
APPROVEDThe template has been reviewed and accepted by Meta. It is now active and can be used in message campaigns.
PENDINGThe template has been submitted and is awaiting initial processing.
PENDING_APPROVALThe template is under review by Meta and is waiting for final approval.
REJECTEDThe template was reviewed and not approved due to content violations or formatting issues. A new version may need to be submitted.
IN_APPEALAn appeal has been submitted for a previously rejected template. It is under re-evaluation.
PAUSEDThe template has been temporarily paused and cannot be used until reactivated.
LIMIT_EXCEEDEDThe template has reached usage or submission limits as defined by Meta. Further use is restricted until limits reset or are adjusted.
DISABLEDThe template has been disabled and is no longer available for use.
DELETEDThe template has been permanently deleted from the account.
PENDING_DELETIONThe template is in the process of being deleted and will no longer be available once deletion is completed.

Sending Authentication Template

Once the authentication template has been created via API and approved, the next step is sending the template to the end users through the Messages API.

🚧

NOTE

The one-time password or verification code to be delivered to the customer must appear twice in the payload.

When sending a WhatsApp Authentication 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 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.

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

Parameters present in the request body example when sending an Authentication Template are the following:

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 template. Numbers are specified in E.164 format → (‘+’ and a country code).

templateName Yes

Name of the 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

Template Language you set when creating the template.

Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send 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 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.

When you sent the Authentication Template, the response body contains the following data:

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

Parameters presented in the response body example when creating the Authentication Template are the following:

Parameter Description
data Data contained in the Message object.
data.
id		 Unique identifier of the WhatsApp message.
data.
body

Content of the authentication template message that will be sent to the end user.

For Authentication 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 space.
data.
status

When a Message is sent, the system assigns one of the following possible statuses to an WhatsApp message:

  • "CODE_NOT_ALLOWED": Messangi 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": Messangi 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": Messangi 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 campaign, 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": Messangi 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.

Updated 7 days ago