Como enviar notificações WhatsApp via API do Blip 14 de fevereiro de 2024 18:42 Atualizado Índice: Introdução Enviando uma notificação Requisição 1: Buscando o identificador de um cliente Requisição 2: Envio da notificação com texto somente Requisição 3: Envio da notificação com imagem Requisição 4: Envio da notificação com vídeo Requisição 5: Envio da notificação com documento Requisição 6: Envio da notificação com quick reply Direcionamento para um subbot cadastrado como serviço de um router Introdução Através do BLiP, é possível criar aplicações para o canal WhatsApp capazes não só de responder às mensagens recebidas, mas também de enviar mensagens (notificações) para o cliente de forma ativa. Qualquer mensagem enviada pelo bot, após um período de 24 horas em relação à última mensagem enviada pelo cliente é considerada uma notificação. Para saber mais sobre as diferenças entre uma mensagem normal e uma notificação clique aqui. Notificações no WhatsApp estão sempre associadas a um Modelo de Mensagem (Message Template), previamente aprovado pelo próprio WhatsApp. Para enviar uma notificação (mensagem ativa) é necessário garantir que os pré-requisitos abaixo já foram satisfeitos: Ter um bot previamente publicado no canal WhatsApp (disponível apenas para clientes com plano) Ter um Message Template criado e aprovado pelo WhatsApp Depois de criar e aprovar seu Message Template você terá acesso ao valor NAME (caractere hexadecimal). Esses valores identificam seu Message Template e serão necessários durante o processo. Enviando uma notificação Para realizar o envio de uma notificação através da API do BLiP será necessário realizar 2 requisições HTTP na API do BLiP. A primeira delas tem o objetivo de buscar o identificador de um cliente no WhatsApp e deverá ser executada uma única vez para cada usuário. Já a segunda requisição é responsável por efetivamente disparar uma notificação através de um Message Template específico. Requisição 1: Buscando o identificador de um cliente Antes de enviar uma notificação, é 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 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, 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) +5531999998888Observação: Utilize a url com id do contrato para consumir os endpoints informados abaixo, sua performance e funcionamento podem ser impactados caso não esteja com id do contrato, portanto, é fundamental utilizar a url com o id do contrato para utilizar as requisições http! POST https://{{contractid}}.http.msging.net/commands HTTP/1.1Content-Type: application/json Authorization: Key YOUR_TOKEN { "id": "a456-42665544000-0123e4567-e89b-12d3", "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 com 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" } } Obs.: Essa operação deve ser executada uma única vez para cada cliente. Requisição 2: Envio da notificação com texto somente De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553175713755@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type": "body", "parameters": [ { "type": "text", "text": "parâmetro1" }, { "type":"text", "text":"parâmetro2" } ] } ] } } } (A requisição acima contém 3 variáveis apresentadas no campo parameters. Se o modelo de mensagem não tiver variáveis, retirar o componente parameters com todos os seus objetos internos, ou abrir e fechar colchetes. Exemplo: "parameters": [] ) Requisição 3: Envio da notificação com imagem De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553199998888@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type":"header", "parameters":[ { "type":"image", "image":{ "link":"https://www.blip.ai/wp-content/uploads/2018/02/logo-blip.png" } } ] }, { "type":"body", "parameters":[ ] } ] } } } Requisição 4: Envio da notificação com vídeo De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: O tamanho do vídeo deve ser de no máximo 16MB. Não são aceitos links do YouTube, como: https://www.youtube.com/watch?v=WU9gzjhyrcc http://youtu.be/WU9gzjhyrcc POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553199998888@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type":"header", "parameters":[ { "type":"video", "video":{ "link":"http://techslides.com/demos/sample-videos/small.mp4" } } ] }, { "type":"body", "parameters":[ ] } ] } } } Requisição 5: Envio da notificação com documento De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553199998888@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type":"header", "parameters":[ { "type":"document", "document":{ "filename":"take.pdf", "link":"http://www.orimi.com/pdf-test.pdf" } } ] }, { "type":"body", "parameters":[ { "type":"text", "text":"BLiP" } ] } ] } } } Requisição 6: Envio da notificação com quick reply De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553175713755@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type": "body", "parameters": [ { "type": "text", "text": "Uma mensagem qualquer. Gostaria de responder?" } ] }, { "type": "button", "sub_type": "quick_reply", "index": 0, "parameters": [ { "type": "payload", "payload": "Sim" } ] }, { "type": "button", "sub_type": "quick_reply", "index": 1, "parameters": [ { "type": "payload", "payload": "Sim" } ] } ] } } } Note que além do token do bot e do identificador do cliente será necessário alterar no corpo da requisição o valor MESSAGE_TEMPLATE_NAME correspondentes ao Message Template pré aprovado. Além disso é preciso inserir os valores das varáveis definidas na criação do Message Template, quando for o caso. Direcionamento do usuário para um subbot cadastrado como serviço de um router Importante: Para este processo funcionar, nas configurações do fluxo, a opção Utilizar o contexto do Roteador, deve estar ligada em todos os subbots (serviços) do router. Para realizar o direcionamento para um subbot cadastrado como serviço de um router, após o envio de uma mensagem ativa via API, é preciso executar a requisição Master state para identificá-lo. Master state: POST https://{{contractid}}.http.msging.net/commands HTTP/1.1Content-Type: application/jsonAuthorization: Key {YOUR_ROUTER_TOKEN}{"id": "{{$guid}}","to": "postmaster@msging.net","method": "set","uri": "/contexts/{{contact.identity}}/Master-State","type": "text/plain","resource": "{{idDoSubbot}}@msging.net"} Caso queira fazer o direcionamento para um bloco específico do bot, é necessário executar a requisição change user state, utilizando o mesmo contact.identity e a mesma key de autorização do router. Change user state: POST https://http.msging.net/commands HTTP/1.1Content-Type: application/jsonAuthorization: Key {YOUR_ROUTER_TOKEN}{ "id": "{{$guid}}", "to": "postmaster@msging.net", "method": "set", "uri": "/contexts/{{contact.identity}}/stateid@{{flow-identifier}}", "type": "text/plain", "resource": "{{state-id}}"} Vale ressaltar que o bloco para o qual o usuário será direcionado, não irá exibir seu conteúdo, executando apenas as condições e ações de saída, que serão validadas após a resposta do usuário. Por este motivo, é aconselhável manter um botão de input do usuário (entrada do usuário) no bloco onde será recebida a mensagem do usuário e sem conteúdo (mensagens). Logo criar uma condição de saída para tratar a resposta dele e direcionar para o bloco desejado. Exemplo: Para mais informações, acesse a discussão sobre o assunto em nossa comunidade ou os vídeos no nosso canal. 😃 Artigos relacionados Como enviar notificações via API Active Campaign (Growth) Atualização do canal WhatsApp - Check Contact Envio de Mensagens Ativas do WhatsApp no Blip Desk Configuração do arquivo de audiência - Envio de notificações em massa Criando mensagens interativas no WhatsApp
Índice: Introdução Enviando uma notificação Requisição 1: Buscando o identificador de um cliente Requisição 2: Envio da notificação com texto somente Requisição 3: Envio da notificação com imagem Requisição 4: Envio da notificação com vídeo Requisição 5: Envio da notificação com documento Requisição 6: Envio da notificação com quick reply Direcionamento para um subbot cadastrado como serviço de um router Introdução Através do BLiP, é possível criar aplicações para o canal WhatsApp capazes não só de responder às mensagens recebidas, mas também de enviar mensagens (notificações) para o cliente de forma ativa. Qualquer mensagem enviada pelo bot, após um período de 24 horas em relação à última mensagem enviada pelo cliente é considerada uma notificação. Para saber mais sobre as diferenças entre uma mensagem normal e uma notificação clique aqui. Notificações no WhatsApp estão sempre associadas a um Modelo de Mensagem (Message Template), previamente aprovado pelo próprio WhatsApp. Para enviar uma notificação (mensagem ativa) é necessário garantir que os pré-requisitos abaixo já foram satisfeitos: Ter um bot previamente publicado no canal WhatsApp (disponível apenas para clientes com plano) Ter um Message Template criado e aprovado pelo WhatsApp Depois de criar e aprovar seu Message Template você terá acesso ao valor NAME (caractere hexadecimal). Esses valores identificam seu Message Template e serão necessários durante o processo. Enviando uma notificação Para realizar o envio de uma notificação através da API do BLiP será necessário realizar 2 requisições HTTP na API do BLiP. A primeira delas tem o objetivo de buscar o identificador de um cliente no WhatsApp e deverá ser executada uma única vez para cada usuário. Já a segunda requisição é responsável por efetivamente disparar uma notificação através de um Message Template específico. Requisição 1: Buscando o identificador de um cliente Antes de enviar uma notificação, é 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 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, 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) +5531999998888Observação: Utilize a url com id do contrato para consumir os endpoints informados abaixo, sua performance e funcionamento podem ser impactados caso não esteja com id do contrato, portanto, é fundamental utilizar a url com o id do contrato para utilizar as requisições http! POST https://{{contractid}}.http.msging.net/commands HTTP/1.1Content-Type: application/json Authorization: Key YOUR_TOKEN { "id": "a456-42665544000-0123e4567-e89b-12d3", "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 com 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" } } Obs.: Essa operação deve ser executada uma única vez para cada cliente. Requisição 2: Envio da notificação com texto somente De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553175713755@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type": "body", "parameters": [ { "type": "text", "text": "parâmetro1" }, { "type":"text", "text":"parâmetro2" } ] } ] } } } (A requisição acima contém 3 variáveis apresentadas no campo parameters. Se o modelo de mensagem não tiver variáveis, retirar o componente parameters com todos os seus objetos internos, ou abrir e fechar colchetes. Exemplo: "parameters": [] ) Requisição 3: Envio da notificação com imagem De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553199998888@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type":"header", "parameters":[ { "type":"image", "image":{ "link":"https://www.blip.ai/wp-content/uploads/2018/02/logo-blip.png" } } ] }, { "type":"body", "parameters":[ ] } ] } } } Requisição 4: Envio da notificação com vídeo De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: O tamanho do vídeo deve ser de no máximo 16MB. Não são aceitos links do YouTube, como: https://www.youtube.com/watch?v=WU9gzjhyrcc http://youtu.be/WU9gzjhyrcc POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553199998888@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type":"header", "parameters":[ { "type":"video", "video":{ "link":"http://techslides.com/demos/sample-videos/small.mp4" } } ] }, { "type":"body", "parameters":[ ] } ] } } } Requisição 5: Envio da notificação com documento De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553199998888@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type":"header", "parameters":[ { "type":"document", "document":{ "filename":"take.pdf", "link":"http://www.orimi.com/pdf-test.pdf" } } ] }, { "type":"body", "parameters":[ { "type":"text", "text":"BLiP" } ] } ] } } } Requisição 6: Envio da notificação com quick reply De posse do identificador do cliente que receberá a notificação, realize a requisição HTTP descrita abaixo alterando o id desta: POST https://{{contractid}}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key YOUR_TOKEN { "id":"{{$guid}}", "to":"553175713755@wa.gw.msging.net", "type":"application/json", "content":{ "type":"template", "template":{ "name":"{{MESSAGE_TEMPLATE_NAME}}", "language":{ "code":"pt_BR", "policy":"deterministic" }, "components":[ { "type": "body", "parameters": [ { "type": "text", "text": "Uma mensagem qualquer. Gostaria de responder?" } ] }, { "type": "button", "sub_type": "quick_reply", "index": 0, "parameters": [ { "type": "payload", "payload": "Sim" } ] }, { "type": "button", "sub_type": "quick_reply", "index": 1, "parameters": [ { "type": "payload", "payload": "Sim" } ] } ] } } } Note que além do token do bot e do identificador do cliente será necessário alterar no corpo da requisição o valor MESSAGE_TEMPLATE_NAME correspondentes ao Message Template pré aprovado. Além disso é preciso inserir os valores das varáveis definidas na criação do Message Template, quando for o caso. Direcionamento do usuário para um subbot cadastrado como serviço de um router Importante: Para este processo funcionar, nas configurações do fluxo, a opção Utilizar o contexto do Roteador, deve estar ligada em todos os subbots (serviços) do router. Para realizar o direcionamento para um subbot cadastrado como serviço de um router, após o envio de uma mensagem ativa via API, é preciso executar a requisição Master state para identificá-lo. Master state: POST https://{{contractid}}.http.msging.net/commands HTTP/1.1Content-Type: application/jsonAuthorization: Key {YOUR_ROUTER_TOKEN}{"id": "{{$guid}}","to": "postmaster@msging.net","method": "set","uri": "/contexts/{{contact.identity}}/Master-State","type": "text/plain","resource": "{{idDoSubbot}}@msging.net"} Caso queira fazer o direcionamento para um bloco específico do bot, é necessário executar a requisição change user state, utilizando o mesmo contact.identity e a mesma key de autorização do router. Change user state: POST https://http.msging.net/commands HTTP/1.1Content-Type: application/jsonAuthorization: Key {YOUR_ROUTER_TOKEN}{ "id": "{{$guid}}", "to": "postmaster@msging.net", "method": "set", "uri": "/contexts/{{contact.identity}}/stateid@{{flow-identifier}}", "type": "text/plain", "resource": "{{state-id}}"} Vale ressaltar que o bloco para o qual o usuário será direcionado, não irá exibir seu conteúdo, executando apenas as condições e ações de saída, que serão validadas após a resposta do usuário. Por este motivo, é aconselhável manter um botão de input do usuário (entrada do usuário) no bloco onde será recebida a mensagem do usuário e sem conteúdo (mensagens). Logo criar uma condição de saída para tratar a resposta dele e direcionar para o bloco desejado. Exemplo: Para mais informações, acesse a discussão sobre o assunto em nossa comunidade ou os vídeos no nosso canal. 😃