Authentication templates overview

If you give your 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:

• Preset authentication message template fixed 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: Either a copy code or one-tap autofill button.

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

Create a new authentication template using the template creator

1. The easiest way to create an authentication template is to use the WhatsApp Template Manager. From the WhatsApp template manager provide a template name, select the language(s) the template will be sent in and set the category as authentication.
2. Select the type of authentication template type that you want to use. Either:

• Copy Code - A copy code button copies the one-time password or code to the user's clipboard. The user can then manually switch to your login screen and paste the password or code.
  
• *One Tap** - A one-tap autofill button automatically loads and passes your app the one-time password or code. This offers the best user experience, but one-tap buttons are only supported on an android device where the end user is also running your application. See additional requirements for one tap
  

3. Regardless of authentication template type you have chosen you can choose to include a security warning and an expiry time.
   

• *Security warning** - this will add localised text to the message warning a user not to share a code. As an example in English - "For your security, do not share this code.""
• *Expiration warning** - this will add a localised text to the message informing the user when the code will expire. As an example in English - "This code expires in NUM_MINUTES minutes.""
  • If you opt to add an expiration warning then provide the number of minutes the code will be valid for

4. Complete the remaining fields
   

• If you have selected the authentication template type of "Copy Code" you will then need to enter the localised text that will be displayed on the button in the message.
• If you have selected the authentication template type of "One Tap" you will then need to enter localised text for both the one tap button and also a copy code button which will be used as a fallback on unsupported devices. Also fill in your android package name and signature hash. See additional requirements for one tap

Create a new authentication template via the API

It is also possible to create an authentication template via the API. You can create a template by sending the following request.

Example for Copy Code

curl -X "POST" "https://integrations.messagebird.com/v2/platforms/whatsapp/templates" \
     -H 'Authorization: AccessKey <access-key>' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'{
  "name": "copy_code_authentication_template",
  "wabaId": "169743163687422",
  "category": "AUTHENTICATION",
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Copy Code"
        }
      ]
    }
  ]
}
'

Example for One Tap

curl -X "POST" "https://integrations.messagebird.com/v2/platforms/whatsapp/templates" \
     -H 'Authorization: AccessKey <access-key>' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'{
  "name": "one_tap_authentication_template",
  "wabaId": "169743163687422",
  "category": "AUTHENTICATION",
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "text": "Copy Code",
          "autofill_text": "Autofill",
          "package_name": "com.example.luckyshrub",
          "signature_hash": "K8a%2FAINcGX7"
        }
      ]
    }
  ]
}
'

Send an authentication template

Once your template has been approved by Meta to send the template you must perform a HTTP request to the Conversations API. For both one tap and copy code templates the request is the same

curl -X "POST" "https://conversations.messagebird.com/v1/send" \
     -H 'Authorization: AccessKey <access-key>' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "to": "+3197006520256",
  "from": "320b489e-d1dc-409a-900d-fd5812f8078a",
  "type": "hsm",
  "content": {
    "hsm": {
      "namespace": "20332cd4_f095_b080_d255_35677159aaff",
      "templateName": "auth_one_tap_otp_button",
      "language": {
        "code": "en_US"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "12345"
            }
          ]
        },
        {
          "type": "button",
          "sub_type": "url",
          "index": 0,
          "parameters": [
            {
              "type": "text",
              "text": "12345"
            }
          ]
        }
      ]
    }
  }
}
'

• content.hsm.namespace can be found in the WhatsApp templates Manager of your Facebook Business account, or, in case you don't have access to it, please contact our support team
• content.hsm.language.code is the language which the template message should be sent
• content.hsm.templateName is the template name
• to is the phone number of the recipient
• type must be hsm because this is a template message
• from must be your WhatsApp channel ID
• content.hsm.components contains a list of components that will be used to replace the variables in the template.
  • type defines the type of the component, in this case body and button. Both components must be present in the template
  • sub_type defines the type of button, in this case a url
  • parameters contains a list of parameters to provide values to variables
    • type defines the type of value, in this case text
    • text provides the value that must be used in the variable. For both body and button components, the value should be the same