How to use WhatsAuth in your platform

This guide will get your from zero to production ready with a few step

Overview

WhatsAuth provides a simple and reliable way to validate mobile phones numbers and authorize several kinds of transactions such as OTP, 2-Factor Authentication, Delivery proof, etc.

We create a unique disposable code for each transaction that you require to validate by a mobile phone number using WhatsApp Application. 

The code is validated or disposed once its purpose is fulfilled or expired while keeping you or your platform informed of any changes in its status allowing you to react as your convenience.

Get Started

In order to implement WhatsAuth services in your platform you require:

  • Be able to request verification codes from our services on demand according to your business needs.
  • Be able to display the verification code to your users using the proper format (e.g. link, button, QR label, QR screen).
  • Be able to receive verification code status updates on a webhook in your platform with user verified information.

Usage Flow

Standard usage flow

The following steps represent an typical usage of the service to login with whatsApp

  1. Your app requests a verification code with a GET request and parses the response to obtain the code.
  2. Your application displays a “whatsapp button” with the unique link obtained in step 1.
  3. The user taps on the button opening whatsApp with a preset message to be sent.
  4. The code mesage is processed.
  5. The user receives a response message with the result of its verification.
  6. Your platform receives a webhook with the details of the verification including phone number and profile name.
  7. Your app continues the regular login process with the obtained profile information.
Login flow in action

‍

Code Generation

To get a verification code from WhatAuth API you need to make an HTTPS request providing the API key for authorization and some parameters for customization.

‍

cURL Sample

The following cURL command you can try from your terminal


curl --location --request GET 'http://whatsauth.me/api/v1/verification_code?callback_url=https://app.mycompany.com/whatsauth \
&expires_at=10&link_message=https://app.mycompany.com/welcome \
&expiration_message=Sorry, this code expires within 10 min. Please start the process again. \
&failure_message=Oops! something went wrong please try again in a few minutes. \
&response_message=Your now validated. Welcome to MyApp! Please click the link to continue \
&authorized_numbers=%2B123456789,%2B987654321' \
--header 'Authorization: Bearer DEMOPDruierhwkfuwgkedjgh'

Parameters

Parameter (*) Type Description
callback_url string The webhook url that will receive verification status. Must implement with HTTPS POST method.
expires_at integer The number of minutes the verification code expires in. Minimum value is 1 minute.
authorized_numbers array (comma separated strings) The list of phone numbers that are allowed to validate generated code. By default any phone number is authorized.
link_message string Message appears on the client's screen as a part of the code message above generated code.
expiration_message string Message is sent to the client on intent to validate the expired code.
failure_message string Message is sent to the client when there is a failure in sending verification status via provided webhook.
response_message string Message is sent to the client as a notification of a successful validation.
qr 0 or 1 Set this parameter to 1 in case you want to receive QR code url in a response.

You can also specify default values for each parameter at the application level and skip those in the request. If you set a parameter in your request it will override the one set as default.

Verification success message
Expiration message
Failure message

Response

If the request is properly formed and authenticated you'll receive a response with a JSON like this:


{
   "code": "9f76681bd4",
   "link": "https://wa.me/56943426553?text=Verify%20my%20phone%20number%20with%20the%20following%20code:%0A%0A%60%60%60--------------%0A%7C%209f76681bd4%20%7C%0A--------------%60%60%60",
   "qr": "https://api.qrserver.com/v1/create-qr-code?data=https%3A%2F%2Fwa.me%2F56943426553%3Ftext%3DVerify%2520my%2520phone%2520number%2520with%2520the%2520following%2520code%3A%250A%250A%2560%2560%2560--------------%250A%257C%25209f76681bd4%2520%257C%250A--------------%2560%2560%2560&size=200x200"
}

‍

Parameter name Type Description
code* String Generated unique verification code.
link* String Link that takes you to whatsapp web or mobile application with predefined message.
qr String URL of the generated QR code image for whatsapp link. When requested.

‍

‍

‍

Webhook

In order to receive updated status of the verification process you will need to implement the webhook that is a URL under HTTPS protocol and POST method. There you will receive the following information in JSON format:


{
   "id": "123e4567-e89b-12d3-a456-426614174000",
   "status": "validated",
   "verification_code": "9f76681bd4",
   "phone_number": "+56911111111",
   "profile_name": "Some Folk",
   "expires_at": "2021-01-27T01:17:13.674Z",
   "requested_at": "2021-01-26T23:17:13.674Z",
   "validated_at": "2021-01-26T23:23:17.28Z",
   "authorized_numbers": [],
   "error": null
}

From here you can obtain the data required to follow up your business process.

Attribute name Type Description
id UUID Verification id.
status String Status of verification code. Possible values: “requested”, “validated”, “expired”, “failed”.
verification_code String Unique verification code associated with the process.
phone_number String Mobile phone number which validated the code.
profile_name String Whatsapp profile name of the person validated the code.
requested_at ISO 8601 String Time when verification code was requested.
validated_at ISO 8601 String Time when verification code was validated by the client.
expires_at ISO 8601 String Time when verification code expires.
authorized_numbers String Array Phone numbers authorized to validate the code.
error String Error message in case of validation failure.

The webhook request expects to have a response 200 or 204 status.

‍

FAQ

Do I need to have my own Whatsapp business number?

No, we provide you with a global WhatsAuth number to validate mobiles phones, package delivery or transaction authorization

Can I use my own Whatsapp business number?

Sure!, we can use any Whatsapp or Twilio business number.

‍