Em Configurações › SDK, CLI e MCP fica uma página de consulta, com o mesmo título SDK, CLI e MCP, para quem vai integrar outro sistema ao BotoZap. Ela reúne exemplos prontos, o ambiente de testes, os pacotes oficiais e a lista de permissões das chaves. Não há nada para configurar nela.
Você não precisa entender o conteúdo técnico da página. Este artigo explica o que cada parte é, para você conversar com o desenvolvedor e decidir o que liberar.
O que é cada coisa
Tudo aqui usa uma chave de API para entrar no BotoZap. Muda só o jeito de usar:
- API: a porta de entrada do BotoZap para outros sistemas. Qualquer programa que saiba falar com a internet usa a API para mandar mensagens, consultar contatos e assim por diante.
- SDK: um kit pronto para programadores que usam Node.js (uma linguagem muito usada em sites e sistemas). Poupa trabalho de quem escreve a integração.
- CLI: um comando que o desenvolvedor usa na tela preta do computador (o terminal) para operar o BotoZap sem abrir o painel: enviar, listar, investigar.
- MCP: uma forma de conectar assistentes de IA de programação, como Claude Code, Cursor e Codex, ao BotoZap. Com o MCP, o assistente consegue executar ações no BotoZap quando o desenvolvedor pede, dentro do que a chave permitir.
A página mostra a versão atual do SDK, da CLI e do MCP, todos em prévia (0.x). A API continua sendo o caminho principal e estável.
O que tem na página
- Quickstart da API REST: um exemplo de envio da primeira mensagem, que funciona com uma chave de testes.
- Sandbox: teste sem número real e sem custo: como testar sem mandar nada de verdade. A tabela mostra números de telefone especiais que simulam uma entrega completa, uma falha e uma resposta do contato.
- Webhooks: um resumo de como funcionam os avisos automáticos, com os botões Configurar endpoints (abre Webhooks), Auditar entregas (abre Logs de webhook) e Contrato de entrega (at-least-once, DLQ, replay) (abre a documentação técnica). O resumo explica que, depois de muitas falhas seguidas, o webhook é pausado e as entregas ficam guardadas; para reativar, use Testar e ativar em Webhooks. Um teste que dá certo retoma as entregas guardadas.
- SDK Node · CLI · MCP: os três pacotes oficiais com a versão de cada um, a instalação da CLI em CLI em 1 minuto e, em Conecte o servidor MCP, a configuração para Claude Code, Cursor e Codex. Os botões Guia do SDK Node, Push, replay e compatibilidade e Código e exemplos levam à documentação técnica e ao código dos pacotes.
- Segurança e escopos: a lista de todas as permissões que uma chave pode ter.
- Links úteis: atalhos para Chaves de API, Logs e Documentação.
Instagram nas ferramentas de integração
O desenvolvedor pode consultar a conexão do Instagram, refazer a assinatura que recebe os directs e desconectar a conta. A reconexão por login continua no navegador, em Canais.
As ferramentas também gerenciam Regras de comentário, Regras de mensagem, perguntas e menu. Uma Regra de mensagem com link pode ter seu QR baixado para impressão ou compartilhamento. Na CLI, o comando é botozap channel-accounts message-rules qr <conta> <regra> --out qr.png --format png; o arquivo também pode ser SVG.
Consultar a conexão exige numbers:read; reassinar e desconectar exigem numbers:write. Baixar o QR exige message-rules:read. Confira os nomes com o desenvolvedor antes de criar a chave.
IA respondendo comentários
As ferramentas permitem consultar a configuração, escolher o agente publicado, definir o limite diário e ligar ou desligar a IA de comentários. Também mostram os comentários tratados e o motivo de cada decisão. A Regra de comentário continua tendo prioridade sobre a IA.
- SDK:
channelAccounts.getCommentAi,channelAccounts.updateCommentAiechannelAccounts.listCommentAiRuns. - CLI:
botozap channel-accounts comment-ai get <conta>,set <conta>eruns <conta>. Noset, use--enabled true|false,--agent <agente>e--daily-limit <limite>;--agent nulllimpa a seleção. O histórico aceita--pagee--per-page. - MCP completo, com chave de API:
get_instagram_comment_ai,update_instagram_comment_aielist_instagram_comment_ai_runs. Essas ferramentas não aparecem no perfil assistente do ChatGPT.
Consultar exige agents:read; alterar exige agents:write e plano com IA. O limite aceita de 1 a 200 comentários por dia (padrão 50), pelo horário de São Paulo. Campos não enviados são mantidos. Ativar permite respostas públicas e directs automáticos; enviar apenas a opção de desligar continua permitido mesmo sem plano com IA. É necessário usar uma conta real do Instagram, sem Sandbox. Nas conexões por OAuth, a alteração é feita pelo painel.
Usar a lista de permissões
Em Segurança e escopos, cada linha tem três colunas:
- Escopo: o nome técnico que o desenvolvedor usa, por exemplo
messages:send. - Permissão: o nome que aparece ao criar a chave, por exemplo Enviar mensagens.
- O que libera: o que a permissão deixa fazer.
Quando o desenvolvedor pedir "uma chave com contacts:read e messages:send", procure esses nomes na coluna Escopo e marque as permissões correspondentes ao criar a chave em Chaves de API.
Conectar um assistente de IA com segurança
Um assistente conectado pelo MCP faz tudo o que a chave permite. Antes de entregar uma chave para esse uso:
- Comece com uma chave de Sandbox. O assistente pode testar à vontade sem mandar nada para contatos reais.
- Na chave de Produção, marque só as permissões que o assistente precisa. A própria página recomenda isso.
- Dê um nome claro à chave, como "Assistente de IA do fulano", para saber qual revogar depois.
- Se não for mais usar, revogue a chave em Chaves de API.
Atenção: a chave funciona como uma senha. A página lembra que ela deve ficar só no computador de quem usa e nunca ser publicada junto com código.
Problemas comuns
O desenvolvedor pediu uma permissão que não encontro. Procure o nome técnico na coluna Escopo de Segurança e escopos: a coluna Permissão, na mesma linha, mostra o nome que aparece ao criar a chave.
O assistente de IA diz que não tem permissão. A chave não tem a permissão para aquela ação, ou está Expirada ou Revogada. Confira em Chaves de API e, se precisar, crie uma chave nova com a permissão certa.
