OpenWA

Generated OpenWA CLI and agent Skill for WhatsApp sessions, messages, groups, and webhooks.

$ openwa search "send message" --json

CLI binaries 6 platform builds

Skill Included in CLI

Source refs 1 pinned inputs

Smoke intent send message

01 Schema openwa commands schema --json

02 Catalog openwa commands --json

03 Search openwa search "send message" --json

Recipe structure

Files

10 files

builds/openwa.json json

{
  "schema_version": 1,
  "recipe": "openwa",
  "cli_name": "openwa",
  "generated_at": "2026-08-21T06:46:28.971Z",
  "lathe_version": "lathe v0.5.2 (none, unknown)",
  "gate": {
    "verdict": "GO",
    "generated_at": "2026-08-21T06:46:28.971Z",
    "lathe_version": "lathe v0.5.2 (none, unknown)",
    "command_count": 153,
    "group_count": 21,
    "skill_included": true,
    "warnings": []
  },
  "source_refs": [
    {
      "name": "openwa_api",
      "display_name": "openwa_api",
      "backend": "openapi3",
      "repo_url": "https://github.com/rmyndharis/OpenWA",
      "pinned_tag": "v0.10.10",
      "files": [
        "openapi.json"
      ]
    }
  ],
  "outputs": {
    "catalog": null,
    "skill": "skills/openwa",
    "cli_artifacts": [
      {
        "os": "darwin",
        "arch": "arm64",
        "format": "tar.gz",
        "binary": "openwa",
        "path": "downloads/openwa-darwin-arm64.tar.gz",
        "size": 3690900,
        "sha256": "sha256:ac66ba94ad62d1e9017d03038444eb2ea784b026bf2b4275822bf960b0cd8a94"
      },
      {
        "os": "darwin",
        "arch": "amd64",
        "format": "tar.gz",
        "binary": "openwa",
        "path": "downloads/openwa-darwin-amd64.tar.gz",
        "size": 3982777,
        "sha256": "sha256:fea96e5dda3ef6bbb5a433638609323c39e9d6de7f042df90be4933176603bf8"
      },
      {
        "os": "linux",
        "arch": "amd64",
        "format": "tar.gz",
        "binary": "openwa",
        "path": "downloads/openwa-linux-amd64.tar.gz",
        "size": 3919706,
        "sha256": "sha256:cedac4be96285548e9120c5b1aa3277f7335d0484bc0faaf32dce308fbc60353"
      },
      {
        "os": "linux",
        "arch": "arm64",
        "format": "tar.gz",
        "binary": "openwa",
        "path": "downloads/openwa-linux-arm64.tar.gz",
        "size": 3555668,
        "sha256": "sha256:fed56b943dc3a6dab7ae6c633bfa0a2b083d7fbfbb59bb01126de14006c25f68"
      },
      {
        "os": "windows",
        "arch": "amd64",
        "format": "tar.gz",
        "binary": "openwa.exe",
        "path": "downloads/openwa-windows-amd64.tar.gz",
        "size": 4038776,
        "sha256": "sha256:1f5821d6f2f1d1d48601d7e31a85d56751ce12110634d0aec4381efa9e2c6908"
      },
      {
        "os": "windows",
        "arch": "arm64",
        "format": "tar.gz",
        "binary": "openwa.exe",
        "path": "downloads/openwa-windows-arm64.tar.gz",
        "size": 3615063,
        "sha256": "sha256:d8268c83ac7a2bacffd9d990c94957e815517ceb32a520736a94bb6690ba023b"
      }
    ]
  }
}

recipes/openwa/README.md markdown

# OpenWA

This recipe generates the `openwa` CLI and agent Skill for
[OpenWA](https://github.com/rmyndharis/OpenWA) WhatsApp sessions, messages,
groups, contacts, and webhooks.

## API and authentication

Use an administrator API key in the `X-API-Key` header:

```sh
openwa auth login --hostname <host> --auth-type apikey
openwa auth status --hostname <host>
```

The default API-key header is `X-API-Key`. A viewer or session-scoped key cannot
pass the administrator settings check used during login.

## Install the Skill

```sh
openwa skill install --scope user --agent codex --yes
```

## Agent workflow

```sh
openwa commands --json
openwa search "send message" --json
```

Use the returned command path with `openwa commands show` before execution.
Bump the release pin in
`specs/sources.yaml` when upgrading the OpenWA API.

recipes/openwa/cli.yaml yaml

cli:
  name: openwa
  short: "Command-line tool for OpenWA WhatsApp automation"

skill:
  bundle: true

auth:
  validate:
    method: GET
    path: /api/settings
    display:
      username_field: general.apiBaseUrl
      fallback_field: notifications.notificationEmail

recipes/openwa/lathe.yaml yaml

name: openwa
display_name: OpenWA
cli_name: openwa
category: messaging
homepage: https://github.com/rmyndharis/OpenWA
description: Generated OpenWA CLI and agent Skill for WhatsApp sessions, messages, groups, and webhooks.
maintainers:
  - github: samzong
auth:
  type: custom
  notes: >-
    Requires an OpenWA administrator API key in the X-API-Key header. Run
    `openwa auth login --hostname <host> --auth-type apikey` and verify it
    with `openwa auth status --hostname <host>`.
smoke:
  intent: send message
  expect: message-controller-send-audio

recipes/openwa/specs/sources.yaml yaml

sources:
  openwa_api:
    default_hostname: localhost:2785
    repo_url: https://github.com/rmyndharis/OpenWA
    # pinned to release v0.10.10 as of 2026-07-26; bump when upgrading
    pinned_tag: v0.10.10
    backend: openapi3
    openapi3:
      files:
        - openapi.json

skills/openwa/.lathe-skill text

generated by lathe codegen; safe to remove and regenerate

skills/openwa/SKILL.md markdown

---
name: openwa
description: >
  Use when operating the openwa generated CLI. Discover commands, inspect parameters,
  check auth state, and execute API operations safely.
---

# openwa CLI

Use this skill when a user asks you to operate `openwa`, inspect its API commands, or find the right generated command for an API task.

## Workflow

1. Search for candidates with `openwa search "<intent>" --json`; use `--limit` when needed. Search is only candidate discovery.
2. Inspect the exact command with `openwa commands show <path...> --json` before executing an unfamiliar command.
3. If the command detail has `auth.required=true`, run `openwa auth status --hostname <host>` before execution. Use `http.default_hostname` when present unless the user provides `--hostname` or `$OPENWA_HOST`.
4. Execute only after flags, body, auth, HTTP path, and output hints are clear from `commands show`.

## General Commands

- `openwa commands --json`: full generated command catalog.
- `openwa commands --include-hidden --json`: include hidden generated commands.
- `openwa commands show <path...> --json`: source of truth for one command.
- `openwa commands schema --json`: catalog schema version for parser compatibility.
- `openwa search "<intent>" --json`: ranked candidate commands.

## Maintenance Commands

- `openwa --version` or `openwa -v`: print CLI build version.

## References

- Read `references/catalog.md` for the command discovery protocol and catalog field meanings.
- Read `references/modules/openwa-api.md` for the `openwa_api` module command index.

## Rules

- Do not guess flags or request body shape from command names.
- Do not execute directly from search results; confirm with `commands show` first.
- Prefer `-o json` for machine-readable command output unless the user asks for human-readable output.
- Use `--file`, `--set`, or `--set-str` for JSON request bodies according to `commands show` body requirements.
- For sensitive flags, prefer safe modes from `flags[].input_modes`: `--<flag>-env`, `--<flag>-file`, or `--<flag>-stdin`.

skills/openwa/agents/openai.yaml yaml

interface:
  display_name: "openwa CLI"
  short_description: "Use the openwa generated CLI"
  default_prompt: "Use $openwa to find and run the right openwa command."

skills/openwa/references/catalog.md markdown

# Catalog Protocol

Use the runtime catalog as the source of truth. Generated references are a fast index; command execution details come from the CLI itself.

## Search

Run `openwa search "<intent>" --json` to find candidate commands. Use `--limit` to control result count. Treat search output as candidates only.

## Full Catalog

Run `openwa commands --json` to inspect the generated command catalog. Use `--include-hidden` only when hidden commands are relevant.

Key fields:

- `path`: command path to pass to `commands show` or execute after the CLI name.
- `shortcuts`: root-level commands that execute the same operation with preset flag values.
- `http`: HTTP method and path template.
- `http.default_hostname`: optional source-level host selected after explicit `--hostname` and `$OPENWA_HOST`; when present it is used before the single-host fallback from `hosts.yml`.
- `flags`: CLI flags, parameter location, type, required state, defaults, enum values, format, input modes, and help.
- `body`: request body requirement and media type.
- `auth`: whether auth is required and which scopes are declared.
- `examples`: runnable examples with optional body shape, output hints, and follow-up commands.
- `output`: list path, default columns, response media type, pagination, and streaming hints.
- `notes`, `prerequisites`, and `known_errors`: overlay-provided operation context that is not inferred from the API spec.

## Command Detail

Run `openwa commands show <path...> --json` before executing an unfamiliar command. This is the source of truth for flags, body, auth, HTTP path, and output hints.

## Schema

Run `openwa commands schema --json` to read the catalog schema version before parsing catalog JSON with durable tooling.

## Sensitive Flags

When a flag entry has `input_modes`, prefer safe modes over putting secrets directly in shell arguments.

- `flag`: pass the direct `--<flag>` value; keep this for compatibility or non-secret values.
- `env`: pass `--<flag>-env NAME` to read the value from an environment variable.
- `file`: pass `--<flag>-file path` to read the value from a file.
- `stdin`: pass `--<flag>-stdin` to read the value from stdin.
- Use only one input mode for the same flag.

## Request Bodies

- `--file path`: read a JSON body from a file.
- `--file -`: read a JSON body from stdin.
- `--set key.path=value`: build JSON with type inference for booleans, null, integers, and floats.
- `--set-str key.path=value`: build JSON while forcing the value to remain a string.

## Output

Use `-o json` for machine-readable command output. Other supported formats are `table`, `yaml`, and `raw`.

## Auth

If command detail returns `auth.required=true`, run `openwa auth status --hostname <host>` before execution. Use `http.default_hostname` when present unless the user provides `--hostname` or `$OPENWA_HOST`; if no matching host is logged in, stop and ask the user to authenticate.

skills/openwa/references/modules/openwa-api.md markdown

# Module `openwa_api`

## Source

- Backend: `openapi3`
- Default hostname: `localhost:2785`
- Repository: https://github.com/rmyndharis/OpenWA
- Pinned tag: `v0.10.10`
- Files: `openapi.json`
- Resolved SHA: `1109ea7a44008fbf784e2b1e185e5c7986351f94`

## audit

### `openwa openwa_api audit audit-controller-find-all`

- Summary: List audit logs with optional filters
- HTTP: `GET /api/audit`
- Auth: required
- Body: none
- Flags:
  - `--action` (query, one of: api_key_created|api_key_updated|api_key_used|api_key_revoked|api_key_deleted|api_key_auth_failed|session_created|session_started|session_stopped|session_force_killed|session_deleted|session_qr_generated|session_connected|session_disconnected|message_sent|message_failed|webhook_created|webhook_deleted|webhook_triggered|webhook_failed|integration_instance_created|integration_instance_updated|integration_instance_secret_regenerated|integration_instance_deleted|infra_config_saved|infra_restart_requested|infra_data_exported|infra_data_imported|infra_storage_exported|infra_storage_imported): action
  - `--severity` (query, one of: info|warn|error): severity
  - `--session-id` (query): sessionId
  - `--api-key-id` (query): apiKeyId
  - `--limit` (query): limit
  - `--offset` (query): offset
- Output: pagination `offset`

## auth

### `openwa openwa_api auth auth-controller-create`

- Summary: Create a new API key (admin only)
- HTTP: `POST /api/auth/api-keys`
- Auth: required
- Body: required; media type `application/json`
- Flags: none

### `openwa openwa_api auth auth-controller-delete`

- Summary: Delete API key (admin only)
- HTTP: `DELETE /api/auth/api-keys/{id}`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): id

### `openwa openwa_api auth auth-controller-find-all`

- Summary: List all API keys (admin only)
- HTTP: `GET /api/auth/api-keys`
- Auth: required
- Body: none
- Flags: none
- Output: columns `name`, `id`, `createdAt`, `expiresAt`, `isActive`, `keyPrefix`; response media `application/json`

### `openwa openwa_api auth auth-controller-find-one`

- Summary: Get API key details (admin only)
- HTTP: `GET /api/auth/api-keys/{id}`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): id
- Output: list path `allowedIps`; response media `application/json`

### `openwa openwa_api auth auth-controller-revoke`

- Summary: Revoke API key (admin only)
- HTTP: `POST /api/auth/api-keys/{id}/revoke`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): id
- Output: list path `allowedIps`; response media `application/json`

### `openwa openwa_api auth auth-controller-update`

- Summary: Update API key (admin only)
- HTTP: `PUT /api/auth/api-keys/{id}`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): id
- Output: list path `allowedIps`; response media `application/json`

### `openwa openwa_api auth auth-validate-controller-validate`

- Summary: Validate an API key
- HTTP: `POST /api/auth/validate`
- Auth: required
- Body: none
- Flags:
  - `--x-api-key` (header): API key to validate

## calls

### `openwa openwa_api calls call-controller-reject`

- Summary: Reject a ringing incoming call
- HTTP: `POST /api/sessions/{sessionId}/calls/{callId}/reject`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--call-id` (path, required): Call ID from the call.received event

## catalog

### `openwa openwa_api catalog catalog-controller-get-catalog`

- Summary: Get business catalog info (not implemented by any engine)
- HTTP: `GET /api/sessions/{sessionId}/catalog`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): sessionId

### `openwa openwa_api catalog catalog-controller-get-product`

- Summary: Get a specific product (not implemented by any engine)
- HTTP: `GET /api/sessions/{sessionId}/catalog/products/{productId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): sessionId
  - `--product-id` (path, required): productId

### `openwa openwa_api catalog catalog-controller-get-products`

- Summary: List catalog products (not implemented by any engine)
- HTTP: `GET /api/sessions/{sessionId}/catalog/products`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): sessionId
  - `--page` (query): Result page (1-based).
  - `--limit` (query): Page size.
- Output: pagination `offset`

### `openwa openwa_api catalog catalog-controller-send-catalog`

- Summary: Send catalog link (not supported by any engine)
- HTTP: `POST /api/sessions/{sessionId}/messages/send-catalog`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): sessionId

### `openwa openwa_api catalog catalog-controller-send-product`

- Summary: Send a product message (not supported by any engine)
- HTTP: `POST /api/sessions/{sessionId}/messages/send-product`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): sessionId

## channels

### `openwa openwa_api channels channel-controller-find-all`

- Summary: Get all subscribed channels/newsletters
- HTTP: `GET /api/sessions/{sessionId}/channels`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api channels channel-controller-find-one`

- Summary: Get a specific channel by ID
- HTTP: `GET /api/sessions/{sessionId}/channels/{channelId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--channel-id` (path, required): Channel ID

### `openwa openwa_api channels channel-controller-get-messages`

- Summary: Get messages from a channel
- HTTP: `GET /api/sessions/{sessionId}/channels/{channelId}/messages`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--channel-id` (path, required): Channel ID
  - `--limit` (query): Max messages to return (default 50)
- Output: pagination `cursor`

### `openwa openwa_api channels channel-controller-subscribe`

- Summary: Subscribe to a channel using invite code
- HTTP: `POST /api/sessions/{sessionId}/channels/subscribe`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api channels channel-controller-unsubscribe`

- Summary: Unsubscribe from a channel
- HTTP: `DELETE /api/sessions/{sessionId}/channels/{channelId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--channel-id` (path, required): Channel ID to unsubscribe from

## contacts

### `openwa openwa_api contacts contact-controller-block-contact`

- Summary: Block a contact
- HTTP: `POST /api/sessions/{sessionId}/contacts/{contactId}/block`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--contact-id` (path, required): Contact ID (e.g., 628xxx@c.us)

### `openwa openwa_api contacts contact-controller-check-number`

- Summary: Check if a phone number exists on WhatsApp
- HTTP: `GET /api/sessions/{sessionId}/contacts/check/{number}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--number` (path, required): Phone number to check (e.g., 628123456789)

### `openwa openwa_api contacts contact-controller-find-all`

- Summary: Get all contacts for a session
- HTTP: `GET /api/sessions/{sessionId}/contacts`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--limit` (query): Max contacts to return (1–1000, default 1000)
  - `--offset` (query): Number of contacts to skip (for paging)
- Output: pagination `offset`

### `openwa openwa_api contacts contact-controller-find-one`

- Summary: Get a specific contact by ID
- HTTP: `GET /api/sessions/{sessionId}/contacts/{contactId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--contact-id` (path, required): Contact ID (e.g., 628xxx@c.us)

### `openwa openwa_api contacts contact-controller-get-profile-picture`

- Summary: Get profile picture URL for a contact
- HTTP: `GET /api/sessions/{sessionId}/contacts/{contactId}/profile-picture`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--contact-id` (path, required): Contact ID (e.g., 628xxx@c.us)

### `openwa openwa_api contacts contact-controller-get-profile-pictures`

- Summary: Batch-resolve profile picture URLs for up to 50 contacts
- HTTP: `GET /api/sessions/{sessionId}/contacts/profile-pictures`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--ids` (query, required): Comma-separated contact ids (max 50 used)

### `openwa openwa_api contacts contact-controller-resolve-phone`

- Summary: Resolve a contact id (e.g. an @lid) to a phone number — best-effort
- HTTP: `GET /api/sessions/{sessionId}/contacts/{contactId}/phone`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--contact-id` (path, required): Contact ID / JID to resolve (e.g., an @lid)

### `openwa openwa_api contacts contact-controller-unblock-contact`

- Summary: Unblock a contact
- HTTP: `DELETE /api/sessions/{sessionId}/contacts/{contactId}/block`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--contact-id` (path, required): Contact ID (e.g., 628xxx@c.us)

## groups

### `openwa openwa_api groups group-controller-add-participants`

- Summary: Add participants to a group
- HTTP: `POST /api/sessions/{sessionId}/groups/{groupId}/participants`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-create`

- Summary: Create a new group
- HTTP: `POST /api/sessions/{sessionId}/groups`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api groups group-controller-demote-participants`

- Summary: Demote participants from admin
- HTTP: `POST /api/sessions/{sessionId}/groups/{groupId}/participants/demote`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-find-one`

- Summary: Get detailed group info
- HTTP: `GET /api/sessions/{sessionId}/groups/{groupId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID (e.g., 120363xxx@g.us)

### `openwa openwa_api groups group-controller-get-invite-code`

- Summary: Get group invite code/link
- HTTP: `GET /api/sessions/{sessionId}/groups/{groupId}/invite-code`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-get-settings`

- Summary: Get group settings (announce / locked / ephemeral timer)
- HTTP: `GET /api/sessions/{sessionId}/groups/{groupId}/settings`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-join`

- Summary: Join a group via invite code
- HTTP: `POST /api/sessions/{sessionId}/groups/join`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api groups group-controller-leave`

- Summary: Leave a group
- HTTP: `POST /api/sessions/{sessionId}/groups/{groupId}/leave`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-promote-participants`

- Summary: Promote participants to admin
- HTTP: `POST /api/sessions/{sessionId}/groups/{groupId}/participants/promote`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-remove-participants`

- Summary: Remove participants from a group
- HTTP: `DELETE /api/sessions/{sessionId}/groups/{groupId}/participants`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-revoke-invite-code`

- Summary: Revoke group invite code and generate new one
- HTTP: `POST /api/sessions/{sessionId}/groups/{groupId}/invite-code/revoke`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-set-description`

- Summary: Change group description
- HTTP: `PUT /api/sessions/{sessionId}/groups/{groupId}/description`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-set-subject`

- Summary: Change group name/subject
- HTTP: `PUT /api/sessions/{sessionId}/groups/{groupId}/subject`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

### `openwa openwa_api groups group-controller-update-settings`

- Summary: Update group settings (announce / locked / ephemeral timer)
- HTTP: `PUT /api/sessions/{sessionId}/groups/{groupId}/settings`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--group-id` (path, required): Group ID

## health

### `openwa openwa_api health health-controller-check`

- Summary: Basic health check
- HTTP: `GET /api/health`
- Auth: public
- Body: none
- Flags: none

### `openwa openwa_api health health-controller-liveness`

- Summary: Liveness probe for Kubernetes
- HTTP: `GET /api/health/live`
- Auth: public
- Body: none
- Flags: none

### `openwa openwa_api health health-controller-readiness`

- Summary: Readiness probe — verifies the auth/audit + data databases respond
- HTTP: `GET /api/health/ready`
- Auth: public
- Body: none
- Flags: none

## infrastructure

### `openwa openwa_api infrastructure infra-controller-export-data`

- Summary: Export all data from Data DB for migration
- HTTP: `GET /api/infra/export-data`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api infrastructure infra-controller-export-storage`

- Summary: Export all storage files as tar.gz
- HTTP: `GET /api/infra/storage/export`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api infrastructure infra-controller-get-config`

- Summary: Read the saved infrastructure configuration for the dashboard form
- HTTP: `GET /api/infra/config`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api infrastructure infra-controller-get-current-engine`

- Summary: Get current active engine
- HTTP: `GET /api/infra/engines/current`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api infrastructure infra-controller-get-engines`

- Summary: Get available WhatsApp engines
- HTTP: `GET /api/infra/engines`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api infrastructure infra-controller-get-status`

- Summary: Get infrastructure status
- HTTP: `GET /api/infra/status`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api infrastructure infra-controller-get-storage-file-count`

- Summary: Get file count in current storage
- HTTP: `GET /api/infra/storage/files/count`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api infrastructure infra-controller-health-check`

- Summary: Health check endpoint
- HTTP: `GET /api/infra/health`
- Auth: public
- Body: none
- Flags: none

### `openwa openwa_api infrastructure infra-controller-import-data`

- Summary: Import data to Data DB (replaces existing data)
- HTTP: `POST /api/infra/import-data`
- Auth: required
- Body: required; media type `application/json`
- Flags: none

### `openwa openwa_api infrastructure infra-controller-import-storage`

- Summary: Import storage files from tar.gz
- HTTP: `POST /api/infra/storage/import`
- Auth: required
- Body: required; media type `application/json`
- Flags: none

### `openwa openwa_api infrastructure infra-controller-request-restart`

- Summary: Request server restart with Docker orchestration
- HTTP: `POST /api/infra/restart`
- Auth: required
- Body: optional; media type `application/json`
- Flags: none

### `openwa openwa_api infrastructure infra-controller-save-config`

- Summary: Save infrastructure configuration to .env file
- HTTP: `PUT /api/infra/config`
- Auth: required
- Body: required; media type `application/json`
- Flags: none

## integration

### `openwa openwa_api integration ingress-controller-receive-delete`

- Summary: IngressController_receive_delete
- HTTP: `DELETE /api/ingress/{pluginId}/{instanceId}/{path}`
- Auth: public
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId

### `openwa openwa_api integration ingress-controller-receive-get`

- Summary: IngressController_receive_get
- HTTP: `GET /api/ingress/{pluginId}/{instanceId}/{path}`
- Auth: public
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId

### `openwa openwa_api integration ingress-controller-receive-patch`

- Summary: IngressController_receive_patch
- HTTP: `PATCH /api/ingress/{pluginId}/{instanceId}/{path}`
- Auth: public
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId

### `openwa openwa_api integration ingress-controller-receive-post`

- Summary: IngressController_receive_post
- HTTP: `POST /api/ingress/{pluginId}/{instanceId}/{path}`
- Auth: public
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId

### `openwa openwa_api integration ingress-controller-receive-put`

- Summary: IngressController_receive_put
- HTTP: `PUT /api/ingress/{pluginId}/{instanceId}/{path}`
- Auth: public
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId

### `openwa openwa_api integration integration-instance-controller-create`

- Summary: IntegrationInstanceController_create
- HTTP: `POST /api/integration/plugins/{pluginId}/instances`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--plugin-id` (path, required): pluginId

### `openwa openwa_api integration integration-instance-controller-get-one`

- Summary: IntegrationInstanceController_getOne
- HTTP: `GET /api/integration/plugins/{pluginId}/instances/{instanceId}`
- Auth: required
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId
- Output: list path `ingressUrls`; columns `route`, `url`; response media `application/json`

### `openwa openwa_api integration integration-instance-controller-list`

- Summary: IntegrationInstanceController_list
- HTTP: `GET /api/integration/plugins/{pluginId}/instances`
- Auth: required
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
- Output: columns `id`, `createdAt`, `enabled`, `instanceId`, `pluginId`, `secret`; response media `application/json`

### `openwa openwa_api integration integration-instance-controller-patch`

- Summary: IntegrationInstanceController_patch
- HTTP: `PATCH /api/integration/plugins/{pluginId}/instances/{instanceId}`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId
- Output: list path `ingressUrls`; columns `route`, `url`; response media `application/json`

### `openwa openwa_api integration integration-instance-controller-regenerate`

- Summary: IntegrationInstanceController_regenerate
- HTTP: `POST /api/integration/plugins/{pluginId}/instances/{instanceId}/regenerate-secret`
- Auth: required
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId
- Output: list path `ingressUrls`; columns `route`, `url`; response media `application/json`

### `openwa openwa_api integration integration-instance-controller-remove`

- Summary: IntegrationInstanceController_remove
- HTTP: `DELETE /api/integration/plugins/{pluginId}/instances/{instanceId}`
- Auth: required
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId

### `openwa openwa_api integration redrive-controller-redrive-instance`

- Summary: RedriveController_redriveInstance
- HTTP: `POST /api/integration/instances/{pluginId}/{instanceId}/redrive`
- Auth: required
- Body: none
- Flags:
  - `--plugin-id` (path, required): pluginId
  - `--instance-id` (path, required): instanceId

## labels

### `openwa openwa_api labels label-controller-add-label-to-chat`

- Summary: Add a label to a chat
- HTTP: `POST /api/sessions/{sessionId}/labels/chat/{chatId}`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--chat-id` (path, required): Chat ID

### `openwa openwa_api labels label-controller-find-all`

- Summary: Get all labels (WhatsApp Business only)
- HTTP: `GET /api/sessions/{sessionId}/labels`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api labels label-controller-find-one`

- Summary: Get a specific label by ID
- HTTP: `GET /api/sessions/{sessionId}/labels/{labelId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--label-id` (path, required): Label ID

### `openwa openwa_api labels label-controller-get-chat-labels`

- Summary: Get labels for a specific chat
- HTTP: `GET /api/sessions/{sessionId}/labels/chat/{chatId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--chat-id` (path, required): Chat ID

### `openwa openwa_api labels label-controller-remove-label-from-chat`

- Summary: Remove a label from a chat
- HTTP: `DELETE /api/sessions/{sessionId}/labels/chat/{chatId}/{labelId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--chat-id` (path, required): Chat ID
  - `--label-id` (path, required): Label ID to remove

## messages

### `openwa openwa_api messages message-controller-cancel-batch`

- Summary: Cancel a running batch
- HTTP: `POST /api/sessions/{sessionId}/messages/batch/{batchId}/cancel`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--batch-id` (path, required): Batch ID

### `openwa openwa_api messages message-controller-delete-message`

- Summary: Delete a message
- HTTP: `POST /api/sessions/{sessionId}/messages/delete`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-edit`

- Summary: Edit the text of a message sent by this account
- HTTP: `POST /api/sessions/{sessionId}/messages/edit`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
- Output: response media `application/json`

### `openwa openwa_api messages message-controller-forward`

- Summary: Forward a message to another chat
- HTTP: `POST /api/sessions/{sessionId}/messages/forward`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-get-batch-status`

- Summary: Get batch processing status
- HTTP: `GET /api/sessions/{sessionId}/messages/batch/{batchId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--batch-id` (path, required): Batch ID

### `openwa openwa_api messages message-controller-get-chat-history`

- Summary: Fetch chat history live from WhatsApp
- HTTP: `GET /api/sessions/{sessionId}/messages/{chatId}/history`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--chat-id` (path, required): Chat ID (e.g. 1234567890@c.us or groupId@g.us)
  - `--limit` (query): Max messages to return (default 50)
  - `--include-media` (query): When true, downloads media (base64) for messages that have it. Slower; default false.
  - `--deep` (query): When true, raises the limit ceiling from 100 to 2000 for reaching further back in history (whatsapp-web.js only; loads earlier messages on demand). Forces metadata-only (includeMedia is ignored). Large/slow requests may increase WhatsApp rate-limiting risk; default false.
- Output: pagination `cursor`

### `openwa openwa_api messages message-controller-get-messages`

- Summary: Get message history for a session
- HTTP: `GET /api/sessions/{sessionId}/messages`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--chat-id` (query): Filter by chat ID
  - `--from` (query): Filter by sender. A phone also matches messages from a lid that resolves to it.
  - `--limit` (query): Max messages to return (default 50)
  - `--offset` (query): Offset for pagination
- Output: pagination `offset`

### `openwa openwa_api messages message-controller-get-reactions`

- Summary: Get reactions for a specific message
- HTTP: `GET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/reactions`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--chat-id` (path, required): Chat ID containing the message
  - `--message-id` (path, required): Message ID to get reactions for

### `openwa openwa_api messages message-controller-react`

- Summary: Add or remove a reaction to a message
- HTTP: `POST /api/sessions/{sessionId}/messages/react`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-reply`

- Summary: Reply to a message
- HTTP: `POST /api/sessions/{sessionId}/messages/reply`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-audio`

- Summary: Send an audio/voice message
- HTTP: `POST /api/sessions/{sessionId}/messages/send-audio`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-bulk`

- Summary: Send messages to multiple recipients (async batch processing)
- HTTP: `POST /api/sessions/{sessionId}/messages/send-bulk`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-contact`

- Summary: Send a contact card message
- HTTP: `POST /api/sessions/{sessionId}/messages/send-contact`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-document`

- Summary: Send a document/file
- HTTP: `POST /api/sessions/{sessionId}/messages/send-document`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-image`

- Summary: Send an image message
- HTTP: `POST /api/sessions/{sessionId}/messages/send-image`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-location`

- Summary: Send a location message
- HTTP: `POST /api/sessions/{sessionId}/messages/send-location`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-poll`

- Summary: Send a native WhatsApp poll
- HTTP: `POST /api/sessions/{sessionId}/messages/send-poll`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-sticker`

- Summary: Send a sticker message
- HTTP: `POST /api/sessions/{sessionId}/messages/send-sticker`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-template`

- Summary: Render a stored text template and send it as a text message
- HTTP: `POST /api/sessions/{sessionId}/messages/send-template`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-text`

- Summary: Send a text message
- HTTP: `POST /api/sessions/{sessionId}/messages/send-text`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api messages message-controller-send-video`

- Summary: Send a video message
- HTTP: `POST /api/sessions/{sessionId}/messages/send-video`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

## plugins

### `openwa openwa_api plugins plugins-controller-catalog`

- Summary: List the remote plugin catalog, annotated with install state
- HTTP: `GET /api/plugins/catalog`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api plugins plugins-controller-disable`

- Summary: Disable a plugin
- HTTP: `POST /api/plugins/{id}/disable`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): id

### `openwa openwa_api plugins plugins-controller-enable`

- Summary: Enable a plugin
- HTTP: `POST /api/plugins/{id}/enable`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): id

### `openwa openwa_api plugins plugins-controller-find-all`

- Summary: List all plugins
- HTTP: `GET /api/plugins`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api plugins plugins-controller-find-one`

- Summary: Get plugin by ID
- HTTP: `GET /api/plugins/{id}`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): id

### `openwa openwa_api plugins plugins-controller-get-config-ui`

- Summary: Serve a plugin's sandboxed config-UI entry HTML (for an iframe srcdoc)
- HTTP: `GET /api/plugins/{id}/config-ui`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): id

### `openwa openwa_api plugins plugins-controller-health-check`

- Summary: Check plugin health
- HTTP: `GET /api/plugins/{id}/health`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): id

### `openwa openwa_api plugins plugins-controller-install`

- Summary: Install a plugin from an uploaded .zip package
- HTTP: `POST /api/plugins/install`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api plugins plugins-controller-install-from-url`

- Summary: Install a plugin by downloading its .zip from a URL (SSRF-guarded)
- HTTP: `POST /api/plugins/install-url`
- Auth: required
- Body: required; media type `application/json`
- Flags: none

### `openwa openwa_api plugins plugins-controller-uninstall`

- Summary: Uninstall a plugin (removes its files; built-ins are protected)
- HTTP: `DELETE /api/plugins/{id}`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): id

### `openwa openwa_api plugins plugins-controller-update`

- Summary: Update an installed plugin in place from a URL (preserves config + enabled state)
- HTTP: `POST /api/plugins/{id}/update`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): id

### `openwa openwa_api plugins plugins-controller-update-config`

- Summary: Update plugin configuration
- HTTP: `PUT /api/plugins/{id}/config`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): id

### `openwa openwa_api plugins plugins-controller-update-session-config`

- Summary: Set a plugin config override for a specific session (empty = clear it)
- HTTP: `PUT /api/plugins/{id}/config/{sessionId}`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): id
  - `--session-id` (path, required): sessionId

### `openwa openwa_api plugins plugins-controller-update-sessions`

- Summary: Set which sessions a session-scoped plugin is activated for (['*'] = all)
- HTTP: `PUT /api/plugins/{id}/sessions`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): id
- Output: list path `activeSessions`; response media `application/json`

## profile

### `openwa openwa_api profile profile-controller-set-name`

- Summary: Set the account display name
- HTTP: `PUT /api/sessions/{sessionId}/profile/name`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api profile profile-controller-set-picture`

- Summary: Set the account profile picture (URL or base64 image)
- HTTP: `PUT /api/sessions/{sessionId}/profile/picture`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api profile profile-controller-set-status`

- Summary: Set the account about/status text
- HTTP: `PUT /api/sessions/{sessionId}/profile/status`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

## search

### `openwa openwa_api search search-controller-search`

- Summary: Search messages across sessions (active search provider)
- HTTP: `GET /api/search`
- Auth: required
- Body: none
- Flags:
  - `--q` (query, required): Search term (required, non-empty)
  - `--session-id` (query): Restrict to a single session
  - `--chat-id` (query): Restrict to a single chat id
  - `--from` (query): Sender filter
  - `--direction` (query, one of: incoming|outgoing): incoming | outgoing
  - `--type` (query): Message type filter
  - `--date-from` (query): Epoch-ms lower bound (inclusive)
  - `--date-to` (query): Epoch-ms upper bound (inclusive)
  - `--limit` (query): Max hits to return
  - `--offset` (query): Pagination offset
- Output: pagination `offset`

## sessions

### `openwa openwa_api sessions session-controller-create`

- Summary: Create a new WhatsApp session
- HTTP: `POST /api/sessions`
- Auth: required
- Body: required; media type `application/json`
- Flags: none

### `openwa openwa_api sessions session-controller-delete`

- Summary: Delete a session
- HTTP: `DELETE /api/sessions/{id}`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): Session ID

### `openwa openwa_api sessions session-controller-delete-chat`

- Summary: Delete a chat from the chat list (e.g. a group you have left)
- HTTP: `POST /api/sessions/{id}/chats/delete`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): Session ID

### `openwa openwa_api sessions session-controller-find-all`

- Summary: List all sessions
- HTTP: `GET /api/sessions`
- Auth: required
- Body: none
- Flags:
  - `--limit` (query): Max sessions to return (1-1000, default 1000)
  - `--offset` (query): Number of sessions to skip (for paging)
- Output: columns `name`, `id`, `connectedAt`, `createdAt`, `lastActive`, `lastError`; response media `application/json`; pagination `offset`

### `openwa openwa_api sessions session-controller-find-one`

- Summary: Get session by ID
- HTTP: `GET /api/sessions/{id}`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): Session ID
- Output: response media `application/json`

### `openwa openwa_api sessions session-controller-force-kill`

- Summary: Force-kill a stuck session (SIGKILL its wedged engine, then tear it down)
- HTTP: `POST /api/sessions/{id}/force-kill`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): Session ID
- Output: response media `application/json`

### `openwa openwa_api sessions session-controller-get-chats`

- Summary: Get active chats for a session
- HTTP: `GET /api/sessions/{id}/chats`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): Session ID
  - `--limit` (query): Max chats to return (1–1000, default 1000)
  - `--offset` (query): Number of chats to skip (for paging)
- Output: columns `name`, `kind`, `id`, `isGroup`, `lastMessage`, `timestamp`; response media `application/json`; pagination `offset`

### `openwa openwa_api sessions session-controller-get-groups`

- Summary: Get all groups for a session
- HTTP: `GET /api/sessions/{id}/groups`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): Session ID
  - `--limit` (query): Max groups to return (1–1000, default 1000)
  - `--offset` (query): Number of groups to skip (for paging)
- Output: pagination `offset`

### `openwa openwa_api sessions session-controller-get-qr-code`

- Summary: Get QR code for session authentication
- HTTP: `GET /api/sessions/{id}/qr`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): Session ID
- Output: response media `application/json`

### `openwa openwa_api sessions session-controller-get-stats`

- Summary: Get session statistics for multi-session monitoring
- HTTP: `GET /api/sessions/stats/overview`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api sessions session-controller-mark-chat-read`

- Summary: Mark a chat as read/seen
- HTTP: `POST /api/sessions/{id}/chats/read`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): Session ID

### `openwa openwa_api sessions session-controller-mark-chat-unread`

- Summary: Mark a chat as unread
- HTTP: `POST /api/sessions/{id}/chats/unread`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): Session ID

### `openwa openwa_api sessions session-controller-request-pairing-code`

- Summary: Request an 8-char pairing code to link via phone number (alternative to QR)
- HTTP: `POST /api/sessions/{id}/pairing-code`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): Session ID

### `openwa openwa_api sessions session-controller-send-chat-state`

- Summary: Send a typing/recording presence indicator to a chat (or clear it with 'paused')
- HTTP: `POST /api/sessions/{id}/chats/typing`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--id` (path, required): Session ID

### `openwa openwa_api sessions session-controller-start`

- Summary: Start a session and initialize WhatsApp connection
- HTTP: `POST /api/sessions/{id}/start`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): Session ID
- Output: response media `application/json`

### `openwa openwa_api sessions session-controller-stop`

- Summary: Stop a session and disconnect WhatsApp
- HTTP: `POST /api/sessions/{id}/stop`
- Auth: required
- Body: none
- Flags:
  - `--id` (path, required): Session ID
- Output: response media `application/json`

## settings

### `openwa openwa_api settings settings-controller-get`

- Summary: Get application settings
- HTTP: `GET /api/settings`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api settings settings-controller-update`

- Summary: Settings are read-only at runtime (environment-derived)
- HTTP: `PUT /api/settings`
- Auth: required
- Body: none
- Flags: none

## statistics

### `openwa openwa_api statistics stats-controller-get-message-stats`

- Summary: Get message statistics with time series
- HTTP: `GET /api/stats/messages`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api statistics stats-controller-get-overview`

- Summary: Get overall statistics
- HTTP: `GET /api/stats/overview`
- Auth: required
- Body: none
- Flags: none

### `openwa openwa_api statistics stats-controller-get-session-stats`

- Summary: Get statistics for a specific session
- HTTP: `GET /api/stats/sessions/{sessionId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): sessionId

## status

### `openwa openwa_api status status-controller-delete-status`

- Summary: Delete own status
- HTTP: `DELETE /api/sessions/{sessionId}/status/{statusId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): sessionId
  - `--status-id` (path, required): statusId

### `openwa openwa_api status status-controller-get-contact-status`

- Summary: Get status updates from a specific contact
- HTTP: `GET /api/sessions/{sessionId}/status/{contactId}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): sessionId
  - `--contact-id` (path, required): contactId

### `openwa openwa_api status status-controller-get-status-media`

- Summary: Stream a stored status media file
- HTTP: `GET /api/sessions/{sessionId}/status/{statusId}/media`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): sessionId
  - `--status-id` (path, required): statusId

### `openwa openwa_api status status-controller-get-statuses`

- Summary: Get all contact status updates
- HTTP: `GET /api/sessions/{sessionId}/status`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): sessionId

### `openwa openwa_api status status-controller-send-image-status`

- Summary: Post an image status
- HTTP: `POST /api/sessions/{sessionId}/status/send-image`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): sessionId

### `openwa openwa_api status status-controller-send-text-status`

- Summary: Post a text status
- HTTP: `POST /api/sessions/{sessionId}/status/send-text`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): sessionId

### `openwa openwa_api status status-controller-send-video-status`

- Summary: Post a video status
- HTTP: `POST /api/sessions/{sessionId}/status/send-video`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): sessionId

## templates

### `openwa openwa_api templates template-controller-create`

- Summary: Create a message template for the session
- HTTP: `POST /api/sessions/{sessionId}/templates`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api templates template-controller-delete`

- Summary: Delete a template
- HTTP: `DELETE /api/sessions/{sessionId}/templates/{id}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--id` (path, required): Template ID

### `openwa openwa_api templates template-controller-find-by-session`

- Summary: List all templates for a session
- HTTP: `GET /api/sessions/{sessionId}/templates`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
- Output: columns `name`, `id`, `body`, `createdAt`, `footer`, `header`; response media `application/json`

### `openwa openwa_api templates template-controller-find-one`

- Summary: Get a template by ID
- HTTP: `GET /api/sessions/{sessionId}/templates/{id}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--id` (path, required): Template ID
- Output: response media `application/json`

### `openwa openwa_api templates template-controller-update`

- Summary: Update a template
- HTTP: `PUT /api/sessions/{sessionId}/templates/{id}`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--id` (path, required): Template ID
- Output: response media `application/json`

## webhooks

### `openwa openwa_api webhooks webhook-controller-create`

- Summary: Create a webhook for the session
- HTTP: `POST /api/sessions/{sessionId}/webhooks`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID

### `openwa openwa_api webhooks webhook-controller-delete`

- Summary: Delete a webhook
- HTTP: `DELETE /api/sessions/{sessionId}/webhooks/{id}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--id` (path, required): Webhook ID

### `openwa openwa_api webhooks webhook-controller-find-by-session`

- Summary: List all webhooks for a session
- HTTP: `GET /api/sessions/{sessionId}/webhooks`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
- Output: columns `id`, `active`, `createdAt`, `retryCount`, `sessionId`, `updatedAt`; response media `application/json`

### `openwa openwa_api webhooks webhook-controller-find-one`

- Summary: Get a webhook by ID
- HTTP: `GET /api/sessions/{sessionId}/webhooks/{id}`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--id` (path, required): Webhook ID
- Output: list path `events`; response media `application/json`

### `openwa openwa_api webhooks webhook-controller-test`

- Summary: Test a webhook by sending a test payload
- HTTP: `POST /api/sessions/{sessionId}/webhooks/{id}/test`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (path, required): Session ID
  - `--id` (path, required): Webhook ID

### `openwa openwa_api webhooks webhook-controller-update`

- Summary: Update a webhook
- HTTP: `PUT /api/sessions/{sessionId}/webhooks/{id}`
- Auth: required
- Body: required; media type `application/json`
- Flags:
  - `--session-id` (path, required): Session ID
  - `--id` (path, required): Webhook ID
- Output: list path `events`; response media `application/json`

### `openwa openwa_api webhooks webhooks-list-controller-delivery-failures`

- Summary: List recently-failed webhook deliveries (all retries exhausted)
- HTTP: `GET /api/webhooks/delivery-failures`
- Auth: required
- Body: none
- Flags:
  - `--session-id` (query): Filter to a single session
  - `--limit` (query): Max records to return (1-1000, default 1000)
  - `--offset` (query): Number of records to skip (for paging)
- Output: pagination `offset`

### `openwa openwa_api webhooks webhooks-list-controller-find-all`

- Summary: List webhooks visible to the calling key (scoped to its allowed sessions)
- HTTP: `GET /api/webhooks`
- Auth: required
- Body: none
- Flags:
  - `--limit` (query): Max webhooks to return (1-1000, default 1000)
  - `--offset` (query): Number of webhooks to skip (for paging)
- Output: columns `id`, `active`, `createdAt`, `retryCount`, `sessionId`, `updatedAt`; response media `application/json`; pagination `offset`

OpenWA

This recipe generates the openwa CLI and agent Skill for OpenWA WhatsApp sessions, messages, groups, contacts, and webhooks.

API and authentication

Use an administrator API key in the X-API-Key header:

openwa auth login --hostname <host> --auth-type apikey
openwa auth status --hostname <host>

The default API-key header is X-API-Key. A viewer or session-scoped key cannot pass the administrator settings check used during login.

Install the Skill

openwa skill install --scope user --agent codex --yes

Agent workflow

openwa commands --json
openwa search "send message" --json

Use the returned command path with openwa commands show before execution. Bump the release pin in specs/sources.yaml when upgrading the OpenWA API.