WhatsApp Guide

WhatsApp can be used as a channel to reach users using Digital Identity Flows you have created. Using a WhatsApp Business Account (WABA), you would be able to send and receive messages through the Whatsapp Business API for your business processes and interactions with your users, each input needed for the Verification Flow is requested and users are guided through each step until completion.

Additionally, you can also send single WhatsApp messages to your users which can be used for sending notifications, one time passwords and more.

For complete detail of the API endpoints and parameters, refer to the Digital Identity API documentation.

You can import this specific Whatsapp Postman collection:

https://www.getpostman.com/collections/881d016f5a57df602262

Whatsapp integration example

Preparing your Whatsapp Business Account

Our team will guide you through the WABA creation process. It will belong to your company but will be managed by us to ease the configuration process. For additional information on setting up your WhatsApp business channel follow this guide.

Start a Flow with Inbound messages.

An inbound message is any message that the user sends to the WABA. A user can start a Verification Flow by sending a specific inbound message you have configured for a WABA. This can be done by creating a link that you can set in your landing page, media campaigns or app buttons. Once the user opens the link, a WhatsApp chat with your WABA will open with the message you have configured, starting the verification process. Try it out here.

To set up your Flow with inbound messages, follow these steps:

  1. Create a Verification Flow with the steps you want the user to follow. If you already have a Flow created, copy the FlowID that identifies the Flow.

  2. Create the Inbound Flow

    • Create a POST request to https://api.identity.truora.com/v1/whatsapp/inbounds
    • Create a Header named Truora-API-Key and set its value to your API key.
    • Set the value for Content-Type header as application/x-www-form-urlencoded.
    • Create the following keys in the application/x-www-form-urlencoded request body and set their respective values as follows:
      • waba_phone_number: phone number of the WABA that will be interacting with the users. Must include the country code.
      • flow_id: identifier of the Verification Flow previously created.
      • inbound_message: unique message the users will be sending to the WABA in order to begin the Verification Flow.

  3. Create a short link that starts the WhatsApp conversation using an external url generator or the internal shortener. The content of the message must be the one you specified as inbound_message in the request of the previous step.

Reach your users with Outbound Messages for starting flows or sending notifications

Outbound Messages are messages sent directly to the users without any previous interaction with your business WABA. For this to be possible, two things are required.

  1. An explicit permission needs to be granted by the user to your business, allowing you to contact them through Whatsapp for business purposes. This is called an opt-in. For more guidance on how to obtain it, visit this link.
  2. The Outbound Message you use to start the interaction with the users needs to be approved by WhatsApp, making sure you comply with the minimum requirements and guidelines to prevent user spam, fraud and other policies.

For creating and sending for approval an Outbound Message, do the following steps.

  1. Create a POST request to https://api.identity.truora.com/v1/whatsapp/outbounds
  2. Create a Header named Truora-API-Key and set its value to your API key.
  3. Set the value for Content-Type header as application/x-www-form-urlencoded.
  4. Create the following keys in the request body and set their respective values as follows:
    • waba_phone_number: Phone number with country code of the WABA line that will send the message.
    • is_notification: Set to true if the Outbound Message is a single notification message or false if it will be used for starting a Verification Flow.
    • content: The message to be sent to the user. Example: Hello, ¿are you ready to start the process?. If the message will include variables, they should be specified between double brackets like {{.<variable_name>}}. Example: Hello {{.name}}, ¿are you ready to start the process?
    • category: Topic category of the Outbound Message, must be one of TRANSACTIONAL, MARKETING, OTP. OTP is for One Time Passwords,MARKETING is for marketing campaigns and TRANSACTIONAL is for any other topic of the Outbound.
    • template_type: Type of content for the Outbound Message. Must be one of TEXT, VIDEO, IMAGE, DOCUMENT, LOCATION.
    • language_code: Code of the language the message is in. Examples: es, es_MX, en.
    • outbound_name: Contains a TEXT specifying the name of the outbound for its future reference.
    • media_url: Required if the template_type is not TEXT. Specifies the URL for the media content.
    • continue_process_message: Required if is_notification is set to false. Contains a TEXT specifying a continue message that will appear as a button to the user. Example: Continue.
    • cancel_process_message: Required if is_notification is set to false. Contains a TEXT specifying a cancel message that will appear as a button to the user. Example: Cancel
    • If the Outbound Message has variables like hello {{.name}} {{.lastname}}, it is Required to send a key with an example of them, one for each variable the message has. The key should be var.<variable_name> and the value should be the example text. Example: for the first variable var.name: Jhon and for the second variable var.lastname: Doe.

Send the request and copy the outbound_id string from the response. The Outbound Message has now been sent to WhatsApp and needs to be approved before it can be used. You can check the status of the process with the Get Outbound Message request:

  1. Create a GET request to https://api.identity.truora.com/v1/whatsapp/outbounds/{outbound_id}
  2. Replace {outbound_id} in the URL with the outbound_id obtained from the previous request.
  3. Create a Header named Truora-API-Key and set its value to your API key.
  4. Send the request. Once the status of the message is APPROVED, it is ready to be sent to WhatsApp users. If the status is PENDING, the message is still in the review process by WhatsApp, wait some time and try again. If the status is REJECTED, the message doesn't comply with WhatsApp requirements and guidelines, so you need to change the message content, create a new Outbound Message and try again.

Once you have the user opt-in and the Outbound Message approved for outbounds, send a request to our API to send the message to the users.

  1. Create a POST request to https://api.identity.truora.com/v1/whatsapp/outbounds/send
  2. Create a Header named Truora-API-Key and set its value to your API key.
  3. Set the value for Content-Type header as application/x-www-form-urlencoded.

  4. Create the following keys in the request body and set their respective values as follows:

    • phone_number: Phone number without the country code of the user that will receive the message.
    • country_code: Country code of the phone number. Here you can find a complete list of country codes.
    • outbound_id: ID of the Outbound Message created in previous steps. The Outbound Message status needs to be APPROVED.
    • user_authorized: Indicates whether the person who owns the phone number provided has authorized the process by giving the opt-in directly to you. Must be true in order to continue.
    • flow_id: Required if the Outbound Message was created with the is_notification field in false. Contains the identifier of the Verification Flow that will start when the user accepts the message.
    • If the Outbound Message has variables like hello {{.name}} {{.lastname}}, it is Required to send a key-value, one for each variable the message has. The key should be var.<variable_name> and the value should be the desired value of the variable. Example: for the first variable var.name: Roger and for the second variable var.lastname: Federer.

  5. Send the request. If all previous steps were followed properly, the user should now receive the Outbound Message you configured, which will notify them with the message content and, if needed, start a Verification Flow.

Configuring a Reengagement Message

Users can always drop-off in the middle of a conversation. Configuring the identity flow to send a re engagement message after a period of inactivity from your users will increase the probability of the user to finish the conversation with the bot.

A re-engagement message is used to encourage the user to finish the process when they leave the WhatsApp conversation hanging without giving a response to a question. This message is sent after a waiting time of minimum 30 minutes and maximum 23 hours.

Whatsapp reengagement example

In the message we send two options: “yes” and “no”. The user will be able to decide if they want to continue with the process or not. In case they want to continue, they will start from the last question they left unanswered. If the user doesn’t answer the re-engagement message, the conversation will be finished when it expires.

Reengagement schedule

To avoid contacting users in the middle of the night, there is a time window for the re-engagement messages to be sent. If the message is scheduled out of this window we will postpone it until the next starting business time. The default business time starts at 8:00 and ends at 19:00.

Whatsapp reengagement schedule

To set up your flow with reengagement messages, make sure you include the following configuration in your identity flow (check out how to create an identity flow here).

  • ​​enable_follow_up: enables the reengagement feature. Must be true for the bot to send the reengagement message. If this field is not set, the reengagement feature will be disabled.
  • follow_up_delay: delay in minutes to send the reengagement message. For example: 45. If this field is not set, the reengagement waiting time will be 2 hours.
  • follow_up_message: reengagement message. For example: "You have an active process in progress, would you like to continue?". If this field is not set, the message will be: “Tienes un proceso activo en curso”.
  • start_business_hours: start of the range of business time in UTC. If this field is not set, the start business hour will be 2021-01-01T13:00:00.000Z.
  • end_business_hours: end of the range of business time in UTC. If this field is not set, the end business hour will be 2021-01-01T00:00:00.000Z.

Receive results of the users that went through the Flow

Results are reported using the same hooks configured for the Digital Identity product. For more information, check the Setting up Hooks guide. The information in the hook contains the results of the validations made to the user, such as liveness verification, and also the responses to custom questions you have set up in the Flow. Be aware that hooks will be sent for all the Identity Verification processes made through all platforms (web, SDK, WhatsApp). If you want to receive only for a specific platform, you might want to use different FlowIDs for each one, and manually filter them once they arrive.

If you want to receive hooks only for processes finished successfully, you need to create the hook and listen only to the succeeded event. Otherwise, you can listen to both, succeeded and failed, if you want to keep the information to use in some kind of user re-engagement process in the future.