Skip to main content

Enabling sending notifications by WhatsApp

  • Updated

Index

  1. Introduction
  2. User verification
  3. Notification Trigger
  4. Redirecting the user in the flow
  5. Router architecture

 

Request

Notes: Notifications are sent via http requests, so please understand "request" topics like these, such as notifications sent by WatsApp.

 

Introduction

Sending a notification on WhatsApp depends on a few steps for it to be done successfully. Assuming you already have your message template registered, the necessary steps are described below. 

 

Note: The ORGANIZATION_ID variable is the identifier of the organization your bot is located. If you are not in an organization, you do not need to use this prefix in requests, including the dot, that is, start with http://http.msging.net/.

 

User verification

Before sending, it is necessary to validate the concerned user number. This process must be carried out for every sending. In possession of the contacts' numbers, it's necessary to access the user's identifier on WhatsApp. Remember to perform this operation only once for each client.

Request

The identifier search is done through an HTTP request, considering the client's mobile phone number in international format "+DDI DDD PHONE_NUMBER". ATTENTION: Do not forget to add the "+" sign before sending. For more details on user verification, contact check, and the validity of the consulted number, check here.
Here's an example of a number considering the country identifier as 55 (Brazil) and the area code as 31 (Minas Gerais).
+5531999998888
YOUR_TOKEN is your bot's authorization key.
PHONE_NUMBER is the user's number to be validated. Example: +5531999998888.

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}

{

"id": "{{$guid}}",

"to": "postmaster@wa.gw.msging.net",

"method": "get",

"uri": "lime://wa.gw.msging.net/accounts/{PHONE_NUMBER}"

}

Response

In the response of this call there will be some contact information. Here, the most important one is the alternativeAccount, which must be used to trigger the notification, so, after validation, save the value returned in this field. The other fields are extra information and will not always be available, depending on the contact.

 

HTTP/1.1 200 OK

Content-Type: application/json

{

"type": "application/vnd.lime.account+json",

"resource": {

"fullName": "John Doe",

"alternativeAccount": "5531988889999@wa.gw.msging.net",

"identity": "5531988889999@wa.gw.msging.net",

"phoneNumber": "+5531988889999",

"source": "WhatsApp"

},

"method": "get",

"status": "success",

"id": "{{$guid}}",

"from": "postmaster@wa.gw.msging.net",

"to": "bot@msging.net",

"metadata": {

"#command.uri": "lime://wa.gw.msging.net/accounts/+5531988889999"

}

}

 

 

Notification Trigger

After verifying the user, you can use the alternative Account to trigger the notification for this contact.

Request

In order to trigger it, you will need to fill in a payload in the WhatsApp standards, which must contain the information regarding your template.

 

  • TO - The previously recovered alternativeAccount;
  • MESSAGE_TEMPLATE_NAME - The name of the message template to use. It can also be found in the contents tab.

 

The language and components fields must be used according to your template.

Language may be used when your template needs to be sent to more than one language. More details on its use may be found here in the official documentation.

Components are related to the values that make up the template's message, in addition to the pre-defined texts in the approval. They may be body, header, button, document, video or image type. In this documentation you will find several examples of using template types.

Shown below is a standard message template payload. Note that in this example a component of type body is used, which refers to two variables that must be replaced in the template.

 

POST https://{ORGANIZATION_ID}.http.msging.net/messages HTTP/1.1

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}

{

"id":"{{$guid}}",

"to":"{TO}",

"type":"application/json",

"content":{

"type":"template",

"template":{

"name":"{{MESSAGE_TEMPLATE_NAME}}",

"language":{

"code":"pt_BR",

"policy":"deterministic"

},

"components":[

{

"type": "body",

"parameters": [

{

"type": "text",

"text": "value1"

},

{

"type":"text",

"text":"value2"

}

]

}

]

}

}

}

Response

Notification processing is done asynchronously and in the background. Therefore, unless there is some improper formatting in the payload of the request, the platform will respond with an Accepted (202) and will start the integration with WhatsApp, which is still subject to failures.

 

Redirecting the user in the flow

In some cases, it is necessary to redirect the user within the flow after or before the trigger. To do this, just control the user's state variable in the flow.

 

The user's state variable is just the identifier of the block that is within the flow. More details of this state can be seen in this Blip documentation.

 

Request

  • FLOW_ID - This is the bot flow identification parameter. It is unique per bot and can be recovered within the builder settings;
  • STATE - This parameter is the identifier of the block that the user wants to send. Note that the name of the changing context variable is stateid@{FLOW_ID}, which must be encoded in url format, resulting in stateid%40{FLOW_ID}; 
  • USER_IDENTITY - This must be the identifier of the user that you want to change the state.
POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}




{

"id": "{{$guid}}",

"to": "postmaster@msging.net",

"method": "set",

"uri": "/contexts/{USER_IDENTITY}/stateid%40{FLOW_ID}",

"type": "text/plain",

"resource": "{STATE}"

}

Response

HTTP/1.1 200 OK

Content-Type: application/json

{

"method": "set",

"status": "success",

"id": "1294447a-2581-4597-be6a-a5dff33af156",

"from": "postmaster@msging.net/#az-iris3",

"to": "docstest@msging.net",

"metadata": {

"#command.uri": "lime://docstest@msging.net/contexts/{USER_IDENTITY}/stateid%40{STATE_ID}"

}

}

Router architecture

If you are using the bot router architecture, it is necessary to set one more context variable. The master-state variable. Following the same pattern as the request to change the user state. In this case, you change the name of the variable and its value must be the identifier of the bot (service) where you want to send the user.

 

It is important to note that this action must be carried out before changing the user's state within the flow.

Request

  • USER_IDENTITY - This must be the identifier of the user who wants to change the state;
  • MASTERSTATE - The bot identifier in the format {IDENTIFIER}@msging.net. The IDENTIFIER can be found on the home page or in the url of your bot.
POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}

{

"id": "{{$guid}}",

"to": "postmaster@msging.net",

"method": "set",

"uri": "/contexts/{USER_IDENTITY}/master-state",

"type": "text/plain",

"resource": "{MASTERSTATE}"

}

Response

HTTP/1.1 200 OK

Content-Type: application/json

{

"method": "set",

"status": "success",

"id": "1294447a-e581-4g97-re6a-a5dff33af156",

"from": "postmaster@msging.net/#az-iris3",

"to": "docstest@msging.net",

"metadata": {

"#command.uri": "lime://docstest@msging.net/contexts/{USER_IDENTITY}/master-state"

}

}

 

For more information, visit the discussion on the subject in our community or the videos on our channel. 😃

Related articles