Documentação da API
A API do BotChat G-LINK conecta o seu WhatsApp automatizado com o resto do seu negócio: seu sistema manda mensagens e consulta o status da conexão, e recebe automaticamente cada mensagem que o bot não sabe responder — pra você devolver dados reais (fatura, pedido, agendamento) na hora.
👋 Introdução
Toda conta do BotChat G-LINK tem uma chave de API própria, gerada na aba Integração do painel. Com ela, dá pra fazer duas coisas de fora do painel: enviarAdmin (mandar uma mensagem pelo bot) e statusAdmin (consultar se a conexão está aberta). Por segurança, a chave não libera mais nada além disso — qualquer outra ação exige estar logado no painel.
No sentido contrário, o Webhook de Integração faz o bot avisar o seu sistema toda vez que recebe uma mensagem que não bate com nenhuma resposta configurada — assim seu servidor responde com dado de verdade, puxado do seu próprio banco.
enviarAdmin, statusAdmin e o Webhook de Integração funcionam do mesmo jeito nos planos Básico e Pro — dá pra montar seu próprio sistema de integração (parecido com um painel de gestão que consulte, dispare mensagens e receba avisos do bot) em qualquer um dos dois.
🧰 O que você precisa pra integrar
Antes de sair copiando os exemplos, um checklist rápido do que precisa existir do seu lado:
| Item | Pra quê |
|---|---|
| Um servidor/hospedagem própria | Onde o código do seu endpoint roda — não precisa ser nada caro (VPS, Render, Railway...) |
| HTTPS válido | Obrigatório em produção. Pra testar antes, o ngrok expõe seu servidor local com HTTPS grátis |
| Chave de API | Só se for mandar mensagem ou checar status pelo seu sistema (enviarAdmin/statusAdmin) |
| URL do webhook configurada | Em Integração, dentro do painel — só se for receber pergunta do bot |
| Sistema organizado por telefone | A parte mais importante: seu banco precisa achar o cliente pelo número que chega em cada chamada |
| Alguém que programe | Pegar a chave e configurar a URL não exige programação — mas escrever a lógica do endpoint, sim |
| Resposta em até 5 segundos | É o tempo que o bot espera pelo seu webhook antes de desistir |
🔐 Autenticação
📍 Onde pegar sua chave
- Entre no painel e clique em 🔑 Integração, no menu lateral esquerdo.
- Na seção Chave de API, sua chave aparece mascarada (uma fileira de pontinhos).
- Clique em 👁 Revelar pra ver ela, ou direto em 📋 Copiar pra copiar sem nem revelar na tela.
- Suspeitou de vazamento? 🔄 Regenerar cria uma chave nova e desativa a antiga na hora.
Todas as chamadas para a API devem incluir sua chave no header x-api-key. Pegue a sua em Integração → Chave de API, dentro do painel.
Nos exemplos desta página, troque https://SEU-DOMINIO.com pelo endereço de verdade do seu site — é o mesmo domínio onde o seu painel está publicado.
Nunca exponha essa chave em código que roda no navegador do cliente (front-end) — ela deve viver só no seu servidor. Se suspeitar de vazamento, regenere a chave a qualquer momento em Integração; a antiga para de funcionar na hora.
🔌 Tipos de conexão: QR code ou API Oficial
Antes de mandar qualquer coisa pela API, seu número precisa estar conectado. Hoje existem duas formas de fazer isso, com vantagens diferentes — escolha a que faz mais sentido pro seu caso.
| 📷 WhatsApp (QR code) | ✅ API Oficial (Meta) | |
|---|---|---|
| Como ativa | Escaneia o QR code, pronto em minutos | Cola token, número e Business ID gerados no Meta Business Manager |
| Custo por mensagem | Nenhum, além da mensalidade do plano | Cobrado pelo próprio Meta, direto na conta comercial do cliente |
| Risco de banimento | Existe (não é canal oficial) — bem menor com proxy dedicado | Praticamente nenhum — é o canal sancionado pelo WhatsApp |
| Fora da janela de 24h | Manda qualquer mensagem, sem restrição | Só templates pré-aprovados pelo Meta |
| Disponível em | Todos os planos | A partir do plano Pro |
📡 Proxy dedicado — por que ele reduz o risco no QR code
O WhatsApp desconfia de números que parecem estar sendo operados por automação em massa — um dos sinais que ele observa é vários números diferentes mandando mensagem a partir do mesmo endereço de IP (comum quando várias contas rodam no mesmo servidor). Com o proxy dedicado (plano Pro), cada conexão sai por um IP próprio e estável, parecendo uma pessoa normal usando o WhatsApp de um único lugar — reduz bastante esse sinal de alerta, mesmo continuando no canal não-oficial (Baileys).
📍 Passo a passo completo: como pegar as credenciais da API Oficial (plano Pro)
- Acesse business.facebook.com e clique em "Criar conta". Preencha o nome do portfólio empresarial, seu nome e um e-mail comercial que você tenha acesso — o Meta manda um código de confirmação pra ele.
- Depois de confirmar o e-mail, você já está dentro do Business Manager. Vá em ⚙️ Configurações → Configurações da empresa → menu lateral Contas → Contas do WhatsApp.
- Clique em "+ Adicionar" → "Crie uma nova conta do WhatsApp Business". Preencha o nome de exibição (igual ao nome comercial) e a categoria do negócio, e clique em Continuar.
- Nas próximas etapas do mesmo assistente, adicione e verifique o número que vai usar — precisa ser um número novo, que ainda não esteja ativo no WhatsApp normal ou Business comum (ele "migra" pra dentro da API, não dá pra usar nos dois ao mesmo tempo). A verificação chega por SMS ou ligação.
- Pra gerar o token de acesso permanente (o token rápido que aparece de cara expira em 23h): vá em Usuários → Usuários do sistema → Adicionar, crie um com papel Admin, depois "Atribuir ativos" selecionando a conta do WhatsApp criada no passo 3, e gere o token marcando as permissões whatsapp_business_management e whatsapp_business_messaging.
- Copie o Phone Number ID (fica nos detalhes do número — é o que vai no campo "Número") e o WABA ID (fica nos detalhes da conta do WhatsApp em si — é o que vai no campo "Business ID"). Atenção: o WABA ID é diferente do ID geral do Business Manager que aparece em "Informações da empresa" — não confunda os dois, senão a conexão falha.
- Cole essas 3 informações (token, número, WABA ID) na tela "Nova conexão" do painel, escolhendo API Oficial (Meta) — sem QR code, a conexão já ativa direto.
| Se aparecer | O que fazer |
|---|---|
| "Não foi possível criar sua conta" ao criar a conta do WhatsApp | É travamento comum em portfólio empresarial recém-criado (proteção antifraude do próprio Meta) — não é erro seu. Espera algumas horas e tenta de novo, sem precisar recriar nada. |
Esse cadastro é feito pelo próprio cliente na conta Meta dele — o BotChat G-LINK nunca vê nem guarda a senha da conta Meta, só as 3 credenciais que ele mesmo cola no painel.
📤 Enviar mensagem POST · enviarAdmin
Manda uma mensagem de texto pro cliente, pela conexão que você escolher.
| Campo | Descrição |
|---|---|
| instancia | Nome da conexão, igual aparece na aba Conexões do painel. |
| numero | Telefone do cliente com DDI + DDD, só dígitos (ex: 5511999887766). |
| mensagem | Texto que o bot vai mandar pro cliente. |
Respostas: 200 mensagem enviada · 400 faltou algum campo · 403 instância não pertence a essa conta · 409 conexão não está aberta no momento (precisa reconectar o WhatsApp) · 502 falha ao enviar, tenta de novo.
🔍 Consultar status POST · statusAdmin
Confere em tempo real (direto na Evolution API, sem cache) se uma conexão está aberta.
Devolve { instancia, existe, aberto, state } — aberto: true quando o WhatsApp está conectado e pronto pra mandar mensagem.
🔗 Webhook de integração POST · seu endpoint
Configure a URL do seu endpoint na aba Integração do painel. O bot chama esse endereço automaticamente sempre que recebe uma mensagem que não corresponde a nenhuma resposta configurada — seu servidor precisa responder em menos de 5 segundos.
Payload que seu endpoint recebe:
O que seu endpoint deve devolver:
🧪 Um número só, cuidando do negócio inteiro
Como hoje todo plano libera 1 conexão, o "multi" não está no número de linhas de WhatsApp — está no seu sistema, do outro lado, sabendo diferenciar cada cliente pelo telefone que chega em cada chamada. Um exemplo de como isso fica na prática, com uma lojinha qualquer:
| Opção do menu | Tipo de ação | O que acontece |
|---|---|---|
| 1 — Rastrear pedido | Webhook | Bot manda o telefone e a mensagem pro seu sistema, que procura o pedido e devolve o status real ("Seu pedido saiu pra entrega") |
| 2 — Pagar fatura em aberto | PIX | Bot gera o copia-e-cola na hora, usando a chave cadastrada em Configurações — sem chamar seu sistema |
| 3 — Falar com atendente | Atendente | Pausa o bot e avisa a equipe (aba Atendimento) — sem precisar de nenhuma linha extra de WhatsApp |
E fora do que o cliente digita, seu próprio sistema ainda pode tomar a iniciativa: usar statusAdmin pra confirmar que a conexão está aberta, e então enviarAdmin pra avisar sozinho ("seu pedido chegou ao destino") sem esperar o cliente perguntar nada.
🧩 Exemplo completo, pronto pra adaptar
Um endpoint mínimo que recebe o webhook acima e responde com dado real do seu sistema.
🚧 O que a API não faz (ainda)
Pra não perder tempo tentando: hoje a chave de API libera só enviarAdmin e statusAdmin. Isso fica de fora, por enquanto:
| Não dá pra fazer | Como fazer, então |
|---|---|
| Mandar foto, áudio ou documento | Só texto pela API — mídia é só pela aba Atendimento, dentro do painel |
| Listar as instâncias/conexões da conta | Ver o nome exato em Conexões, dentro do painel |
| Criar ou desconectar uma instância | Só pelo painel (aba Conexões) |
| Convidar atendente, trocar plano, regenerar a chave | Só logado no painel, como Administrador |
Isso é proposital: a chave de API é escopada de propósito só pra enviar/consultar, então mesmo vazando ela não dá acesso a nada administrativo da conta.
⚠️ Limites de uso e erros
Não há limite de chamadas do nosso lado. O limite prático é a estabilidade da conexão do WhatsApp — evite mandar um volume muito alto em pouco tempo, pra não correr risco de bloqueio pelo próprio WhatsApp.
Seu endpoint de webhook precisa responder em até 5 segundos. Se passar disso, o bot avisa o cliente que não conseguiu buscar a informação no momento — e não repete a chamada.
❓ Dúvidas frequentes
Não. O BotChat G-LINK fornece a ferramenta — o painel, a automação, a conexão com o WhatsApp. O número de telefone e o cadastro na API Oficial são feitos por você, direto no site do Meta (business.facebook.com), com seus próprios dados. A gente nunca cria conta no Meta em nome do cliente, nunca vê a senha, e não tem acesso à sua conta comercial — só recebe o token que você mesmo gera e cola no painel.
Tem um passo a passo completo (com print de cada tela) na seção Tipos de conexão, logo no início dessa documentação: criar o Business Manager, criar a conta do WhatsApp Business, verificar o número e gerar o token. Depois é só colar as 3 informações na tela "Nova conexão" do painel.
É cobrado direto pelo Meta, na sua própria conta comercial — não passa pelo BotChat G-LINK. A mensalidade que você paga aqui é só pelo uso da ferramenta (painel, automação, conexão); o consumo de mensagens da API Oficial é entre você e o Meta.
Não. O modo padrão é o QR code (Baileys) — escaneia e já ativa em minutos, sem criar conta nenhuma no Meta, e está disponível em todos os planos. A API Oficial é uma segunda forma de conectar, opcional, disponível a partir do plano Pro pra quem quer o canal oficial (sem risco de banimento) e não se importa em fazer o cadastro no Meta. O bot — menu automático, respostas, atendimento, API, webhook — funciona igual nos dois casos; muda só como o número fica conectado ao WhatsApp.
Isso só importa pra quem conecta via QR code (na API Oficial não existe essa distinção, o canal já é oficial). Sem proxy, sua conexão sai pelo IP do nosso servidor — como várias contas de clientes diferentes dividem esse mesmo IP, é um dos sinais que o WhatsApp observa pra detectar automação em massa. Com proxy dedicado (incluso no Pro), sua conexão passa a sair por um IP próprio e estável, só seu, parecendo uma pessoa normal usando o WhatsApp de um único lugar — reduz bastante esse sinal de alerta. Isso não elimina 100% o risco (continua sendo um canal não-oficial), mas diminui bastante comparado a não ter proxy nenhum. O plano Básico não inclui proxy; o Pro inclui.
Resumindo tudo que cabe dentro do painel: menu automático (fluxo de opções que o bot manda sozinho), respostas por palavra-chave (responde na hora quando o cliente digita certos termos, mesmo fora do menu), atendimento em equipe com fila compartilhada pra assumir a conversa manualmente (até 2 pessoas no Básico, até 5 no Pro), envio e consulta de mensagens pela sua própria API (enviarAdmin/statusAdmin), e o webhook de integração pra receber automaticamente cada pergunta que o bot não sabe responder, puxando dado real do seu sistema. Tudo isso funciona tanto no QR code quanto na API Oficial.
Pra pegar sua chave e configurar a URL do webhook, não. Mas pra fazer seu sistema conversar de fato com o bot (o "outro lado" da integração), é preciso alguém que programe — pode ser você, um funcionário, ou um freelancer.
Sim, em produção é obrigatório. Pra testes, ferramentas como ngrok expõem um servidor local com HTTPS gratuito.
O bot espera até 5 segundos. Se passar disso, ele avisa o cliente que não conseguiu buscar a informação no momento.
Não há limite do nosso lado. O limite prático é a estabilidade da conexão do WhatsApp — evite mandar um volume muito alto em pouco tempo pra não correr risco de bloqueio pelo próprio WhatsApp.