Como habilitar o envio de notificações pelo WhatsApp

• Introdução
• Verificação do usuário

1. Requisição
2. Resposta

• Disparo da notificação

1. Requisição
2. Resposta

• Redirecionando o usuário no fluxo

1. Requisição
2. Resposta

• Arquitetura de roteador

1. Requisição
   1. RespostaObs. 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, pois mesmo em casos de números já validados o WhatsApp não garante um cache de mais de 7 dias e, portanto, seu envio pode receber um erro de contato inexistente na base do container do WhatsApp. Este definição de cache e usuários válidos está descrita na Documentação Oficial do WhatsApp.

Requisição

A plataforma se encarregará de chamar o WhatsApp e realizar a validação, retornando os dados daquele contato no WhatsApp. A chamada para validar usuário pela API da Take Blip é a seguinte.

YOUR_TOKEN é a chave de autorização do seu bot.
PHONE_NUMBER é o número do usuário a ser validado. Não se esqueça de adicionar o + (mais) antes de enviar. Exemplo: [phone].

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

{
"id": "{{$guid}}",
"to": "[e-mail]",
"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": "[e-mail]",
"identity": "[e-mail]",
"phoneNumber": "[phone]",
"source": "WhatsApp"
},
"method": "get",
"status": "success",
"id": "{{$guid}}",
"from": "[e-mail]",
"to": "[e-mail]",
"metadata": {
"#command.uri": "lime://wa.gw.msging.net/accounts/[phone]"
}
}

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;
• NAMESPACE - O namespace em que se encontra o seu message template. Pode ser encontrado no próprio template do Bot na aba de conteúdos;
• 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":{
"namespace":"{{NAMESPACE}}",
"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 Take 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": "[e-mail]",
"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": "[e-mail]/#az-iris3",
"to": "[e-mail]",
"metadata": {
"#command.uri": "lime://[e-mail]/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": "[e-mail]",
"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": "[e-mail]/#az-iris3",
"to": "[e-mail]",
"metadata": {
"#command.uri": "lime://[e-mail]/contexts/{USER_IDENTITY}/master-state"
}
}