Uma chave de API é uma senha que você entrega a outro sistema para ele usar o BotoZap em seu nome. Com ela, o site da sua loja, o seu sistema de gestão, uma automação (como o n8n) ou um programa feito pelo seu desenvolvedor consegue, por exemplo, mandar mensagens, consultar contatos ou criar oportunidades no funil, sem ninguém abrir o painel.
Você só precisa de uma chave se alguém for integrar outro sistema ao BotoZap. Para usar o painel no dia a dia, não precisa.
As chaves ficam em Configurações › Chaves de API.
Antes de começar
- Criar e revogar chaves é só para Administrador. Se você trabalha sozinho, você já é o Administrador da conta. Quem é Operador vê a lista, mas não vê o botão Nova chave nem a opção de revogar.
- A chave vale para a conta inteira: uma mesma chave alcança todos os seus clientes, e quem integra escolhe o cliente em cada pedido. O seletor de cliente do topo não muda nada nesta tela.
- Combine com quem vai integrar o que o sistema precisa fazer. Isso define as permissões.
Produção ou Sandbox
Ao criar uma chave, você escolhe o Ambiente:
- Produção: a chave trabalha com os seus canais reais, os números de WhatsApp e a conta do Instagram. Mensagens enviadas com ela chegam aos contatos de verdade. O código da chave começa com
bz_live_. - Sandbox: um ambiente de testes. Nada é enviado ao WhatsApp nem ao Instagram de verdade: o BotoZap simula os envios e as respostas, sem custo. O código começa com
bz_sandbox_. É o ideal para o desenvolvedor montar e testar a integração antes de ligar na produção. Com uma chave Sandbox ativa, a tela Canais mostra também um número e uma conta do Instagram de teste, com o selo Sandbox.
Na lista, as chaves de testes aparecem com a etiqueta Sandbox ao lado do nome.
Permissões em linguagem simples
Cada chave só faz o que você marcar em Permissões. É preciso marcar pelo menos uma. Em geral, cada assunto tem duas opções:
- Ler (ou Consultar): o sistema só consulta. Exemplos: Ler mensagens, Ler contatos, Ler templates, Ler transmissões.
- Gerenciar: o sistema também cria, altera ou apaga. Exemplos: Gerenciar contatos, Gerenciar templates, Gerenciar transmissões, Gerenciar agendamentos.
Algumas permissões merecem atenção especial:
- Enviar mensagens: o sistema manda mensagens pelos seus canais para os seus contatos, no WhatsApp e no Instagram.
- Gerenciar agentes: o sistema configura os agentes de IA e controla o atendimento.
- Gerenciar webhooks: o sistema escolhe para onde o BotoZap manda os avisos automáticos. Veja Webhooks.
- Gerenciar clientes e Gerenciar números: o sistema mexe no cadastro dos seus clientes e dos números conectados.
- Enviar arquivos de mídia: o sistema guarda no BotoZap imagens, vídeos, áudios e documentos a partir de um link, para usar depois nas mensagens.
- Ler regras de comentário e Gerenciar regras de comentário: o sistema consulta ou altera as regras de Comentários → DM do Instagram.
- Ler plano e cobrança e Gerenciar slots adicionais: o sistema consulta o plano e os slots adicionais (com vencimento e link da fatura) ou compra e cancela slots de R$ 47 por mês. Comprar um slot gera cobrança. Veja Plano e cobrança.
- Ler respostas rápidas e Gerenciar respostas rápidas: o sistema consulta ou altera as respostas rápidas que você usa no atendimento.
Cada opção da tela traz uma descrição curta do que libera. Na dúvida, marque só o que a integração precisa: uma chave com menos permissões causa menos estrago se vazar.
Passo a passo: criar uma chave
- Abra Configurações › Chaves de API e clique em Nova chave.
- Em Nome da chave, escreva onde ela vai ser usada, por exemplo "Site da loja" ou "Integração n8n". O nome ajuda a saber qual chave revogar depois.
- Em Ambiente, escolha Produção ou Sandbox.
- Em Permissões, marque o que a integração precisa.
- Em Expiração, a chave já vem com Em 1 ano. Você pode trocar por Nunca expira, Em 30 dias, Em 90 dias ou Data específica…. Com data específica, a chave vale até o fim do dia escolhido, no horário de Brasília.
- Se quiser, em IPs autorizados, informe de quais endereços a chave pode ser usada (veja Limitar a chave a certos IPs). Em branco, a chave funciona de qualquer lugar.
- Clique em Gerar chave.
- Na janela Sua nova chave de API, clique no botão de copiar e guarde a chave em um lugar seguro, ou entregue direto para quem vai integrar.
- Clique em Já guardei a chave.
Importante: a chave completa aparece uma única vez. Depois que você fecha a janela, o BotoZap não consegue mostrá-la de novo. Se ela se perder, revogue e crie outra.
A janela só fecha pelo botão Já guardei a chave, para você não perder a chave com um clique fora dela.
Limitar a chave a certos IPs
Por padrão, uma chave funciona de qualquer lugar da internet. Se a sua integração sempre chama o BotoZap do mesmo servidor, você pode restringir a chave aos IPs desse servidor. Assim, mesmo que a chave vaze, ela não serve para quem chamar de outro lugar.
No campo IPs autorizados, escreva um endereço por linha (ou separados por vírgula). Cada item pode ser:
- um IP simples, como
203.0.113.10; - uma faixa, como
198.51.100.0/24; - um IP ou faixa IPv6, como
2001:db8::/32.
Cabem até 20 itens por chave. Deixar em branco libera qualquer IP, como antes. Chamadas de um IP fora da lista recebem o erro ip_not_allowed e ficam registradas nos registros de API.
Como descobrir o IP do servidor. É o IP de onde a chamada sai, não o do seu computador. Peça à pessoa que cuida da hospedagem ou da automação (n8n, Make, servidor da loja) o "IP de saída" ou "IP fixo de saída". Se ela não souber, faça o próprio servidor consultar um serviço como https://api.ipify.org e anote o resultado. Atenção: hospedagens que trocam de IP a cada execução (algumas funções serverless e planos gratuitos) não combinam com esta lista, a menos que tenham IP fixo.
Cuidado para não travar a sua integração. Se o IP estiver errado ou mudar, a integração para de funcionar até você corrigir a lista. Para ajustar, abra a linha da chave, clique em Editar IPs autorizados e salve: vale na próxima chamada. Na dúvida, apague a lista para liberar qualquer IP e refaça com calma.
Só Administrador edita a lista. Ela vale para chaves ativas; as chaves já revogadas não podem ser editadas.
Acompanhar as chaves
A lista mostra, para cada chave:
- Nome e, se for de testes, a etiqueta Sandbox;
- Prefixo: o começo do código, para você reconhecer a chave sem expor o resto;
- Permissões marcadas;
- IPs autorizados: a lista da chave, ou Qualquer IP;
- Status: Ativa, Expirada ou Revogada;
- Expira em: a data de expiração ou Nunca;
- Último uso: a última data em que um sistema usou a chave, ou Nunca.
Use os filtros Ativas, Expiradas, Revogadas e Todas no alto da lista. A tela abre em Ativas.
O sino avisa 30 dias e de novo 7 dias antes de uma chave vencer, e os Administradores recebem um e-mail em cada aviso. A chave criada com até 30 dias de prazo só recebe o aviso dos 7 dias, e a de até 7 dias não recebe aviso. Depois de trocar na integração, revogue a chave antiga: o aviso some quando ela vence ou é revogada. O sino também avisa quando uma chave passa 90 dias sem uso; ela continua funcionando até alguém revogar.
Dica: uma chave ativa com Último uso muito antigo pode ser de uma integração desligada. Confirme com quem integrou e revogue se não for mais usada.
Passo a passo: revogar uma chave
Revogar é desligar a chave para sempre. Faça isso quando uma integração for desativada, quando alguém que tinha a chave sair da equipe ou se você suspeitar que ela vazou.
- Na linha da chave, clique no botão de três pontos (Ações da chave).
- Clique em Revogar.
- Confirme em Revogar chave.
A mensagem Chave revogada confirma. A partir desse momento, qualquer sistema que use essa chave para de funcionar, e não há como desfazer. Se a integração ainda for necessária, crie uma chave nova e entregue a quem cuida dela.
Problemas comuns
O botão Nova chave não aparece. Seu papel na conta é Operador. Peça a um Administrador.
Aparece "Chaves de API indisponíveis agora." O BotoZap não conseguiu carregar a lista neste momento. Suas chaves continuam valendo e as integrações seguem funcionando; atualize a página em instantes.
O botão Gerar chave fica apagado. Marque pelo menos uma permissão.
Aparece "A data de expiração precisa ser no futuro." ou "A data de expiração é muito distante (máx. 10 anos)." Escolha uma data a partir de amanhã e dentro de dez anos.
A integração parou de funcionar. Confira o Status da chave. Se estiver Expirada ou Revogada, crie uma nova e entregue a quem cuida da integração. Se estiver Ativa, peça a quem integrou para conferir os registros em Registros de API, Meta e webhooks.
A integração recebe ip_not_allowed. O IP de onde ela chama não está na lista da chave. A mensagem do erro mostra o IP que o BotoZap viu: confira se é o do servidor certo e adicione-o em Editar IPs autorizados.
Perdi a chave logo depois de criar. Não há como ver de novo. Revogue a chave perdida e crie outra.
