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:

1. MESSAGE (mensagens recebidas): mensagens recebidas pela API, enviadas pelo usuário final;
2. 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 endpoint do serviço de disparo de mensagens de WhatsApp é  https://api.zenvia.com/v2/channels/whatsapp/messages.

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 Tier da 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.