API de WhatsApp para Bubble

O que dá para fazer com Bubble e WhatsApp

• Aviso a partir do app

  Cadastro, agendamento ou pagamento dispara uma mensagem para o cliente, direto do workflow.

• Mensagens no banco do Bubble

  O webhook cria um registro para cada mensagem recebida, com número, nome e texto.

• Disparo para uma lista

  Um backend workflow percorre a lista com intervalo entre os envios, dentro do limite da API.

• Atendimento pelo app

  A equipe lê e responde as conversas numa página do próprio app.

Enviar mensagens pelo Bubble

1. 1

   Configure o API Connector

   Em Plugins, instale o API Connector e adicione uma API. Em Authentication, escolha Private key in header, com Key name Authorization e Key value Bearer zpx_.... Assim a chave fica no servidor do Bubble e não vai para o navegador.

2. 2

   Crie a chamada de envio

   Os campos entre < > viram parâmetros. Eles nascem marcados como Private — desmarque para poder preenchê-los no workflow:

   Name:    Enviar texto
   Use as:  Action
   Method:  POST
   URL:     https://zapixo.com.br/api/v1/messages/text
   Header:  Content-Type: application/json
   
   Body (JSON):
   {
     "instance": "<instancia>",
     "number": "<numero>",
     "text": "<texto>"
   }

3. 3

   Inicialize com o seu número

   Initialize call faz uma chamada de verdade: a mensagem é enviada. Use uma instância conectada e o seu próprio número. O Bubble aprende a resposta (success, messageId) e libera a ação nos workflows.

4. 4

   Use em qualquer workflow

   A ação aparece em Plugins › Zapixo - Enviar texto. Antes, limpe o telefone com :find & replace usando expressão regular, para mandar só dígitos com DDI e DDD.

Receber mensagens no Bubble

1. 1

   Ligue o Workflow API

   Em Settings › API, marque Enable Workflow API and backend workflows. Depois, em Backend workflows, crie um API workflow — por exemplo, whatsapp.

2. 2

   Proteja o endereço com um token só dele

   O Zapixo não manda o token do Bubble no header, então ele vai na própria URL, como api_token. Gere em Settings › API um token exclusivo para isso: token do Bubble tem poder de administrador, e se vazar você apaga só ele.

   https://SEU-APP.bubbleapps.io/api/1.1/wf/whatsapp?api_token=TOKEN_SO_DO_WEBHOOK

3. 3

   Deixe o Bubble detectar os dados

   Em Parameter definition, escolha Detect data. Durante a detecção, a URL no painel do Zapixo termina em /initialize; mande uma mensagem para o número conectado e o Bubble passa a oferecer os campos — event e, dentro de data, o key com remoteJid, fromMe e id. Depois, volte a URL do painel para a versão sem /initialize.

4. 4

   Filtre e grave

   No workflow, use Only when event é messages.upsert e fromMe é não. O número sai do remoteJid com :split by (@) e :first item; o texto vem de message › conversation.

Erros comuns e como resolver

Mensagem enviada ao inicializar

É o comportamento do Initialize call: ele faz a chamada de verdade. Inicialize sempre com o seu próprio número.

Parâmetro que não aceita valor do workflow

O parâmetro ficou marcado como Private no API Connector. Parâmetro privado só aceita o valor fixo digitado na chamada.

Workflow rodando duas vezes

Se o backend workflow não responder em até 10 segundos, o Zapixo tenta de novo, até 3 vezes. Antes de criar o registro, procure uma mensagem com o mesmo id e só siga se a contagem for zero.

Consumo que dispara

Cada webhook recebido roda o workflow e consome capacidade do plano. Coloque o Only when no próprio workflow, para que fromMe e evento errado parem logo no início.

Erro do Zapixo parando o workflow

Marque Include errors in response and allow workflow actions to continue na chamada. Assim um 401, 404 ou 502 volta como dado e o workflow decide o que fazer.

Perguntas frequentes