Bot do WhatsApp com número próprio
Passo a passo para ligar o bot de atendimento no WhatsApp da sua academia: instância Z-API, tokens, URL do webhook, QR Code e prompt.
- Menu: Configurações › Comunicação › WhatsApp e Bot do WhatsApp
- Plano: Profissional+
- Quem usa: Administrador
Nesta página (7)
- Para que serve
- Quem usa
- Passo a passo
- 1. Criar a instância na Z-API
- 2. Pegar o Client-Token da conta
- 3. Preencher o WhatsApp no BQuadra
- 4. Colar a URL nos webhooks da Z-API
- 5. Ler o QR Code
- 6. Escrever o prompt e a tabela de preços
- 7. Testar
- Campos importantes
- Regras do sistema
- Erros comuns e como resolver
- Dúvidas comuns
Para que serve
Com o número próprio, o WhatsApp da sua academia passa a responder sozinho quem manda mensagem: tira dúvidas, manda a tabela de preços e capta leads para o CRM. Esta página mostra, do começo ao fim, o que você faz no BQuadra e o que faz no painel da Z-API para o bot começar a atender.
O modo Número do BQuadra só envia notificações (códigos, cobranças e avisos) e não conversa. Para o bot, a academia precisa de uma instância da Z-API contratada à parte, ligada ao WhatsApp dela. A diferença entre os dois modos está em WhatsApp.
Quem usa
Só o administrador. A tela WhatsApp aparece a partir do plano Profissional. A tela Bot do WhatsApp depende do módulo CRM.
Passo a passo
1. Criar a instância na Z-API
-
Entre em app.z-api.io, abra Instâncias Web e clique em Adicionar.
-
Dê um nome (ex.: o nome da academia) e conclua a assinatura da instância.
-
Na lista, a instância aparece com ID e Token. Você vai copiar os dois para o BQuadra.

2. Pegar o Client-Token da conta
-
No menu da Z-API, abra Segurança.
-
Em 3. Token de segurança da conta, copie o token. Se estiver Inativo, ative antes.

Esse token é da conta, não da instância: é o mesmo para todas as instâncias que você tiver.
3. Preencher o WhatsApp no BQuadra
-
Abra Configurações › Comunicação › WhatsApp.
-
Clique em Número próprio.
-
Preencha ID da instância, Token da instância e Client-Token, colados da Z-API.
-
Ligue a chave Envios desta academia por esta instância (fica ON).
-
Em Bot de atendimento, marque Bot respondendo neste número.
-
Clique em Salvar. Aparece o campo URL do webhook; clique em Copiar.

A URL tem o formato https://webhook.bquadra.com.br/webhook/zapi/<academia>/<token>. Não compartilhe: quem tiver essa URL pode falar com o bot em nome da Z-API.
4. Colar a URL nos webhooks da Z-API
-
Na Z-API, abra a instância e a aba Webhooks e configurações gerais.
-
Cole a URL copiada em todos os seis campos: Ao enviar, Ao desconectar, Ao receber, Presença do chat, Receber status da mensagem e Ao conectar.
-
Deixe todas as chaves Ignorar webhook de… desligadas.
-
Em Ao receber, ligue Notificar as enviadas por mim também. É assim que o bot percebe quando alguém da academia respondeu pelo celular e fica em silêncio com aquele contato por 5 horas.
-
Salve.

5. Ler o QR Code
- Na Z-API, abra a instância e mostre o QR Code.
- No celular com o número da academia, abra o WhatsApp › Aparelhos conectados › Conectar um aparelho e leia o código.
- De volta ao BQuadra, clique em Verificar conexão. Tem que aparecer Ativo com o número conectado.
6. Escrever o prompt e a tabela de preços
- Abra Configurações › Comunicação › Bot do WhatsApp.
- Em Prompt do Sistema, escreva como o bot deve falar, o que a academia oferece, horários e regras. Clique em Salvar Prompt (vale em até 5 minutos).
- Em Documentos do Bot, envie o PDF da Tabela de Preços. No prompt, use a tag
[enviar_tabela_precos]para dizer quando o bot deve mandá-la.
Sem prompt, o bot não sabe o que responder: ele avisa que vai encaminhar para um atendente e fica em silêncio. Os detalhes do prompt e dos documentos estão em WhatsApp.
7. Testar
Mande uma mensagem de outro celular para o número da academia. O bot deve responder em alguns segundos. Se ele pedir atendimento humano, os administradores com esse aviso marcado recebem um WhatsApp (veja Avisos aos admins).
Campos importantes
- Número próprio — o WhatsApp da academia, na instância Z-API dela. Único modo com bot.
- Número do BQuadra — número compartilhado, incluso no plano. Só envia notificações.
- ID da instância e Token da instância — ficam na lista de instâncias da Z-API.
- Client-Token — token de segurança da conta Z-API (menu Segurança).
- Envios desta academia por esta instância (ON/OFF) — em OFF, nada sai por WhatsApp e o bot não responde.
- Bot respondendo neste número — liga o bot nesta instância. Precisa da chave acima em ON.
- URL do webhook — gerada ao salvar. Vai nos seis webhooks da instância na Z-API.
- Notificar as enviadas por mim também (Z-API) — manda ao BQuadra também o que a academia envia pelo celular, para o bot saber que um humano assumiu.
Regras do sistema
- O bot só funciona com Número próprio, instância em ON e Bot respondendo neste número marcado.
- A URL do webhook é única por academia. Se trocar de instância, cole a mesma URL nos webhooks da nova.
- Quando alguém da academia escreve pelo WhatsApp, respondendo ou puxando a conversa, o bot fica em silêncio com aquele contato por 5 horas a partir da última mensagem da academia, mesmo que o sistema seja reiniciado.
- Quando o bot não sabe responder, ele avisa que vai encaminhar para um atendente, fica em silêncio com aquele contato por 24 horas e avisa os administradores por WhatsApp, com as últimas 15 falas da conversa.
- Se o bot repetir a mesma pergunta pela terceira vez no cadastro da aula experimental, ele para e avisa os administradores (“BOT TRAVOU NO CADASTRO”). Cadastro parado há mais de 6 horas, ou retomado só com um “oi”, volta à conversa normal.
- Não cadastre em Avisos aos admins o celular do próprio WhatsApp da academia: o número conectado não recebe mensagem dele mesmo.
- Sem prompt salvo, toda mensagem cai no encaminhamento para atendente.
- Tokens ficam guardados cifrados. Campos com **** mantêm o valor salvo; para trocar, cole o valor novo.
Erros comuns e como resolver
- Botão mostra “Desconectado” — a instância não leu o QR Code ou caiu. Leia o QR Code de novo no painel da Z-API e clique em Verificar conexão.
- O bot não responde nada — confira, nesta ordem: instância em ON; Bot respondendo neste número marcado; URL colada no webhook Ao receber da Z-API; instância conectada.
- O bot só encaminha para atendente — falta o prompt em Bot do WhatsApp.
- O bot responde junto com a recepção — falta ligar Notificar as enviadas por mim também no webhook Ao receber da Z-API.
- “Credenciais não configuradas” — faltam ID da instância ou Token da instância. Preencha e salve.
- Erro de autorização na Z-API — o Client-Token está errado ou a conta ativou o token de segurança depois. Copie de novo em Segurança e salve.
Dúvidas comuns
Posso ter o bot usando o Número do BQuadra?
Não. O número do BQuadra é compartilhado e só envia notificações: ele não conversa. O bot só funciona no modo Número próprio, com a instância Z-API da academia.
Onde fica o Client-Token na Z-API?
Na conta, não na instância: menu Segurança › Token de segurança da conta. É o mesmo para todas as instâncias da conta.
Salvei e a URL do webhook não apareceu. Por quê?
A URL só é gerada depois de salvar no modo Número próprio. Confira se Número próprio está selecionado, clique em Salvar e a URL aparece abaixo de Bot respondendo neste número.
Preciso colar a URL nos seis webhooks mesmo?
Sim. Cada campo avisa o BQuadra de um evento diferente (mensagem recebida, enviada, status, presença, conexão). Sem o Ao receber o bot não ouve; sem o Ao enviar com Notificar as enviadas por mim também ele não percebe quando alguém da academia respondeu.
O bot respondeu junto comigo enquanto eu atendia pelo celular. O que faltou?
A chave Notificar as enviadas por mim também, no webhook Ao receber da Z-API. Com ela ligada, quando alguém da academia responde pelo WhatsApp o bot fica em silêncio com aquele contato por 5 horas.
Se eu mandar a primeira mensagem para o aluno, o bot responde quando ele retornar?
Não. Vale a mesma regra de quando a academia responde: a partir da sua última mensagem pelo WhatsApp, o bot fica em silêncio com aquele contato por 5 horas. Se o aluno responder depois disso, o bot volta a atender.
O bot só diz que vai encaminhar para um atendente. O que fazer?
Falta o prompt. Sem prompt em Configurações › Comunicação › Bot do WhatsApp, o bot não sabe o que responder e encaminha tudo para atendimento humano. Escreva o prompt e clique em Salvar Prompt.
A tela mostra Desconectado. E agora?
A instância ainda não leu o QR Code, ou o celular saiu do WhatsApp. Abra a instância no painel da Z-API e leia o QR Code com o celular do número da academia. Depois clique em Verificar conexão.
Obrigado! Que bom que ajudou.
Obrigado por avisar. Conte pelo WhatsApp o que faltou.