Creating & Sending WhatsApp Authentication Template

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 are able to 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

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

category Yes

Type of message template.

Template category.

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

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", "en_GB", "en_US"

Spanish: "es", "es_AR", "es_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 chose 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.

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.

HTTP Request: POST /whatsapp/messages

๐Ÿ“˜

NOTE

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

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

placeholders Yes

Array of components objects containing the verification code placeholder.

placeholders.code Yes

The one-time password or verification code to be delivered to the customer.

templateLanguage Yes

Copy the language configured when creating the template to be sent.

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:

ParameterDescription
dataData containing the Message object.
data.idUnique identifier of the WhatsApp message.
data.bodyContent of the text template message that will be sent to the end user.

For Authentication Templates the body is null.
data.fromPhone number of the sender.

Phone number provided during the WABA account setup will be used as the sender of the notification message.
data.toDetermines the destination phone number for your authentication template.

Numbers are specified in E.164 format โ†’ (โ€˜+โ€™ and a country code).
data.dateDate when the message has been sent.
data.statusDateDate when the last update or status change.
data.externalIdAlphanumeric identifier used for reporting purposes.
data.ownerOwner or creator of the message.
data.operatorUser who is a member of the owner or creatorโ€™s space.
data.statusWhen a Message is sent, the system assigns one of the following possible statuses to an WhatsApp message:

- "SENT": Message was sent to the outbound delivery system.

- "DELIVERED": Message was delivered to the end-device of the user.

- "READ": Message has been opened or acknowledged by the end user.
Note: The โ€œREADโ€ status may not be displayed because an end user can block the read option.

- "CODE_NOT_ALLOWED": Sender of the WhatsApp Business Account is not valid to send the message.

- "FAILED":Message delivery failed.

- "QUOTA_EXCEEDED": WhatsApp Business Account exceeded the message sending limits.
For more information about Messaging Limits go to: Capacity, Quality Rating, and Messaging Limits section.

- "EXPIRED": Message was too old to be sent.

- "INCOMPLETE": The placeholders (personalized fields) of the message sent through templates must be complete.
data.providerIdUnique identifier of the provider. The support team provides this Id once the account has been approved.