Pular para o conteúdo
BQuadra·Ajuda

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

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

  1. Entre em app.z-api.io, abra Instâncias Web e clique em Adicionar.

  2. Dê um nome (ex.: o nome da academia) e conclua a assinatura da instância.

  3. Na lista, a instância aparece com ID e Token. Você vai copiar os dois para o BQuadra.

    Lista Instâncias web da Z-API com a instância da academia, colunas ID e Token e o botão Adicionar

2. Pegar o Client-Token da conta

  1. No menu da Z-API, abra Segurança.

  2. Em 3. Token de segurança da conta, copie o token. Se estiver Inativo, ative antes.

    Tela Segurança da Z-API com o Token de segurança da conta ativo e o aviso para enviar no cabeçalho Client-Token

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

  1. Abra Configurações › Comunicação › WhatsApp.

  2. Clique em Número próprio.

  3. Preencha ID da instância, Token da instância e Client-Token, colados da Z-API.

  4. Ligue a chave Envios desta academia por esta instância (fica ON).

  5. Em Bot de atendimento, marque Bot respondendo neste número.

  6. Clique em Salvar. Aparece o campo URL do webhook; clique em Copiar.

    Tela WhatsApp do BQuadra em Número próprio, instância ON, Bot respondendo neste número marcado e a URL do webhook com o botão 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

  1. Na Z-API, abra a instância e a aba Webhooks e configurações gerais.

  2. 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.

  3. Deixe todas as chaves Ignorar webhook de… desligadas.

  4. 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.

  5. Salve.

    Aba Webhooks e configurações gerais da Z-API com a URL do BQuadra nos seis campos e a chave Notificar as enviadas por mim também ligada

5. Ler o QR Code

  1. Na Z-API, abra a instância e mostre o QR Code.
  2. No celular com o número da academia, abra o WhatsApp › Aparelhos conectados › Conectar um aparelho e leia o código.
  3. 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

  1. Abra Configurações › Comunicação › Bot do WhatsApp.
  2. 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).
  3. 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.

Esta página ajudou?