Preview público 0.26.0
@botozap/cli está em preview 0.x, sem promessa de estabilidade de comandos e flags até a 1.0. A API REST é a interface estável: se algo faltar na CLI, chame /api/v1 direto ou use o SDK.
A CLI é uma casca fina sobre o SDK Node: toda chamada de rede passa por ele, com a mesma autenticação e os mesmos códigos de erro. A versão 0.26.0 tem 32 comandos de primeiro nível e 338 subcomandos executáveis, 156 deles no grupo ai.
Instalação
pnpm add --global @botozap/cli@0.26.0
botozap --version
# ou, sem instalar:
pnpm dlx @botozap/cli@0.26.0 --helpRequer Node 22.12 ou superior. Qualquer comando aceita --help, inclusive os subcomandos: botozap appointments services --help.
Autenticação
Crie a chave em /chaves no painel. A CLI envia Authorization: Bearer e resolve a chave e a URL base nesta ordem:
| Item | 1º | 2º | 3º | Padrão |
|---|---|---|---|---|
| Chave | --api-key | BOTOZAP_API_KEY | ~/.botozap/cli/config.json | nenhuma: erro config_error sem chamar a rede |
| URL base | --api-url | BOTOZAP_API_URL | ~/.botozap/cli/config.json | https://botozap.com.br/api/v1 |
# opção 1: variável de ambiente (recomendada em CI e scripts)
export BOTOZAP_API_KEY='bz_live_substitua_por_sua_chave'
# opção 2: gravar no config local (arquivo 0600, diretório 0700)
botozap login # pede a chave sem ecoar no terminal
botozap config set apiKey bz_live_substitua_por_sua_chave
botozap config get # mostra a config com a chave mascarada
botozap config path # ~/.botozap/cli/config.json
botozap statusbotozap login ainda não abre login pelo navegador: ele explica onde criar a chave e grava a chave colada no config local. botozap status faz uma sonda leve em GET /phone_numbers?per_page=1 e mostra a URL base, a origem da chave (flag, env ou config) e o total de Números. Evite --api-key em máquinas compartilhadas: argumentos ficam no histórico do shell e aparecem em ps.
Flags globais
Valem em qualquer posição da linha de comando.
| Flag | Efeito |
|---|---|
--api-key <chave> | Chave de API; sobrepõe env e config. Prefira BOTOZAP_API_KEY ou botozap login: argv fica no histórico do shell. |
--api-url <url> | URL base da API; sobrepõe env e config. |
-o, --output <formato> | human (padrão) ou json. Em json, sucesso vai para stdout e erro para stderr. |
-v, --version | Mostra a versão. |
-h, --help | Ajuda do comando; funciona em qualquer nível. |
Saída e erros
O formato human imprime tabelas e detalhes legíveis. Com -o json, o sucesso vai para stdout como JSON indentado e o erro vai para stderr como { error: { code, message } }, o mesmo envelope da API. Falhas de rede aparecem como network_error. Todo erro sai com código 1.
botozap status -o json
# {
# "ok": true,
# "base_url": "https://botozap.com.br/api/v1",
# "api_key_source": "env",
# "phone_numbers_total": 1
# }Comandos
Os comandos de recursos mais antigos recebem parâmetros por flags. Os mais novos, marcados como --input-file, recebem um arquivo com um objeto JSON de até 256 KiB. O --help de cada um lista os campos obrigatórios do JSON. Ids de rota entram como argumento posicional, por exemplo botozap journeys get <id>.
| Comando | Subcomandos | Entrada |
|---|---|---|
saved-repliesRespostas salvas compartilhadas; saved_replies:read/write. | list, get, create, update, delete | --input-file |
inbox-toolsNotas internas, retornos, arquivo e adiamento; inbox:read/write. | get, mutate | --input-file |
opportunitiesOportunidades do CRM; crm:read/write. | list, get, create, update, activities, conversations, link-conversation, unlink-conversation | --input-file |
demandsDemandas do CRM; crm:read/write. | list, get, create, update, activities, conversations, link-conversation, unlink-conversation | --input-file |
radarPendências do CRM e critérios por etapa; crm:read/write. | list, stage-rules, stage-rule | --input-file |
journeysRéguas e execuções; catalog lista os modelos prontos da galeria e enable-model liga um no Cliente (envia o template à Meta); journeys:read/write, ambiente live. | list, get, create, update, delete, control, runs, enroll, get-run, control-run, catalog, enable-model | --input-file |
assignmentsAtribuições de Conversas a membros da Conta. | list, create, get, update | --input-file |
appointmentsAgenda completa, incluindo serviços, jornadas e exceções; appointments:read/write. | list, get, create, update, delete, history, availability, services list, services create, services update, schedules list, schedules create, schedules update, exceptions list, exceptions create, exceptions update, exceptions delete | --input-file |
calendarGoogle Calendar autorizado antes em /calendarios no Painel; calendar:read/write. | connections, disconnect, calendars, refresh, select, jobs, retry-job, resolve-conflict | --input-file |
contact-stagesEtapas do funil por Cliente; contacts:read/write. | list, create, update, delete, reorder | --input-file |
contact-fieldsCampos personalizados da Conta; contacts:read/write. | list, create, update, delete | --input-file |
messagesEnviar e consultar mensagens de WhatsApp e Instagram: send (--quick-reply/--quick-replies-json só no Instagram), send-media por URL https (--voice manda áudio como mensagem de voz no WhatsApp), send-interactive, send-location e react; --reply-to responde citando (menos em react) e todos aceitam --idempotency-key. | send, send-media, send-interactive, send-location, react, list, get | flags |
conversationsListar Conversas (coluna CANAL, Contato, origem entry_point e hora da última mensagem; filtros --channel e --channel-account-id), alterar status (active | ended), mostrar "digitando…" ao contato (typing) e marcar como lida (read), pedir consentimento (request-consent, WhatsApp e Instagram, só com a janela de 24h aberta), ver os envios que a Meta não confirmou (pending-sends) e dizer se saíram (mark-send --outcome sent|not_sent) e excluir a conversa sem volta (delete, só Administrador, pede confirmação ou --yes). | list, get, update, typing, read, pending-sends, mark-send, request-consent, delete | flags |
contactsGerenciar Contatos; create/update aceitam --display-name e update aceita --clear-display-name. consents lê o consentimento vigente e o histórico; record-consent registra um novo (origem api). delete apaga também a mídia e guarda a recusa só como código cifrado. | list, get, create, update, delete, consents, record-consent | flags |
mediaIngestão de mídia a partir de uma URL, só no WhatsApp; para enviar mídia, inclusive no Instagram, use messages send-media. | ingest | flags |
customersGerenciar Clientes do workspace. | list, get, create, update, delete | flags |
setup-linksLinks de setup de um Cliente, do WhatsApp (Embedded Signup) ou do Instagram (--channel). | list, create, update | flags |
numbersNúmeros de WhatsApp conectados; list mostra nome local e status da conexão, update --label/--clear-label. profile, prompts, qr e blocked leem e gravam na Meta o perfil e a foto, as perguntas prontas e comandos, os QR codes e os contatos bloqueados; numbers:read/write. | list, get, update, health, profile get, profile update, profile photo, prompts get, prompts update, prompts clear, qr list, qr create, qr get, qr update, qr delete, blocked list, blocked block, blocked unblock, history-import get, history-import set, resubscribe-webhooks | flags |
channel-accountsContas de canal (Números do WhatsApp e Contas do Instagram; list com coluna TOKEN e filtros --channel/--customer-id) e conexão, IA de comentários, Regras de comentário/mensagem, QR, perguntas e menu do Instagram; numbers:read/write, agents:read/write, comment-rules:read/write, message-rules:read/write e messenger-profile:read/write. | list, get, comment-rules list, comment-rules get, comment-rules create, comment-rules update, comment-rules delete, comment-rules metrics, connection get, connection resubscribe, connection disconnect, comment-ai get, comment-ai set, comment-ai runs, message-rules list, message-rules get, message-rules create, message-rules update, message-rules delete, message-rules qr, messenger-profile get, messenger-profile update, messenger-profile delete, messenger-profile sync | flags |
templatesTemplates de mensagem; create e update aceitam --opt-out-button para marcar os botões de resposta rápida que são de saída. delete exclui na Meta (--yes fora do terminal) e sync traz o estado da Meta. | list, get, create, update, delete, sync | flags |
webhooksEndpoints de webhook, filtro por Cliente e por canal, rotação do secret e teste assinado. | list, get, create, update, delete, test | flags |
deliveriesEntregas de webhook (webhook_deliveries) e reenvio das esgotadas. | list, replay | flags |
logsLogs de requisições à API (api_logs) e os avisos da Meta contados por hora. | list, meta | flags |
usersUsuários do workspace. | list | flags |
usageCusto aproximado da Meta (usage meta-costs [--customer-id] [--from] [--to]); custo ausente sai como "indisponível", nunca 0; customers:read. | meta-costs | flags |
billingPlano da Conta, slots adicionais (R$ 47/mês por negócio a mais) e garantia de 7 dias; billing:read/write, só chave de API. | slots create, slots cancel | flags |
exportsExportação de dados da Conta ou de um Cliente (create [--customer-id] [--format], list, get com o link de download); exports:read/write, só chave de API. | create, list, get | flags |
team-eventsRegistro de atividades da equipe (list com --since, --until, --actor-id, --action, --target-type e --target-id); team:read, só Administrador. | list | flags |
loginExplica como criar a chave em /chaves e grava a chave colada no config local. | — | flags |
configLê e grava a configuração local (apiKey, baseUrl). | set, get, path | — |
statusConfere autenticação e conectividade com GET /phone_numbers?per_page=1. | — | — |
aiIA BYOK: conversation-control e um subcomando por operação (botozap ai <grupo> <operação>); agents:read/write. | conversation-control e os grupos agents, credentials, providers, executions, knowledge, memory, skills, followup-flows, followups, routers, cases, alerts, notices, proposals, usage, uploads, files, commercial-proposals, eligibility, inferences, operator, evolution, style-adjustments. Veja Agente de IA. | --input-file |
No grupo ai, os uploads (ai knowledge upload, até 20 MiB, e ai skills import-zip, até 5 MiB) leem o arquivo local indicado em file_path no JSON. A CLI confere o tamanho antes do envio.
Exemplos
botozap numbers list
botozap numbers update <id> --label "Loja Centro" # --clear-label remove
botozap usage meta-costs --from 2026-09-01 --to 2026-09-24
botozap messages send --to 5531988887777 --text "Olá!"
botozap messages list --direction inbound --limit 20 -o json
botozap webhooks create \
--url https://seu-dominio.example/webhooks/botozap \
--events messages \
--customer-id <uuid-do-cliente> # opcional: só as entregas desse Cliente
botozap webhooks test <webhook_id>
botozap webhooks update <webhook_id> --secret <novo-secret> # rotaciona
botozap webhooks update <webhook_id> --clear-customer # toda a Conta
botozap deliveries list -o jsonO Endpoint criado nasce sem verificação e só recebe Eventos reais depois que webhooks test recebe 2xx. --customer-id (em create e update) limita as entregas a um Cliente da Conta; --clear-customer remove o filtro, e as duas flags não se combinam. webhooks update --secret rotaciona o secret de assinatura (16 a 256 caracteres); o valor novo não volta na resposta. O fluxo completo está em Webhooks, incluindo como rotacionar sem perder entregas.
cat > filtro.json <<'JSON'
{ "customer_id": "<uuid-do-cliente>", "status": "open" }
JSON
botozap opportunities list --input-file filtro.json -o json
botozap opportunities create --help # mostra os campos obrigatórios do JSONmessages send e messages send-media mandam direct quando o --to é o IGSID do contato; com mais de uma conta do Instagram ativa, informe --from (id da conta na Meta ou UUID da Conta de canal). --quick-reply título=payload (até 13 vezes) e --quick-replies-json só valem no Instagram. No Instagram o recibo mostra channel e external_id (o mid da Meta) no lugar do wamid. media ingest é só do WhatsApp: no Instagram a mídia sai por link, com messages send-media. Regras do canal em Enviar para o Instagram.
botozap channel-accounts list --channel instagram # coluna TOKEN: saúde da conexão
botozap conversations list --channel instagram
botozap messages send --to <igsid> --text "Qual tamanho?" \
--quick-reply "P=TAM_P" --quick-reply "M=TAM_M"
botozap messages send-media --to <igsid> --type image --link https://cdn.exemplo.com/foto.jpg
botozap channel-accounts comment-rules create <channel_account_id> \
--keyword quero --dm-text "Oi! Te mandei o link por aqui."Para a IA de comentários, use comment-ai get para consultar a prontidão e comment-ai runs para ver decisões e envios. Ambos exigem agents:read. O comando comment-ai set exige agents:write e plano com IA, salvo quando só desliga. Informe ao menos um campo; os omitidos são preservados. --agent null limpa a seleção e --daily-limit aceita inteiros de 1 a 200, no fuso America/Sao_Paulo. Sem sandbox; no OAuth, a alteração é exclusiva do painel. Ativar permite respostas públicas e DMs automáticas.
botozap channel-accounts comment-ai get "$CANAL"
botozap channel-accounts comment-ai set "$CANAL" --agent "$AGENTE" --daily-limit 50
# Depois de conferir a prontidão, ativar permite respostas públicas e DMs:
# botozap channel-accounts comment-ai set "$CANAL" --enabled true
botozap channel-accounts comment-ai runs "$CANAL" --page 1 --per-page 20
# Só desligar continua permitido mesmo sem plano com IA:
botozap channel-accounts comment-ai set "$CANAL" --enabled falseEm channel-accounts, use connection get para consultar o diagnóstico, connection resubscribe para reassinar e connection disconnect para desconectar. As operações de conexão não aceitam sandbox. message-rules gerencia Regras de mensagem e messenger-profile gerencia perguntas e menu. Para baixar o QR de uma regra com link:
botozap channel-accounts message-rules qr "$CANAL" "$REGRA" --out qr.png --format pngO QR exige --out; --format aceita png ou svg. Nas Regras de comentário, --live true|false seleciona lives. Ambos os tipos de regra aceitam --require-follow true|false, --non-follower-text e --clear-non-follower-text. Nas listagens de contatos e conversas, --follows-business true|false filtra quem segue a conta.
O que a CLI não cobre
A CLI 0.26.0 cobre um subconjunto do SDK. Não há comando para:
broadcasts: transmissões.events: replay de Eventos (GET /events).conversations reply / agent-control: use messages send; o controle do agente está em ai conversation-control.numbers delete: remoção de Número.media get: leitura de mídia recebida.
Para esses casos, use o SDK ou a API /v1. Para agentes, o MCP oferece reply_to_conversation e control_conversation_agent.
