Como habilitar o envio de notificações pelo WhatsApp

Índice :

1. Introdução
2. Verificação do usuário
3. Disparo da notificação
4. Redirecionando o usuário no fluxo
5. Arquitetura de roteador  

 

 Observação: O envio de notificações ocorre por meio de requisições http, por isso entenda os tópicos "requisição" como estas, tais como as notificações enviadas pelo WatsApp.

 

Introdução

O envio de notificação no WhatsApp depende de alguns passos para que seja feito com sucesso. Considerando que você já possua seu template de mensagem cadastrado, os passos necessários são descritos abaixo. 

Obs.: A variável ORGANIZATION_ID é o identificador da organização em que seu bot se encontra. Caso não esteja em organização, não precisa utilizar este prefixo nas requisições, incluindo o ponto, ou seja, comece com http://http.msging.net/.

 

Verificação do usuário

Antes de realizar o envio é necessário validar o número do usuário em questão. Este processo deve ser realizado para todo envio. 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.

Requisição

A busca pelo identificador é feita através de uma requisição HTTP levando em consideração 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

YOUR_TOKEN é a chave de autorização do seu bot.

PHONE_NUMBER é o número do usuário a ser validado. Exemplo: +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}"
}

Resposta

Na resposta desta chamada haverão algumas informações do contato. Aqui a mais importante delas é o alternativeAccount, o qual deve ser utilizado para o disparo da notificação, portanto, após a validação, salve o valor retornado neste campo. Os outros campos são informações extras e que nem sempre estarão disponíveis, a depender do contato.

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"
}
}

 

Disparo da notificação

Após verificar o usuário, você já pode utilizar o alternativeAccount para efetuar o disparo de notificação para este contato.

Requisição

Para efetuar o disparo você precisará preencher um payload nos padrões do WhatsApp, o qual deverá conter as informações referentes ao seu template.

• TO - O alternativeAccount recuperado anteriormente;
• MESSAGE_TEMPLATE_NAME - O nome do message template a ser utilizado. Também pode ser encontrado na aba de conteúdos.

Os campos language e components devem ser utilizados de acordo com seu template.

Language pode ser utilizada quando seu template precisa ser enviado para mais de um idioma. Mais detalhes sobre seu uso podem ser encontrados aqui na documentação oficial.

Components estão relacionados aos valores que compõe a mensagem do template, além dos textos pré-definidos na aprovação. Podem ser do tipo body, header, button, document, video ou imagem. Nesta documentação você encontra diversos exemplos de utilização dos tipos de template.

Abaixo, um payload padrão de template de mensagens. Repare que neste exemplo é utilizado um componente do tipo body, o qual se refere a duas variáveis que devem ser substituídas no 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"
}
]
}
]
}
}
}

Resposta

O processamento da notificação é feito de forma assíncrona e em backgroud. Portanto, a não ser que haja alguma formatação indevida no payload da requisição, a plataforma responderá com um Accepted (202) e iniciará a integração com o WhatsApp, a qual ainda está sujeita a falhas.

 

Redirecionando o usuário no fluxo

Em alguns casos é necessário redirecionar o usuário dentro do fluxo após ou antes do disparo. Para isto, basta realizar o controle da variável de estado do usuário no fluxo.

A variável de estado do usuário nada mais é do que o identificador do bloco em que ele se encontra dentro do fluxo. Mais detalhes deste estado podem ser vistos nesta documentação da Blip.

Requisição

• FLOW_ID - Este é o parâmetro de identificação do fluxo do bot. É único por bot e pode ser recuperado dentro das configurações do builder;
• STATE - Este parâmetro é o identificador do bloco que se deseja enviar o usuário. Repare que o nome da variável de contexto que se está alterando é stateid@{FLOW_ID}, a qual deve ser encodada para o formato de url, resultando em stateid%40{FLOW_ID};
• USER_IDENTITY - Este deve ser o identificador do usuário que se deseja alterar o estado.

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}"
}

Resposta

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}"
}
}

 

Arquitetura de roteador

Caso esteja utilizando a arquitetura de bot roteador e necessário setar mais uma variável de contexto. A variável master-state. Seguindo o mesmo padrão da requisição de mudar o estado do usuário. Neste caso, muda-se o nome da variável e seu valor deve ser o identificador do bot (serviço) em que se deseja enviar o usuário.

É importante destacar que esta ação deve ser realizada antes de mudar o estado do usuário dentro do fluxo.

Requisição

• USER_IDENTITY - Este deve ser o identificador do usuário que se deseja alterar o estado;
• MASTERSTATE - O identificador do bot no formato {IDENTIFICADOR}@msging.net. O IDENTIFICADOR pode ser encontrado na página home ou na url do seu 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}"
}

Resposta

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"
}
}

 

 

Para mais informações, acesse a discussão sobre o assunto em nossa comunidade ou os vídeos em nosso canal. 😃