Os registros (ou "logs") são o diário técnico do BotoZap: cada pedido feito por um sistema integrado, cada aviso que a Meta mandou e cada aviso que o BotoZap entregou ao seu sistema fica anotado, com data, hora e resultado. No dia a dia você não precisa deles. Eles servem para descobrir por que uma integração falhou e para dar ao suporte as informações certas.
São três telas, todas em Configurações, na parte Desenvolvedores:
- Logs de API: os pedidos feitos com as suas chaves de API e os avisos da Meta que o BotoZap não conseguiu processar.
- Logs da Meta: quantos avisos a Meta mandou para o BotoZap, hora a hora.
- Logs de webhook: os avisos que o BotoZap entregou (ou tentou entregar) aos seus webhooks.
Antes de começar
- Qualquer pessoa da equipe pode consultar os registros.
- Os registros são da conta inteira: o seletor de cliente do topo não muda nada nestas telas.
- Logs de API mostra os 200 registros mais recentes; Logs da Meta, as últimas 48 horas; Logs de webhook, os 200 mais recentes do filtro escolhido. A partir de 22/12/2026, a tela e a API mostram os registros de API dos últimos 30 dias; até lá, dos últimos 6 meses.
Como ler o código de resultado
A coluna HTTP traz um número de três dígitos que resume o resultado:
- 2xx (200, 201...): deu certo.
- 4xx (400, 401, 403, 404, 422...): o pedido foi recusado por um problema nele mesmo, como chave errada, permissão que falta ou dado inválido.
- 5xx (500, 502...): falhou do lado de quem recebeu o pedido.
Logs de API
Em Configurações › Logs de API, cada linha é um registro:
- Método e Path: o tipo de pedido e o endereço usado. O desenvolvedor reconhece por aqui o que o sistema tentou fazer, por exemplo enviar uma mensagem.
- HTTP: o resultado (veja acima).
- Origem: API para pedidos feitos com as suas chaves; Webhook Meta para avisos que a Meta mandou e o BotoZap não conseguiu processar, mesmo tentando de novo por algumas horas. Eles aparecem com HTTP 500 e o erro
processing_failed. Como o BotoZap tenta de novo por algumas horas antes de desistir, o registro entra horas depois, com a data e a hora em que o aviso chegou: ele pode ficar abaixo de registros mais novos. - Erro: o código de erro do BotoZap, quando houve.
- Duração: quanto tempo levou.
- Quando: data e hora, no horário de Brasília.
Acima da lista, o link Investigar por Conta, Cliente, Número e período abre a investigação de envios em Operação.
No alto da lista, filtre por origem (Todas as origens, API, Webhook Meta) e por resultado (Todos, 2xx, 4xx, 5xx). O botão Atualizar busca os registros mais recentes.
Clique numa linha para abrir o detalhe. Além das colunas, ele mostra:
- Código da aplicação: o código de erro do BotoZap.
- Código Meta (síncrono): o código de erro que a Meta devolveu na hora, quando houve.
- Resultado da tentativa, nos envios de mensagem:
- Aceita; entrega não comprovada: a Meta aceitou a mensagem. A confirmação de entrega chega depois e aparece em Mensagens.
- Recusa síncrona: a Meta recusou na hora. A mensagem não saiu.
- Desconhecido; reconciliar antes de reenviar: não dá para saber se a mensagem saiu. Confira em Mensagens antes de mandar de novo, para o contato não receber duas vezes.
- Ambiente: Produção ou Sandbox.
- Número (UUID): o código interno do número usado.
- Id da chamada: o código que a API devolveu no cabeçalho
x-request-iddaquela resposta. Mande esse código ao suporte quando precisar de ajuda com a chamada.
Não coletado quer dizer que aquele registro não guardou essa informação.
Logs da Meta
Configurações › Logs da Meta mostra quantos avisos a Meta mandou ao BotoZap nas últimas 48 horas, hora a hora, para cada número e conta do Instagram: mensagens recebidas e atualizações de entrega. Filtre por número ou conta no alto da tela.
- Hora: o começo da hora.
- Número ou conta: de onde veio o aviso.
- Recebidos: quantos avisos chegaram naquela hora.
- Com falha: quantos o BotoZap não conseguiu processar. A falha só entra quando o BotoZap desiste de um aviso, depois de tentar de novo por algumas horas, então o número de uma hora que já passou pode subir. Cada aviso com falha também aparece em Logs de API, na origem Webhook Meta.
A contagem é refeita de hora em hora, aos 5 minutos. Até lá, a hora mais recente aparece com parcial: ela só tem os primeiros minutos. Hora sem nenhum aviso não aparece na lista. Os avisos simulados do número de teste (sandbox) não entram na contagem.
Use esta tela para confirmar que a Meta está mandando avisos ao BotoZap. Se os contatos estão escrevendo e, depois dos 5 minutos da hora seguinte, a contagem não subiu, os avisos não estão chegando: fale com o suporte.
Logs de webhook
Configurações › Logs de webhook mostra cada aviso que o BotoZap entregou ou tentou entregar aos seus webhooks:
- Evento: o tipo de aviso, por exemplo uma mensagem recebida ou uma atualização de entrega.
- Canal: o número ou a conta do Instagram de onde veio o aviso. Sem canal é o aviso de teste ou um aviso da conta toda.
- Endpoint: o endereço do seu sistema que devia receber.
- Status:
- Sucesso: o seu sistema recebeu.
- Pendente: ainda vai ser enviado ou está esperando a próxima tentativa.
- Falha: a última tentativa não deu certo. O BotoZap tenta de novo.
- Esgotado: o BotoZap parou de tentar essa entrega.
- Limitada: o aviso passou do limite de repasse do plano Free e não foi enviado.
- HTTP: o código que o seu sistema respondeu.
- Tentativas: quantas vezes o BotoZap tentou.
- Quando: a última tentativa (ou a criação, se ainda não houve tentativa).
Filtre por situação (Todos, Sucesso, Falha, Pendente, Esgotado, Limitada) e por canal (Todos os canais, um número ou conta, ou Sem canal). O filtro busca em todas as entregas guardadas, não só nas 200 da tela: uma entrega com falha de ontem aparece mesmo que o outro canal tenha recebido centenas de avisos depois.
Quando um canal está pausado, aparece um aviso no alto da tela, por exemplo Loja · +55 11 12345-6789: entregas pausadas após 15 falhas seguidas. O link Ver as entregas com falha já abre a lista filtrada por Falha e por esse canal.
Clique numa linha para ver Canal, Última tentativa, Próxima tentativa, Criado em, o Id da entrega, o X-Idempotency-Key (o mesmo valor que o seu sistema recebe no cabeçalho de cada tentativa) e o Payload, que é o conteúdo exato do aviso.
Nas entregas com falha, o BotoZap guarda o começo da resposta que o seu sistema deu (até 4 KB). Ela não aparece na tela nem na API. Se o desenvolvedor precisar dela para achar o erro, peça ao suporte informando o Id da entrega.
Entregas Esgotado podem ser reenviadas em Operação, depois que o sistema de destino estiver funcionando.
Se a tela mostra Nenhuma entrega ainda., ainda não houve aviso para entregar. Cadastre um webhook em Webhooks e use Testar e ativar: o aviso de teste já aparece aqui.
Como ajudar o suporte
Quando algo der errado numa integração, envie ao suporte:
- Quando aconteceu (data e hora do registro).
- Em Logs de API: Método, Path, HTTP, Código da aplicação, Código Meta (síncrono), Resultado da tentativa e Ambiente.
- Em Logs de webhook: Evento, Canal, Endpoint, Status, HTTP, Tentativas e o Id da entrega.
- Se a integração guardou a resposta da API, o código do cabeçalho
x-request-id: toda resposta da API traz esse código, e com ele o suporte acha a chamada. - Se for uma mensagem específica, o ID do WhatsApp que aparece nos detalhes da mensagem em Mensagens. Nas mensagens do Instagram, o campo se chama ID do Instagram.
Atenção: nunca envie a chave de API completa nem o segredo do webhook. Evite também copiar o Payload inteiro: ele traz o conteúdo das mensagens e dados dos contatos. Os códigos acima bastam para o suporte localizar o caso.
O suporte fica em Ajuda › Suporte por e-mail e Ajuda › Suporte no WhatsApp.
Problemas comuns
Aparece "Logs indisponíveis. A falha de consulta não indica ausência de chamadas.", "Logs da Meta indisponíveis agora." ou "Logs de webhook indisponíveis agora." A leitura falhou naquele momento; não quer dizer que nada aconteceu. Atualize a página ou volte em alguns minutos.
A integração recebe 401. A chave não foi enviada, está errada, expirou ou foi revogada. Confira o Status dela em Chaves de API.
A integração recebe 403. A chave funciona, mas não tem a permissão para aquela ação, ou é uma chave de Sandbox tentando algo que só existe em Produção. Abra o detalhe do registro e passe o Código da aplicação ao desenvolvedor.
O registro que procuro não aparece. Logs de API e Logs de webhook mostram só os 200 registros mais recentes; em Logs de webhook, filtre por situação e canal para chegar às entregas mais antigas. Logs da Meta mostra as últimas 48 horas. Para investigar envios de mensagem de um período, cliente ou número específico, use Investigar envios em Operação.
