SKILL para agentes - Zapster API

O que é

A SKILL é um arquivo no formato Claude Code Skills que descreve, em prosa otimizada para agentes, quando usar a CLI da Zapster, como se autenticar, quais comandos chamar para cada cenário e como interpretar os erros. Quando colada na pasta de skills do agente, ela vira parte do contexto permanente — o agente não precisa mais de prompt explicando como usar a zapsterapi. Funciona com Claude Code (CLI ou IDE), Codex CLI e qualquer agente que respeite o formato ~/.claude/skills/<name>/SKILL.md.

Como instalar

Crie a pasta da skill

mkdir -p ~/.claude/skills/zapsterapi-cli

Cole o conteúdo abaixo no arquivo SKILL.md

Use o botão “Copy” do bloco mais abaixo e salve em ~/.claude/skills/zapsterapi-cli/SKILL.md.

Reinicie o agente ou abra um novo chat

Skills são carregadas no startup. Da próxima conversa, o agente já reconhece a CLI da Zapster e segue as convenções abaixo automaticamente.

Pré-requisito: a CLI precisa estar instalada (npm i -g @zapsterapi/cli). A skill assume Node.js 22+ e que o token está em ~/.zapsterapi/credentials (use zapsterapi auth login --token <token> antes do primeiro uso).

Conteúdo da skill

---
name: zapsterapi-cli
description: Send and schedule WhatsApp messages, cancel and list scheduled messages, check whether a phone number is on WhatsApp, and list instances using the @zapsterapi/cli command-line tool. Use when the user asks to send a WhatsApp message via Zapster, schedule a message for later, cancel a scheduled message, check if a phone number is on WhatsApp, or list Zapster instances from a shell or agent loop.
---

# zapsterapi-cli

## Pre-flight

Run these once per machine, in order:

1. Verify Node.js >= 22: `node --version`. Abort if older.
2. Check install: `zapsterapi --version`. If the binary is missing, install: `npm install -g @zapsterapi/cli`.
3. Authenticate. Ask the user for their token from https://app.zapsterapi.com/tokens. Do NOT echo the token back into chat or logs. Run: `zapsterapi auth login --token <token> [--profile <name>]`. Login validates by calling `GET /v1/wa/instances?per_page=1`; a 401 aborts without persisting.
4. Confirm: `zapsterapi auth whoami --json`. Expect `data.valid: true`.

## Output discipline

Always pass `--json` when parsing programmatically. Every command returns the same envelope:

- Success: `{ "ok": true, "data": <payload> }`
- Failure: `{ "ok": false, "error": { "code": "<slug>", "message": "<human>", "hint": "<optional>" } }`

Branch on `ok`. Never grep stdout text; the table format is for humans.

## Command catalog

### auth

| Command | Use when |
|---|---|
| `zapsterapi auth login --token <token> [--profile <name>] [--base-url <url>]` | Persist credentials for a profile. |
| `zapsterapi auth logout [--profile <name>]` | Drop credentials for the active profile. Deletes the file if it was the last profile. |
| `zapsterapi auth whoami [--profile <name>] [--json]` | Verify the active token and print profile/base-url/token-suffix. |

### message

| Command | Use when |
|---|---|
| `zapsterapi message send --recipient <e164> --text <body> [--instance-id <id>] [--send-at <iso8601>] [--profile <name>] [--json]` | Send a text message now, or schedule for later by passing `--send-at`. `--instance-id` is auto-resolved when exactly one instance is connected. |
| `zapsterapi message cancel <message-id> [--profile <name>] [--json]` | Cancel a `scheduled` or `pending` message by ID. Already-sent messages cannot be canceled. |
| `zapsterapi message list --from <iso8601> --to <iso8601> [--status <pending\|scheduled\|sent\|failed\|canceled>] [--instance-id <id>] [--recipient <e164>] [--message-id <id>] [--connection-type <waba\|unofficial>] [--limit <n>] [--after <cursor>] [--profile <name>] [--json]` | Audit/reconcile messages in a window. Window <= 90 days. Default `--limit` 20, max 100. Page with `--after meta.next_cursor`. |

Send response shapes:

- Immediate (Baileys): `data.kind = "immediate"`, `message_id`, `message_trace_id`.
- Immediate (WABA): `data.kind = "immediate"`, `message_id` (`wamid....`).
- Scheduled: `data.kind = "scheduled"`, `message_id` (`msg_...`), `send_at`, `status: "scheduled"`.

v1 covers text only. For media, buttons, or templates use the REST API.

### recipient

| Command | Use when |
|---|---|
| `zapsterapi recipient fetch --recipient <e164> [--instance-id <id>] [--profile <name>] [--json]` | Check whether a phone number is on WhatsApp before sending. Returns `{ id, lid, is_business, profile_picture }`. Auto-resolves `--instance-id` when exactly one instance is active. A 404 surfaces as `recipient_not_found`. |

### instance

| Command | Use when |
|---|---|
| `zapsterapi instance list [--status <connected\|offline\|disconnected>] [--lookup-key <key>] [--page <n>] [--per-page <n>] [-q, --query <text>] [--profile <name>] [--json]` | Discover instance IDs, filter by status/lookup_key, or search by name. `--per-page` max 100. Create/update/delete are not in v1 — use the REST API. |

## Error code map

| `error.code` | Meaning | Agent action |
|---|---|---|
| `unauthorized` / `invalid_token` | Missing or expired token. | Re-run `auth login`; do not retry blindly. |
| `no_connected_instance` | `--instance-id` omitted and zero instances connected. | Run `instance list --status connected --json`; surface to user if empty. |
| `instance_id_required` | `--instance-id` omitted and >1 connected instance. | Pick one via `instance list` and pass `--instance-id` explicitly. |
| `instance_not_found` | ID does not belong to the account. | Re-list and confirm. |
| `missing_recipient` | `--recipient` empty/absent. | Stop and ask user. |
| `missing_text` | `--text` empty/absent. | Stop and ask user. |
| `invalid_recipient` / `recipient_not_found` | Number is not on WhatsApp. | Verify via `recipient fetch` first. |
| `invalid_send_at` | `--send-at` is not valid ISO 8601. | Reformat (e.g. `2026-05-15T10:00:00Z`). |
| `invalid_button` | Button payload rejected. | Drop to REST API; CLI v1 is text only. |
| `invalid_mentions` | Mentions payload rejected. | Drop to REST API. |
| `from_after_to` | `--from >= --to` on `message list`. | Swap or fix the bounds. |
| `window_too_large` | `message list` window > 90 days. | Page over multiple <=90d windows. |
| `message_not_found` | Cancel target does not exist on this account. | Verify ID; check profile. |
| `message_cannot_cancel` | Message already left `scheduled`/`pending`. | Surface to user; do not retry. |
| `network_error` | Transport-level failure. | Retry with backoff (max 3); then surface. |

## Multi-profile

Pass `--profile <name>` on any command, or set `ZAPSTERAPI_PROFILE=<name>`. Default is `default`. Credentials live in `~/.zapsterapi/credentials`.

## Privacy

Never echo tokens, recipient phone numbers, or message bodies back into the chat or log files. When reporting results, redact (e.g. `5511******999`). Disable telemetry with `ZAPSTERAPI_DISABLE_TELEMETRY=1`.

Próximos passos

Quickstart para agentes — prompt copy-paste pra primeira instalação automatizada.
Referência de comandos — detalhes de flags por comando.
Saída JSON — formato do envelope { ok, data, error }.

​O que é

​Como instalar

​Conteúdo da skill

​Próximos passos

O que é

Como instalar

Conteúdo da skill

Próximos passos