Verify API - Get started with WhatsApp

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page walks you step-by-step through how to use the Telesign Verify API to send a WhatsApp message to an end user with a one-time passcode (OTP) and how to create and use a custom WhatsApp template. It also explains how to complete the verification process, either to test the end user's asserted OTP or so you don't get charged for any unnecessary messages.

Before you begin

1. Make sure Telesign Verify is enabled for your account. Contact our Customer Support Team to enable this product.
2. Make sure you have set up a WhatsApp integration with your account.

Authentication templates

Authentication templates allow you to authenticate end users with one-time passcodes to securely access their accounts. You can authenticate end users potentially at multiple steps in the sign in process (e.g., account verification, account recovery, and integrity challenges). Authentication templates include a button to copy the one-time passcode (OTP), making it convenient for your end users to securely authenticate.

URLs, media, and emojis are not allowed for authentication template content or parameters.

A template needs to be approved by Telesign and WhatsApp before it can be used.

The Verify API currently supports only authentication templates, with an OTP as the only variable.

Components

These templates consist of two components:

Body

• Text: <VERIFICATION_CODE> is your verification code.
• An optional security disclaimer: For your security, do not share this code.
• An optional expiration warning: This code expires in <NUM_MINUTES> minutes.

CTA

• Includes either a copy code button, a one-tap autofill button, or there's no button at all when using zero-tap.
• Variables are not supported.
• You can custumize the text for the button. Text for the button is limited to a max length of 25 characters.

Create a template

There are three options available for creating a template. You can create custom templates in your account, using our Template API, or by contacting our Customer Support Team.

📘

NOTE:

When creating templates in your account, you can only create a template with fixed text and a copy code button. For additional adjustments described on this page, contact our Customer Support Team.

Create a template in the request

Use double curly brackets to include a variable name in a parameter value. Otp_text defines the text shown on a copy code button below a one-time passcode. Use Autofill when a one-tap autofill or zero-tap authentication template is used.

{
  "channel": "whatsapp",
  "content": [
    {
      "body": {
        "type": "text",
        "sample_text": [
          "34354"
        ],
        "text": "Your verification code is {{otp_code}}."
      },
      "suggested_action": [
        {
          "action_type": "otp",
          "otp": {
            "zero_tap_terms_accepted": true,
            "otp_text": "Autofill"
          }
        }
      ],
    }
  ],
  "name": "verification_template",
  "category": "authentication"
}

CTA examples

Example 1: Message with a one-time passcode and a copy code button

A copy code authentication template allows you to send a one-time passcode (OTP) along with a copy code button to your end users. When a WhatsApp user taps the copy code button, WhatsApp copies the passcode to the clipboard of the end user's device. The end user can then switch to your app and paste the passcode into the app.

When specifying the template in the request, you can only include the name of the template and the value for the OTP.

{
  "message_template": {
    "name": "verification_template"
  },
  "security_factor": "5724433"
}

You can also have Telesign generate the OTP for you if you don't include the security_factor in your request.

📘

NOTE:

Contact our Customer Support Team to enable this feature.

{
  "message_template": {
    "name": "telesign_otp_template"
  }
}

Example 2: Message with a one-time passcode and one-tap autofill button

A one-tap autofill authentication template allows you to send a one-time passcode (OTP) along with an Autofill button to your end users. When a WhatsApp user taps the Autofill button, the WhatsApp client triggers an activity which opens the end user's app and delivers the password or code to the app.

📘

NOTE:

One-tap autofill buttons are only supported on Android. If you send an one-tap autofill authentication template to a WhatsApp end user who is using a non-Android device, the WhatsApp client will display a copy code button instead. The WhatsApp client performs eligibility checks when it receives an authentication template message. If a check fails, the one-tap autofill button will be replaced with a copy code button.

Before using one-tap authentication template, you must set up your app so that the app signals the WhatsApp client to expect imminent delivery of a password or code. When an end user using your app requests a one-time password or verification code and chooses for it to be delivered to their WhatsApp number, first perform the handshake, then call our Verify API to send the authentication template message. (A handshake is an Android intent and public class that you implement but that the WhatsApp client can start.) When the WhatsApp client receives the message, it will perform an eligibility check. If there are no errors, WhatsApp will start the intent and display the message to the end user. When the end user taps the message's one-tap autofill button, WhatsApp automatically loads your app and passes password or code to it.

Requirements for a successful completion of an eligibility check

1. The handshake was initiated no more than 10 minutes ago.
2. The package name in the template matches the package name set on the intent.
3. The app signing key hash in the template matches the installed app's signing key hash.
4. The app has defined an activity to receive the password or code.

🚧

CAUTION:

You must adjust your app where the OTP should be auto-filled at the end in order to have one-tap autofill templates fully supported. Before using one-tap or zero-tap, you must set up your app so that the app signals the WhatsApp client to expect imminent delivery of a password or code. If your app does not perform a handshake before sending the message, or the message fails an eligibility check, the delivered message will display a copy code button instead of a one-tap button.

When specifying the template in the request, you can only include the name of the template and the value for the OTP.

{
  "message_template": {
    "name": "autofill_verification_template"
  },
  "security_factor": "5724433"
}

You can also have Telesign generate the OTP for you if you don't include the security_factor in your request.

📘

NOTE:

Contact our Customer Support Team to enable this feature.

{
  "message_template": {
    "name": "autofill_telesign_otp_template"
  }
}

Example 3: Message with a one-time passcode with zero-tap authentication

A zero-tap authentication template allows end users to receive one-time passwords or codes via WhatsApp without having to leave your app. When an end user using your app requests a password or code and we deliver it using a zero-tap authentication template, the WhatsApp client simply broadcasts the included password or code so your app can capture it immediately with a broadcast receiver. From end user's perspective, they request a password or code in your app and it appears in the app automatically.

📘

NOTE:

Zero-tap authentication templates are only supported on Android. If you send an one-tap autofill authentication template to a WhatsApp end user who is using a non-Android device, the WhatsApp client will display a copy code button instead. The WhatsApp client performs eligibility checks when it receives an authentication template message. If a check fails, the one-tap autofill button will be replaced with a copy code button.

Like one-tap autofill button authentication templates, when the WhatsApp client receives the template message containing the user's password or code, WhatsApp perform a series of eligibility checks. If the message fails these checks and it is not able to broadcast the password or code, the message will display either a one-tap autofill button or a copy code button.

Requirements for a successful completion of an eligibility check

1. The handshake was initiated no more than 10 minutes ago.
2. The package name in the template matches the package name set on the intent.
3. The app signing key hash in the template matches the installed app's signing key hash.
4. The app has defined an activity to receive the password or code.

🚧

CAUTION:

You must adjust your app where the OTP should be auto-filled at the end in order to have zero-tap authentication templates fully supported. Before using one-tap or zero-tap, you must set up your app so that the app signals the WhatsApp client to expect imminent delivery of a password or code. If your app does not perform a handshake before sending the message, or the message fails an eligibility check, the delivered message will display a copy code button instead of a zero-tap authentication notification.

When specifying the template in the request, you can only include the name of the template and the value for the OTP.

{
  "message_template": {
    "name": "zero_tap_verification_template"
  },
  "security_factor": "5724433"
}

You can also have Telesign generate the OTP for you if you don't include the security_factor in your request.

📘

NOTE:

Contact our Customer Support Team to enable this feature.

{
  "message_template": {
    "name": "zero_tap_telesign_otp_template"
  }
}

Send OTP via WhatsApp

Keep the reference pages Create a verification process and Update a verification process open in another window while you work on these steps.

📘

NOTE:

Updating a verification process using the procedure explained in Complete verification and get delivery status is a mandatory step when using Verify API. This step allows Telesign to know the real state of your verification as well as control all the features related to a verification process such as fallback, callback, and pricing. If your end user has verified themselves but the verification process is not updated, these features might not work as intended which can lead to extra costs or incorrect billing.

Send the request

1. Send a Create a verification process request to the Verify API. Include the following param values:

   Parameter	Value	Description	Required?
   recipient.phone_number	Digits without spaces or special characters, beginning with the country dialing code.	The recipient's phone number	yes
   verification_policy[0].method	whatsapp	One of the verification methods included in a verification policy.	Required only if WhatsApp is not already defined as the primary verification method for this account's default verification policy.
   verification_policy[0].fallback_time	A time in seconds.	The time window in seconds that the service waits before abandoning the current verification method and then initiating verification using the next method.	No. In case you don’t specify the fallback time, default fallback time is used.
   verification_policy[1].method	sms	One of the verification methods included in a verification policy. This is your backup method.	No, but recommended in case your recipient cannot be reached by WhatsApp.
   security_factor	A numeric code, formatted as a string.	The OTP to include in the message to the end user.	No. Can be used if you wish to define your own OTP instead of allowing Telesign to generate an OTP.
   message_template.name	A string consisting only of lowercase alpha characters and underscores.	A name of the template that is used for this request.	No. If you do not declare a template, Verify API will use a default template.

   Request

   HTTP

   POST /verification HTTP/1.1
   Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
   Content-Type: application/json; charset=utf-8
   Host: verify.telesign.com
   {
     "recipient": {
       "phone_number": "11234567890"
     },
     "verification_policy": [
       {
         "method": "whatsapp",
         "fallback_time": 30
       },
       {
         "method": "sms",
         "fallback_time": 30
       }
     ],
     "message_template": {
       "name": "verification_template"
     }
   }
   

   🚧

   CAUTION:

   The template name is specified only once in the POST request. This means that if you use fallback methods, the same template name is applied to all methods. Therefore, you need to ensure that each active channel has a template with that name. While the content can differ, the name must remain the same.

2. The service then sends a WhatsApp message to your end user, inserting a randomly generated OTP in the message.

3. Save the value of the property reference_id from the response. You will need it to complete the verification flow.

4. The status.code and status.description properties in the response indicate the preliminary delivery status of the message.

   Response

   HTTP

   HTTP/1.1 200 OK
   Content-Type: application/json
   {
     "reference_id": "0123456789ABCDEF0123456789ABCDEF",
     "recipient": {
       "phone_number": "11234567890"
     },
     "state": "ONGOING",
     "verification_policy": [
       {
         "method": "whatsapp",
         "fallback_time": 30
       },
       {
         "method": "sms",
         "fallback_time": 30
       }
     ],
     "status": {
       "code": 3901,
       "description": "Request in progress"
     }
   }
   

   📘

   NOTE:

   The status.code property gives you status of delivery to the destination carrier, not necessarily all the way to the end user.

Complete verification and get delivery status

Once your end user has submitted a potential code through your application, complete the verification flow with a second API call.

1. Send an Update a verification process request to the Verify API. This is to provide Telesign with the asserted OTP from the end user.

   Parameter	Value	Description	Required?
   action	finalize	Specifies how you want to change the verification state for this verification process.	yes
   security_factor	A string consisting of a series of numeric digits.	The end user's asserted one-time passcode (OTP).	yes

   Request

   HTTP

   PATCH /verification/0123456789ABCDEF0123456789ABCDEF/state HTTP/1.1
   Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
   Content-Type: application/json; charset=utf-8
   Host: verify.telesign.com
   {
     "action": "finalize",
     "security_factor": "5724433"
   }
   

   Response

   HTTP

   HTTP/1.1 200 OK
   Content-Type: application/json
   {
     "status": {
       "code": 3900,
       "description": "Verified"
     }
   }
   

2. If Telesign generated the OTP, and the value of the status.description property is Verified, the verification process completed successfully.