Como enviar e receber mensagens de WhatsApp utilizando ZENVIA API’s
Confira o passo a passo para enviar e receber mensagens de WhatsApp utilizando a API da Zenvia. Teste agora!
agosto 13, 2021
- Por: Zenvia
min de leitura
Quer integrar a sua ferramenta com a API de WhatsApp da Zenvia e automatizar seus processos, mas ficou com dúvidas de como configurar este serviço? Este artigo se propõe a explicar de maneira simples e descomplicada como configurar um ambiente de integração, apresentando informações complementares à documentação técnica e exemplos de funcionamento do serviço de disparo e recebimento de mensagens de WhatsApp.
Para acessar a nossa documentação técnica e ter acesso a bibliotecas, especificações e informações mais detalhadas, clique aqui.
Este tutorial estará dividido em 4 seções que representam as etapas fundamentais do processo de integração:
Visão Geral
Autenticação
Configuração de Webhook para recebimento de eventos
Parâmetros e Construção da Requisição
Importante:
Os passos abaixo se aplicam à integração com uma conta WhatsApp Business API Oficial, em ambiente de Produção. Se você ainda não possui um número contratado com a Zenvia e deseja testar a API, crie uma conta gratuita na nossa plataforma e execute os testes utilizando a ferramenta Sandbox.
Como enviar mensagens de WhatsApp com a ZENVIA API’s
Visão Geral
A comunicação com a ZENVIA API’s irá ocorrer toda vez que a sua aplicação necessitar utilizar algum serviço da nossa API. Toda vez que a sua aplicação envia uma solicitação de disparo de mensagem para a API, vamos chamar de requisição.
Cada requisição é composta pelos elementos que serão apresentados nas próximas seções.
Exemplo visual de funcionamento da integração:
Autenticação
O primeiro passo para que a sua aplicação consiga se comunicar com a nossa API é a Autenticação.
A nossa API possui 2 opções de chaves de autenticação: JWT e TOKEN.
Acesse a seção Authentication da documentação e entenda qual destas chaves se aplica ao seu caso.
Caso você opte por autenticar via JWT, para obtê-lo basta acessar a nossa plataforma, logado na conta Oficial da sua empresa (na qual deve estar vinculado o número de WhatsApp). No menu principal, acesse a opção Área do Cliente > Preferências > Minhas Contas e obter o API Token:
Caso você opte por autenticar via TOKEN, logado na plataforma Zenvia, você deve acessar o caminho Produtos > Desenvolvedores > Tokens e Webhooks:
Caso ainda não haja nenhum Token disponível na sua conta, basta clicar em Criar Novo, escolher um nome e salvar:
Ele ficará disponível por tempo indeterminado e você pode consultá-lo quantas vezes for necessário:
Configuração de Webhook
Ter uma Webhook configurada e integrada com o ambiente da Zenvia, permite que você receba respostas da nossa API na sua aplicação.
Há dois tipos de eventos disponíveis:
MESSAGE (mensagens recebidas): mensagens recebidas pela API, enviadas pelo usuário final;
MESSAGE_STATUS (status da mensagem): status de envio das mensagens disparadas pela API (entregue, não entregue, lido, etc);
Para vincular o seu endereço de Webhook com a nossa plataforma, basta acessar o caminho Produtos > Desenvolvedores > Tokens e Webhooks e clicar em Criar Novo:
Versão: escolha sempre a opção V2. Só selecione a opção V1 se tiver sido recomendado pelo time Zenvia.
Tipo do Evento: Status ou Mensagem.
Canal: WhatsApp, para este tutorial.
Direção: quando o Tipo de Evento for Mensagem será habilitado este campo. Recomendamos que seja preenchido com a opção Ambos.
URL: deve ser preenchida com o endereço de Webhook.
Cabeçalhos: opcional. Deve ser configurado somente se a sua Webhook exigir algum tipo de método de autenticação.
Salve a configuração.
Parâmetros e Construção da Requisição
O Header ou Cabeçalho da requisição é formado por dois parâmetros:
Content-Type: application/json
X-API-TOKEN: deve ser preenchido o Token gerado na plataforma
O formato do body da requisição varia de acordo com o tipo de mensagem que será enviada.
O WhatsApp disponibiliza os seguintes tipos de mensagens: text, template, file, contact, location.
A documentação técnica fornece exemplos de cada um dos formatos bem como as especificidades de cada parâmetro:
Para este tutorial, usaremos os dois mais comuns: text e template.
Antes de mais nada, é necessário compreendermos que o WhatsApp só permite o contato ativo com o usuário final por meio de um Template pré-aprovado. Saiba como criar um Template clicando aqui.
Sendo assim, caso você esteja configurando um processo onde a empresa vai iniciar o contato, saiba que você precisará utilizar o tipo template.
As mensagens do tipo text poderão ser enviadas sempre no intuito de responder o usuário final. A janela para responder o usuário final usando mensagens do tipo text é de 24h. Passado este prazo, você precisa novamente enviar um template para retomar o contato.
Também não é permitido enviar uma mensagem do tipo text logo após o envio de um template, sem que o usuário já tenha respondido alguma vez. O WhatsApp sempre irá aguardar que haja uma interação por parte do usuário final para permitir o envio de uma mensagem do tipo text.
Template
Vamos iniciar então a simulação com o envio de uma mensagem do tipo template.
A estrutura da mensagem deve conter essencialmente o ID do template e todos os campos variáveis nele contidos.
No exemplo abaixo, o template possui as variáveis {{name}} e {{ticket}}:
Resultado do disparo:
Neste momento, já devemos ter recebido na Webhook cadastrada, o STATUS de entrega desta mensagem. Como a mensagem foi enviada, entregue e lida pelo usuário, receberemos 3 eventos:
Resposta do usuário final
Se o usuário final responder a mensagem, a API enviará um evento do tipo MESSAGE para a Webhook cadastrada, como no exemplo abaixo:
Text (mensagem simples)
Após as primeiras interações (envio de um Template e resposta do usuário final) a plataforma já permite o disparo de uma mensagem do tipo text.
Segue um exemplo de request:
Dúvidas frequentes:
1. Fiz o disparo de um template, recebi um retorno 200 OK da API, porém a mensagem não foi entregue. O que houve?
Resposta: Se você tiver uma Webhook de Status configurada, será possível consultar o status de erro no envio.
Os motivos mais comuns são:
não ter todas as variáveis de um template informadas na requisição;
URLs de imagens, vídeos, áudios ou documentos informados no Template não serem públicas e portanto, não poderem ser acessadas de maneira externa;
limite de envios atingido de acordo com o Tierda conta;
mensagem enviada fora da janela de 24h de contato (regra de contato ativo).
2. Como enviar uma mensagem com quebra de linha?
Resposta: Como no exemplo passada na seção Text, a quebra de linha é representada pelo símbolo \n.
No caso dos disparos de Template, a quebra de linha já deve estar prevista no modelo pré-aprovado.
3. Consigo passar informações com quebra de linha dentro de uma variável? Por exemplo, tenho uma variável {{pedidos}} e quero passar uma lista de números. Como faço?
Resposta: Não é possível passar informações em formato de lista como conteúdo de uma variável. No caso dos disparos de Template, a quebra de linha deve estar prevista dentro do modelo pré-aprovado.
4. Como enviar mensagens de WhatsApp com Emoji?
Resposta: Como no exemplo passada na seção Text, basta passar o próprio Emoji na requisição, pois a API está preparada para interpretar este formato de conteúdo. Você pode obter os Emojis padrão no WhatsApp em bibliotecas na Web;
No caso dos disparos de Template, o Emoji já deve estar previsto no modelo pré-aprovado.
5. Meu template possui cabeçalho com Imagem, Documento ou Vídeo. Como informar isso na requisição?
Resposta: Basta adicionar um parâmetro do array fields informando a URL do arquivo. O nome das variáveis são respectivamente: imageUrl, videoUrl e documentUrl. Exemplo:
6. Meu template não possui nenhuma variável, o que informar no array fields?
Resposta: Caso o template não possua nenhuma variável, basta manter o array fields vazio. Exemplo:
Esperamos que suas dúvidas tenham sido esclarecidas e que, a partir de agora, você esteja pronto para empoderar a sua comunicação junto com a gente! ?
*Amanda Niches é Analista de Atendimento ao Cliente (Customer Support) – plataformas Zenvia Bots, Zenvia Chat e WhatsApp API | LinkedIn.