> ## Documentation Index > Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt > Use this file to discover all available pages before exploring further. # SKILL for agents > Copy-paste skill for Claude Code, Codex, and any agent that respects the Claude skill format. Once installed the agent uses the CLI without further prompting. ## What it is The SKILL file is a [Claude Code Skill](https://docs.claude.com/) — agent-readable prose that tells the agent **when** to reach for the Zapster CLI, **how** to authenticate, **which** commands to call for each scenario, and **how** to interpret errors. Once installed in the agent's skill directory, the agent has it as permanent context — no prompt explaining the CLI is needed. Works with Claude Code (CLI or IDE), Codex CLI, and any agent that respects the `~/.claude/skills//SKILL.md` convention. ## How to install ```bash theme={null} mkdir -p ~/.claude/skills/zapsterapi-cli ``` Use the "Copy" button on the block further down and save it to `~/.claude/skills/zapsterapi-cli/SKILL.md`. Skills load at startup. The next conversation, the agent already recognizes the Zapster CLI and follows the conventions below automatically. Prerequisite: the CLI must be installed (`npm i -g @zapsterapi/cli`). The skill assumes Node.js 22+ and that the token is in `~/.zapsterapi/credentials` (run `zapsterapi auth login --token ` before first use). ## Skill content ```markdown theme={null} --- 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 [--profile ]`. 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": }` - Failure: `{ "ok": false, "error": { "code": "", "message": "", "hint": "" } }` Branch on `ok`. Never grep stdout text; the table format is for humans. ## Command catalog ### auth | Command | Use when | |---|---| | `zapsterapi auth login --token [--profile ] [--base-url ]` | Persist credentials for a profile. | | `zapsterapi auth logout [--profile ]` | Drop credentials for the active profile. Deletes the file if it was the last profile. | | `zapsterapi auth whoami [--profile ] [--json]` | Verify the active token and print profile/base-url/token-suffix. | ### message | Command | Use when | |---|---| | `zapsterapi message send --recipient --text [--instance-id ] [--send-at ] [--profile ] [--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 [--profile ] [--json]` | Cancel a `scheduled` or `pending` message by ID. Already-sent messages cannot be canceled. | | `zapsterapi message list --from --to [--status ] [--instance-id ] [--recipient ] [--message-id ] [--connection-type ] [--limit ] [--after ] [--profile ] [--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 [--instance-id ] [--profile ] [--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 ] [--lookup-key ] [--page ] [--per-page ] [-q, --query ] [--profile ] [--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 ` on any command, or set `ZAPSTERAPI_PROFILE=`. 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`. ``` ## Next steps * [Agent Quickstart](/en/v1/cli/agent-quickstart) — copy-paste prompt for first-time install automation. * [Command reference](/pt-BR/v1/cli/reference/auth) — flag-by-flag reference (pt-BR).