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 informa que os pacotes do SDK, da CLI e do MCP estão em versão de prévia (0.x) e mostra a versão atual de cada um ao lado do nome. 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.
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.