Como acessar a API de WhatsApp com a Twilio

Como acessar a API de WhatsApp com a Twilio

Eu sei que o WhatsApp alcançou uma popularidade gigantesca na América latina e em especial no Brasil, portanto seria muito natural o surgimento de serviços através da plataforma. Enquanto desenvolvedores, recebemos diversas demandas para implementação de chatbots, sistema de atendimento, entre outras necessidades para integrar com WhatsApp, porém encontrar algum material ou referência para integração não é uma tarefa trivial.

A Twilio fornece um ambiente para testes onde qualquer desenvolvedor pode montar seu protótipo antes de começar o processo de aprovação do Facebook. Então, se você teve uma ideia e quer validar seu funcionamento para entender se vale a pena construir um produto e colocá-lo em produção, vou ensinar neste artigo como configurar e utilizar a "WhatsApp Sandbox".

Antes de começar a usar a API do WhatsApp, você precisa entender que existem duas formas de interagir com o usuário:

1. Disparar mensagens de modelo: Essas mensagens podem ser disparadas a qualquer momento, devem seguir um modelo aprovado previamente pelo WhatsApp e podem possuir campos que são variáveis. Esta regra foi criada pelo Facebook para evitar propagandas indesejadas e também existe um custo diferenciado, por parte do WhatsApp, para disparar estas mensagens.
2. Receber mensagens do usuário: o usuário pode, a qualquer momento, enviar uma mensagem para seu número. Quando isso acontece, você tem uma janela de 24 horas para enviar qualquer mensagem sem restrição de conteúdo, ou seja, conversar com seu usuário da forma que achar mais apropriada.

O que é a WhatsApp Sandbox da Twilio?

Nossa Sandbox é um número aprovado no WhatsApp para receber e enviar mensagens e que possui alguns templates com casos de uso, para que você possa testar o envio de mensagens fora da janela de 24 horas.

Vou mostrar a seguir como configurar o webhook para ativar sua sandbox através de um passo a passo no Console da Twilio. Se você não quiser seguir o tutorial, acesse a configuração do Sandbox de WhatsApp diretamente e siga para a parte final deste artigo.

Ativando a Sandbox

Acesse diretamente o Assistente de Configuração da Sandbox WhatsApp ou vá para o Console da Twilio, no menu clique na opção "Programmable Messaging", em seguida no item "Try it Out" e finalmente no submenu "Try WhatsApp". Será exibida uma mensagem para ativar a Sandbox:

Uma vez que você marcou a caixa de aceite dos termos de serviço e clicou em "Confirm", a Sandbox está ativa e o primeiro passo será vincular seu número de WhatsApp.

Vinculando seu número de WhatsApp

Uma vez que a Sandbox foi ativada, você verá um código para vincular seu número de WhatsApp com a Sandbox. O seu telefone pode estar vinculado com apenas um único projeto da Twilio, por isso é necessário realizar esse vínculo. Lembre-se que pode trocar de projeto quando quiser.

Envie uma mensagem com o comando de "join [SEU IDENTIFICADOR]" para o número que aparece na tela, conforme a imagem acima. Para cada projeto no Console da Twilio, o código de join será diferente, assim você poderá convidar outros usuários para testarem sua aplicação

Uma vez que você tenha enviado o código de join corretamente, a caixa "Waiting for you message" mudará para "Message Received" e você poderá prosseguir para o próximo passo. Veja a seguir a mensagem que você receberá no WhatsApp confirmando que está com a Sandbox ativada.

Clique no botão "Next" para continuar.

Enviando mensagem de modelo

O próximo passo é testar o envio das mensagens de modelo, ou "template". Para isso, a Twilio aprovou com o WhatsApp 3 casos de uso para que você consiga testar na sua aplicação. Caso seu caso de uso específico não esteja de acordo com um dos 3 exemplos, você pode usar esses modelos como teste e, posteriormente, criar e aprovar seu modelo personalizado na sua conta.

Temos os seguintes modelos:

1. Appointment Reminders: são lembretes de agendamentos, como por exemplo uma consulta ou algum serviço com data e hora.
2. Order Notifications: informações sobre algum pedido feito em lojas.
3. Verification Codes: códigos de confirmação para validar seu número de celular.

Observe que nos 3 casos temos exemplos de situações transacionais. Os usuários são notificados no momento de ocorrência de alguma atualização dessas notificações. Quando criar seus modelos, certifique-se de que eles obedecem esse formato para não apenas trazer uma informação útil para seu usuário, mas também para criar um caso de uso claro e que possa ser aprovado.

Clique em um dos modelos que deseja testar para abrir o formulário. Vou usar aqui o modelo "Verification Codes".

O modelo pode possuir parâmetros que são dados variáveis conforme a mensagem que você vai disparar. Você não pode utilizar um parâmetro muito vago, sob risco de não ter seu modelo aprovado. Deve ficar claro qual tipo de dado será inserido naquele campo.

O parâmetro corresponde a um número entre duas chaves. Um exemplo seria Seu código de {{1}} é {{2}}, onde o primeiro parâmetro poderia ser aprovação, confirmação, verificação, validação do telefone, etc. e o segundo campo um valor numérico aleatório.

Continuando nosso tutorial, veja que na tela você pode fazer a chamada para disparar a mensagem direto do navegador ou executar localmente o código na linguagem de sua preferência.

Clique no botão "Make Request" para fazer a chamada na API. Você verá no item "Response" o retorno do servidor, conforme a imagem abaixo e receberá no seu WhatsApp a mensagem correspondente ao campo "Body".

Agora que você conseguiu enviar mensagens, vamos testar o recebimento delas. Clique em "Next" para continuar no próximo passo.

Recebendo uma mensagem do usuário

Este passo serve para demonstrar o recebimento das mensagens. Ao responder a mensagem que recebeu no aplicativo do WhatsApp, esta tela exibirá a última mensagem recebida de algum telefone que ativou a sandbox da sua conta. Lembrando que quando o usuário envia uma mensagem para seu número, o WhatsApp cria uma janela de 24 horas e você poderá enviar mensagens fora do modelo aprovado, ou seja, a partir deste momento, pode conversar com seu usuário. Ao final deste artigo, demonstrarei como você poderá responder as mensagens recebidas.

Vamos continuar para o próximo passo. Clique em "Next" e você será redirecionado para o último passo da configuração da Sandbox para WhatsApp da Twilio.

Configurando o webhook para meu servidor

Esta é a última tela do tutorial e também a tela de configuração da Sandbox na sua conta. Você pode acessá-la em qualquer momento a partir do submenu "WhatsApp Sandbox Settings", do  menu "Settings", dentro de "Programmable Messaging".

Nesta tela temos 3 áreas importantes:

1. Sandbox Configuration: com campos para definir o webook para mensagens recebidas e para acompanhar o status das mensagens
2. Sandbox Participants: você consegue conferir todos os números que estão com a sua sandbox ativa e o código para ativar a sandbox.
3. Sandbox Message Templates: os modelos aprovados de mensagens que você pode enviar pela sandbox. No momento, os modelos estão disponíveis apenas em Inglês.

Ao configurar seu webhook, observe que você pode informar qualquer URL, porém o método de chamada HTTP deve ser POST ou PUT apenas. Uma vez que você definiu a url do seu servidor, clique em "Save".

Pronto, sua Sandbox WhatsApp da Twilio está configurada e pronta para interagir com sua aplicação. Agora vamos ver como tratar as chamadas realizadas pelos servidores da Twilio quando receber mensagens do WhatsApp.

Como responder as chamadas do webhook da Twilio

Toda vez que um usuário enviar uma mensagem para nossa conta, a Twilio fará uma chamada HTTP para o seu servidor, repassando os dados do remetente e sua mensagem. Uma vez que seu servidor receber essa requisição, ele deverá responder em um padrão que chamamos de Twiml e essa resposta será enviada para o usuário através do WhatsApp.

Se você optar por não responder a mensagem, basta retornar um elemento "Response" vazio com o status HTTP como 200. Se você não fizer isso, resultará numa mensagem de erro dentro da plataforma da Twilio.

A Twiml para mensagens é bem simples e basicamente é um retorno no formato XML. Você vai utilizar uma tag "Response" e nela criar uma tag filha "Message". Essa tag pode ser parametrizada de duas formas: texto simples ou mensagem com anexo.

Exemplo de mensagem simples:

Exemplo de mensagem com mídia:

Você pode ter mais de um elemento "Message" em "Response". Isso fará com que apareçam duas mensagens distintas na interface do WhatsApp no lugar de uma. Os anexos podem ser imagens, vídeos, áudios ou arquivos PDF. Existem algumas regras de formatos e tamanhos de arquivos que são aceitos na plataforma.

Você não precisa fazer nenhuma chamada adicional na nossa API para responder seu usuário, mas se desejar enviar mensagens além dessa resposta ou enviar templates em outro momento, confira nosso artigo sobre como Enviar uma Mensagem de WhatsApp com JavaScript e Node.

Recapitulando

Terminamos nosso tutorial para que você consiga iniciar seus protótipos com a API do WhatsApp da Twilio. Espero que tenha gostado dessa introdução e que consiga dar os primeiros passos para criar seu serviço e engajar com seus usuários.

Se você deseja colocar seu chatbot em produção, confira nossa documentação sobre como conectar seu número da Twilio com a conta Business do WhatsApp (artigo em Inglês).

Fique a vontade para tirar dúvidas, enviar sugestões e conversar comigo sobre seus projetos. Mal posso esperar para ver o que você vai construir.

• Email: lleao@twilio.com
• Twitter: @luisleao
• Github: luisleao
• Twitch (live code): umleaopordia