Navegar na CentralSDK, CLI e MCP

SDK, CLI e MCP

Saiba o que a página SDK, CLI e MCP oferece para quem integra, o que é cada ferramenta e como conectar um assistente de IA com segurança.

Atualizado em

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.updateCommentAi e channelAccounts.listCommentAiRuns.
  • CLI: botozap channel-accounts comment-ai get <conta>, set <conta> e runs <conta>. No set, use --enabled true|false, --agent <agente> e --daily-limit <limite>; --agent null limpa a seleção. O histórico aceita --page e --per-page.
  • MCP completo, com chave de API: get_instagram_comment_ai, update_instagram_comment_ai e list_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:

  1. Comece com uma chave de Sandbox. O assistente pode testar à vontade sem mandar nada para contatos reais.
  2. Na chave de Produção, marque só as permissões que o assistente precisa. A própria página recomenda isso.
  3. Dê um nome claro à chave, como "Assistente de IA do fulano", para saber qual revogar depois.
  4. 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.