How to manage a distribution list to send WhatsApp notifications

1. Survey of all your contacts

First of all, as your users may be coming from different platforms and times, we will modularize this content for easy understanding. Above all, it is worth mentioning that all the content of surveying contacts on WhatsApp is related to the contact number of users.

1.1 Survey of all your contacts who have already interacted with your bot

Suppose you have a BLiP Chatbot and some users who have already interacted with your bot are not on your distribution list. To identify these users, the Get contacts with paging endpoint must be used. When it comes to the Whatsapp channel, the filter used in the query below, returns all users who communicated with your bot using the whatsapp channel.

POST https://http.msging.net/commands HTTP/1.1

Content-Type: application/json

Authorization: Key YOUR_TOKEN

{  

  "id": "a456-42665544000-0123e4567-e89b-12d3",

  "method": "get",

  "uri": "/contacts?$filter=(substringof('WhatsApp'%2Csource))"

For each contact returned in the consultation, there will be an identity key, which represents the user's identifier on WhatsApp.

"items": [

            {

                "name": "John Doe 1",

                "identity": "[e-mail]",

                "extras": {},

                "source": "WhatsApp"

            },

            {

                "name": "John Doe 2",

                "identity": "[e-mail]",

                "phoneNumber": "[phone]",

                "extras": {},

                "source": "WhatsApp"

            }

]

1.2 Survey of all your contacts on an external platform

In possession of the contact numbers, it is necessary to have access to the user's identifier in WhatsApp. Remember to perform this operation only once for each customer.

The search for the identifier is done through an HTTP request, considering the customer's cell phone number in international format. See an example of a number considering the country identifier equal to 55 (Brazil) and the DDD equal to 31 (Minas Gerais)

[phone]

POST https://http.msging.net/commands HTTP/1.1

Content-Type: application/json

Authorization: Key YOUR_TOKEN

{  

  "id": "a456-42665544000-0123e4567-e89b-12d3",

  "to": "[e-mail]",

  "method": "get",

  "uri": "lime://wa.gw.msging.net/accounts/[phone]"

}

Note that one of the headers in this request requires a bot authorization token (YOUR_TOKEN). To find out where to find your bot's token click here.

Below is an example of a response to this request. Note that the resource property has a JSON object that contains the alternativeAccount property, this is the value that identifies the customer on the WhatsApp channel.

[e-mail] - identifier of the customer who has the mobile number 5531999998888

{

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

    "resource": {

        "fullName": "John Doe",

        "alternativeAccount": "[e-mail]",

        "identity": "[e-mail]",

        "phoneNumber": "[phone]",

        "source": "WhatsApp"

    },

    "method": "get",

    "status": "success",

    "id": "a456-42665544000-0123e4567-e89b-12d3",

    "from": "[e-mail]",

    "to": "[e-mail]",

    "metadata": {

        "#command.uri": "lime://wa.gw.msging.net/accounts/[phone]"

    }

}

Note: This operation must be performed only once for each customer.

2. Create a distribution list

There are currently two ways to create a distribution list, directly in the builder or using the API. Below are presented each of these forms with their respective specificities.

2.1 Creating distribution list via Builder

To perform the action of creating distribution list in Builder, click on any block and select the Actions tab. In the functionality of adding input action select the distribution list option.

With the completion of all previous processes, enter the desired name in the list name field and the add new list button must be clicked to complete the process. The image below indicates in a compiled way the steps presented here.

2.2 Creating distribution list via API

To perform the action of creating distribution list via API, we will use the endpoint of the documentation (replace {your_distributionList} with the desired name for your list).

POST https://http.msging.net/commands HTTP/1.1

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}

{  

  "id": "1",

  "to": "[e-mail]",

  "method": "set",

  "type": "application/vnd.iris.distribution-list+json",

  "uri": "/lists",

  "resource": {  

    "identity": "{your_distributionList}@broadcast.msging.net"

  }

}

3. Insert all numbers in the distribution list in the correct format

Finishing all the previous steps, we will use the API to insert all the contacts raised in the created list. For this we will use the add a member to list endpoint, for each user to be inserted we must execute the request below, remember to replace {your_distributionList} with the name of your created list that can be obtained in the previous steps or in the get all endpoint lists.

POST https://http.msging.net/commands HTTP/1.1

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}

{  

  "id": "3",

  "to": "[e-mail]",

  "method": "set",

  "uri": "/lists/{your_distributionList}@broadcast.msging.net/recipients",

  "type": "application/vnd.lime.identity",

  "resource": "[e-mail]"

}