SKILL for agents - Zapster API

What it is

The SKILL file is a Claude Code Skill — 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/<name>/SKILL.md convention.

How to install

Create the skill folder

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

Paste the content below into SKILL.md

Use the “Copy” button on the block further down and save it to ~/.claude/skills/zapsterapi-cli/SKILL.md.

Restart the agent or open a new chat

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 <token> before first use).

Skill content

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

Next steps

Agent Quickstart — copy-paste prompt for first-time install automation.
Command reference — flag-by-flag reference (pt-BR).

​What it is

​How to install

​Skill content

​Next steps

What it is

How to install

Skill content

Next steps