CLI

Opere a API /v1 do terminal ou de scripts: enviar, listar, configurar e depurar com o comando botozap.

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 --help

Requer 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:

Item1º2º3ºPadrão
Chave--api-keyBOTOZAP_API_KEY~/.botozap/cli/config.jsonnenhuma: erro config_error sem chamar a rede
URL base--api-urlBOTOZAP_API_URL~/.botozap/cli/config.jsonhttps://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 status

botozap 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.

FlagEfeito
--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, --versionMostra a versão.
-h, --helpAjuda 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>.

ComandoSubcomandosEntrada
saved-replies
Respostas salvas compartilhadas; saved_replies:read/write.
list, get, create, update, delete--input-file
inbox-tools
Notas internas, retornos, arquivo e adiamento; inbox:read/write.
get, mutate--input-file
opportunities
Oportunidades do CRM; crm:read/write.
list, get, create, update, activities, conversations, link-conversation, unlink-conversation--input-file
demands
Demandas do CRM; crm:read/write.
list, get, create, update, activities, conversations, link-conversation, unlink-conversation--input-file
radar
Pendências do CRM e critérios por etapa; crm:read/write.
list, stage-rules, stage-rule--input-file
journeys
Ré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
assignments
Atribuições de Conversas a membros da Conta.
list, create, get, update--input-file
appointments
Agenda 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
calendar
Google Calendar autorizado antes em /calendarios no Painel; calendar:read/write.
connections, disconnect, calendars, refresh, select, jobs, retry-job, resolve-conflict--input-file
contact-stages
Etapas do funil por Cliente; contacts:read/write.
list, create, update, delete, reorder--input-file
contact-fields
Campos personalizados da Conta; contacts:read/write.
list, create, update, delete--input-file
messages
Enviar 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, getflags
conversations
Listar 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, deleteflags
contacts
Gerenciar 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-consentflags
media
Ingestão de mídia a partir de uma URL, só no WhatsApp; para enviar mídia, inclusive no Instagram, use messages send-media.
ingestflags
customers
Gerenciar Clientes do workspace.
list, get, create, update, deleteflags
numbers
Nú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-webhooksflags
channel-accounts
Contas 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 syncflags
templates
Templates 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, syncflags
webhooks
Endpoints de webhook, filtro por Cliente e por canal, rotação do secret e teste assinado.
list, get, create, update, delete, testflags
deliveries
Entregas de webhook (webhook_deliveries) e reenvio das esgotadas.
list, replayflags
logs
Logs de requisições à API (api_logs) e os avisos da Meta contados por hora.
list, metaflags
users
Usuários do workspace.
listflags
usage
Custo aproximado da Meta (usage meta-costs [--customer-id] [--from] [--to]); custo ausente sai como "indisponível", nunca 0; customers:read.
meta-costsflags
billing
Plano 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 cancelflags
exports
Exportaçã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, getflags
team-events
Registro de atividades da equipe (list com --since, --until, --actor-id, --action, --target-type e --target-id); team:read, só Administrador.
listflags
login
Explica como criar a chave em /chaves e grava a chave colada no config local.
—flags
config
Lê e grava a configuração local (apiKey, baseUrl).
set, get, path—
status
Confere autenticação e conectividade com GET /phone_numbers?per_page=1.
——
ai
IA 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 json

O 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 JSON

Instagram

messages 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 false

Em 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 png

O 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.