CLI

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.4.0 tem 28 comandos de primeiro nível e 266 subcomandos executáveis, 150 deles no grupo ai.

Instalação

pnpm add --global @botozap/[email protected]
botozap --version

# ou, sem instalar:
pnpm dlx @botozap/[email protected] --help

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

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

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

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

O que a CLI não cobre

A CLI 0.4.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.