Como gerenciar uma lista de distribuição para enviar notificações WhatsApp – Blip | Blip Help

Índice:

Levantamento de todos os seus contatos

Antes de mais nada, como seus usuários podem estar vindo de diferentes plataformas e momentos, iremos modularizar este conteúdo para fácil compreensão. Sobretudo, vale ressaltar que todo o conteúdo de levantamento de contatos no WhatsApp está relacionado ao número de contato dos usuários.

Levantamento de todos os seus contatos que já interagiram com seu bot

Suponha que você possui um Blip Chatbot e alguns usuários que já interagiram com seu bot não estão na sua lista de distribuição. Para identificar estes usuários, o endpoint de Get contacts deverá ser utilizado. Se tratando do canal WhatsApp, o filtro utilizado na consulta abaixo, retorna todos os usuários que comunicaram com o seu bot utilizando o canal WhatsApp.

POST https://{{contractid}}.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))"
}

Para cada contato retornado na consulta, haverá uma chave identity, que representa o identificador do usuário no WhatsApp.

"items": [
            {
                "name": "John Doe 1",
                "identity": "553199999999@wa.gw.msging.net",
                "extras": {},
                "source": "WhatsApp"
            },
            {
                "name": "John Doe 2",
                "identity": "553188888888@wa.gw.msging.net",
                "phoneNumber": "+553188888888",
                "extras": {},
                "source": "WhatsApp"
            }
        
]

Levantamento de todos os seus contatos em uma plataforma externa

Em posse dos números dos contatos, é preciso ter acesso ao identificador do usuário no WhatsApp. Lembre-se de realizar essa operação uma única vez para cada cliente.

A busca pelo identificador é feita por uma requisição HTTP, considerando o número do celular do cliente no formato internacional “+ DDI DDD PHONE_NUMBER”. PONTO DE ATENÇÃO:

Não se esqueça de adicionar o sinal de "+" (mais) antes de enviar. Mais detalhes sobre verificação do usuário, check contact e a validade do número consultado, acesse aqui.

Veja um exemplo de um número considerando o identificador do país igual a 55 (Brasil) e o DDD igual a 31 (Minas Gerais).

+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/+5531999998888"

Repare que um dos cabeçalhos dessa requisição exige um token (YOUR_TOKEN) de autorização do bot. Para saber onde encontrar o token de seu bot:

Veja abaixo um exemplo de resposta para essa requisição. Repare que a propriedade resource possui um objeto JSON que contém a propriedade alternativeAccount, esse é o valor que identifica o cliente no canal WhatsApp.

5531999998888@wa.gw.msging.net - identificador do cliente que possui o número de celular 5531999998888

{
    "type": "application/vnd.lime.account+json",
    "resource": {
        "fullName": "John Doe",
        "alternativeAccount": "5531999998888@wa.gw.msging.net",
        "identity": "5531999998888@wa.gw.msging.net",
        "phoneNumber": "+5531999998888",
        "source": "WhatsApp"
    },
    "method": "get",
    "status": "success",
    "id": "a456-42665544000-0123e4567-e89b-12d3",
    "from": "postmaster@wa.gw.msging.net",
    "to": "bot@msging.net",
    "metadata": {
        "#command.uri": "lime://wa.gw.msging.net/accounts/+5531999998888"
    }
}

Observação: Essa operação deve ser executada uma única vez para cada cliente.

Criar uma lista de distribuição

Atualmente existem duas formas de criar uma lista de distribuição, diretamente no builder ou utilizando a API. Abaixo são apresentados cada uma dessas formas com suas respectivas especificidades.

Criando lista de distribuição via Builder

Para executar a ação de criar lista de distribuição no Builder, clique sobre um bloco qualquer e selecione a aba Ações. Na funcionalidade de adicionar ação de entrada selecione a opção lista de distribuição. Com a finalização de todos os processos anteriores, digite o nome desejado no campo de nome de lista e o botão de adicionar nova lista deve ser clicado para conclusão do processo. A imagem abaixo indica de forma compilada os passos aqui apresentados.

Criando lista de distribuição via API

Para executar a ação de criar lista de distribuição via API, utilizaremos o endpoint a documentação substitua o {your_distributionList} pelo nome desejado para sua lista.

POST https://{{contractid}}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}

{  
  "id": "1",
  "to": "postmaster@broadcast.msging.net",
  "method": "set",
  "type": "application/vnd.iris.distribution-list+json",
  "uri": "/lists",
  "resource": {  
    "identity": "{your_distributionList}@broadcast.msging.net"
  }
}

Inserir todos os números na lista de distribuição no formato correto

Finalizando todas as etapas anteriores, utilizaremos a API para inserir todos os contatos levantados na lista criada. Para isso utilizaremos o endpoint add a member to list, para cada usuário a ser inserido devemos executar a requisição abaixo, lembre-se de substituir o {your_distributionList} pelo nome da sua lista criada que pode ser obtida nos passos anteriores ou no endpoint get all lists.

POST https://{{contractid}}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}

{  
  "id": "3",
  "to": "postmaster@broadcast.msging.net",
  "method": "set",
  "uri": "/lists/{your_distributionList}@broadcast.msging.net/recipients",
  "type": "application/vnd.lime.identity",
  "resource": "5531999998888@wa.gw.msging.net"
}

Utilizando o Plugin para criar e gerenciar as listas de distribuição

O plugin Blip é uma maneira independente para conectar recursos não oficiais para aprimorar as funcionalidades do portal.

Quais são as funcionalidades desse plugin/tool?

Visualizar todas as listas de distribuição do seu bot
Adicionar uma nova lista de distribuição
Deletar listas de distribuição
Visualizar todos os membros de uma lista de distribuição
Remover membros de uma lista de distribuição
Visualizar todos os contatos do bot
Adicionar um contato como membro de uma lista de distribuição
Adicionar um contato como membro de uma lista de distribuição a partir de um arquivo [New]
Filtrar contatos do bot
Visualizar todas as informações de um contato

Como usar?

Pré-requisito:

Ative a extensão Broadcast List através da loja de plugins

Instruções

Para criar listas de distribuição:

Acesse a tab “Manage Lists”
Clique no campo de entrada “New list” e digite o nome desejado para lista
Clique no botão “Add”

Para remover listas de distribuição:

Acesse a tab “Manage Lists”
Selecione uma ou mais listas na tabela “List”
Clique no botão “Remove”

Para visualizar todos os membros de uma lista de distribuição:

Acesse a tab “Manage Members”
Selecione uma lista de distribuição na seleção “List”

Para remover membros de uma lista de distribuição:

Acesse a tab “Manage Members”
Selecione uma lista de distribuição na seleção “List”
Selecione um ou mais membros na tabela “Members”
Clique no botão “Remove”

Para adicionar um contato como membro de uma lista de distribuição:

1. Acesse a tab “Manage Contacts”
2. Selecione uma lista de distribuição na seleção “List”
3. Selecione um ou mais contatos na tabela “Contacts”
4. Clique no botão “Add”