{ "openapi": "3.1.0", "info": { "title": "wuapi API", "version": "0.1.0", "summary": "Secure, fast and scalable WhatsApp API for developers.", "description": "wuapi links your own WhatsApp numbers as linked devices (by QR code or pairing code, the same way WhatsApp Web works) and lets you send and receive messages, manage chats, contacts, groups, communities and channels over REST and webhooks. Platforms can isolate each of their customers in a project.\n\n**How it works.** wuapi is an independent service. It is not affiliated with, endorsed or sponsored by WhatsApp, and it does not use the official WhatsApp Business Platform. WhatsApp can restrict or ban numbers that behave like spam; you are responsible for having your recipients' consent and for following WhatsApp's terms.\n\n**Conventions.**\n- Authenticate with `Authorization: Bearer wu_live_...`. Organization keys reach the whole organization; project keys reach one project. `Wuapi-Project` scopes an organization key to one project.\n- Every resource carries `object` (its type) and is returned as is, never wrapped. Every list is `{object: \"list\", items, nextCursor}`: `?limit` (1-100, default 50) and `?cursor`; `nextCursor` is `null` on the last page. Lists read live from WhatsApp page the same way.\n- Fields are camelCase, enum values snake_case. Timestamps are ISO 8601 UTC strings named `...At`; durations and sizes carry their unit (`durationSeconds`, `proxyBytes`); money is integer cents (`...Cents`) with `currency`.\n- Contacts are E.164 numbers with `+` (`+584241112233`), or `lid:` when WhatsApp hides the number. Groups are `...@g.us`, channels `...@newsletter`, the account's stories `stories`.\n- Every `POST` accepts `Idempotency-Key`: the first 2xx response is replayed for 24 hours with `Idempotent-Replayed: true` and `Original-Request` (the `x-request-id` of the request that produced it).\n- Every response carries `x-request-id` and `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`. The limit is 600 requests per minute per API key; over it, `429 rate_limited` with `Retry-After` in seconds. WhatsApp's own pacing also answers `429 rate_limited`.\n- An organization without a paid subscription is on the Free plan, with no card: 1 connected account, 2,000 messages (sent and received together) and 0.5 GB of proxy traffic per calendar month (UTC), with sends, webhooks and every engine-backed call working. When a limit is reached its accounts pause (`disconnectReason: free_limit_reached`) and sends, new accounts and reconnects answer `402 free_limit_reached` until the month ends or the organization upgrades. A second account answers `402 upgrade_required`.\n- Errors always have the shape `{code, message, details?}`:\n\n| Status | Code | When |\n|---|---|---|\n| 400 | `invalid_request` | The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one. |\n| 400 | `not_supported` | WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events, the bot directory or link resolution where WhatsApp does not offer them. |\n| 400 | `not_on_whatsapp` | The recipient has no WhatsApp. |\n| 400 | `username_not_supported` | A WhatsApp username (`@handle`) that cannot be used: `to` names a username this account has no chat with, or a field that takes contact ids got one. WhatsApp does not let a linked device look up usernames. |\n| 400 | `unsupported_proxy_location` | `proxyLocation` names a country or city that is not in `GET /v1/proxy-locations`. |\n| 401 | `unauthorized` | The API key is missing, malformed or revoked. |\n| 402 | `subscription_required` | A new account or invitation while the subscription is past due. `details.billingUrl` links to Billing. |\n| 402 | `upgrade_required` | The Free plan includes 1 connected account: a second account, invitation or reconnect that would take another slot, or a send from a Free organization with more than 1 billable account (after a paid subscription ended). `details.maxAccounts`, `details.upgradeUrl`, and `details.accountId` when the account holding the slot is still linking. |\n| 402 | `free_limit_reached` | The Free plan's monthly limit is reached (2,000 messages sent and received, or 0.5 GB of proxy traffic). Sends, new accounts and reconnects are refused until the month ends (UTC) or the organization upgrades. `details.limit` (`messages` or `proxy`), `details.month`, `details.resetsAt`, `details.upgradeUrl`. |\n| 402 | `addon_required` | `hideWuapiBranding: true` needs the White label add-on ($100/month on the usage subscription). |\n| 402 | `trial_proxy_limit_reached` | Legacy free trials only: a send after the trial's 0.5 GB of proxy traffic is used up, until the trial ends. `details.upgradeUrl` links to Billing. |\n| 402 | `payment_required` | Proxy traffic is paused because an invoice is unpaid (a failed charge, a payment waiting on 3D Secure, or a past-due subscription). Sends and new sessions are refused until it is paid; the organization's accounts show `disconnectReason: proxy_paused` and reconnect on their own once it is. `details.billingUrl` links to Billing. |\n| 402 | `proxy_spend_cap_reached` | Proxy traffic is paused because this month's proxy overage reached the organization's monthly spend cap (set in Billing, $50 by default). Sends and new sessions are refused until the cap is raised or the month ends (UTC); the accounts show `disconnectReason: proxy_paused` and reconnect on their own. `details.capCents` has the cap, `details.billingUrl` links to Billing. |\n| 403 | `forbidden` | The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route. |\n| 403 | `project_suspended` | The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed. |\n| 403 | `project_limit_reached` | The project already has `maxAccounts` accounts. |\n| 403 | `trial_account_limit` | Legacy free trials only: a second account while the trial runs. `details.upgradeUrl` links to Billing. |\n| 403 | `whatsapp_forbidden` | WhatsApp refused: the account is not a member, not an admin, or not allowed. |\n| 404 | `not_found` | The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403. |\n| 404 | `project_not_found` | No live project in this organization matches `Wuapi-Project` or the `projectId` given. |\n| 404 | `group_not_found` | WhatsApp does not know the group. |\n| 404 | `channel_not_found` | WhatsApp does not know the channel. |\n| 404 | `invite_not_found` | The invite code was revoked or does not exist. |\n| 404 | `picture_not_found` | The contact or group has no picture this account can see. |\n| 404 | `business_profile_not_found` | The contact is not a WhatsApp Business account. |\n| 404 | `link_not_found` | WhatsApp does not know the link. |\n| 404 | `sticker_pack_not_found` | WhatsApp does not know the sticker pack. |\n| 404 | `order_not_found` | WhatsApp does not know the order, or the token does not match. |\n| 404 | `whatsapp_not_found` | WhatsApp does not know the target. |\n| 409 | `account_not_ready` | The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it. An account reconnecting on its own is waited for a few seconds first; if it is still reconnecting, the answer carries `Retry-After` and `details.reconnecting: true`. |\n| 409 | `already_linked` | The account is already linked, so there is nothing to pair. |\n| 409 | `already_completed` | The invitation is completed, so it cannot be cancelled or resent. |\n| 409 | `already_exists` | A project with this `externalId` already exists (`details.projectId`). |\n| 409 | `idempotency_conflict` | The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body. |\n| 409 | `message_sending` | `DELETE` or `PATCH` of a queued message while it is being handed to WhatsApp. Retry in a few seconds. |\n| 429 | `rate_limited` | 600 requests per minute per API key, WhatsApp is pacing this account, or the account's `proxyLocation` changed less than 10 minutes ago. Wait `Retry-After` seconds. |\n| 500 | `internal_error` | Something failed unexpectedly. |\n| 502 | `whatsapp_error` | WhatsApp failed the operation. Retrying may work. |\n| 503 | `engine_unavailable` | The WhatsApp engine is unreachable. Retry shortly. |", "license": { "name": "Proprietary", "url": "https://wuapi.dev/terms" }, "contact": { "name": "wuapi support", "url": "https://wuapi.dev/support" } }, "servers": [ { "url": "https://api.wuapi.dev", "description": "Production." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Me", "description": "The organization, API key and project behind the current request." }, { "name": "Accounts", "description": "An account is one WhatsApp number linked as a device, by QR code or by pairing code. Create one, show `qrCodeUrl` to the phone owner or have them type `pairingCode`, and wait for `ready`. Routes under `/v1/accounts/{accountId}` that talk to WhatsApp need the account `ready` (otherwise `409 account_not_ready`).\n\nAn account is billable once it has finished linking (`linkedAt` is set), until it is deleted or logged out." }, { "name": "Proxy locations", "description": "The countries and cities an account's residential proxy can be placed in: the values `proxyLocation` accepts on `POST /v1/accounts`." }, { "name": "Messages", "description": "Send messages to contacts, groups and channels, and read, edit, react to, star and delete them." }, { "name": "Chats", "description": "Read receipts, typing indicators, archive, pin, mute, unread badges, deletion and disappearing messages. `{chatId}` is a contact id, a group id or a channel id." }, { "name": "Stories", "description": "WhatsApp Status posts. A story is stored as a message whose `chatId` is `stories`." }, { "name": "Contacts", "description": "Check numbers, look up contacts, read pictures and business profiles, block and unblock, contact links and presence subscriptions." }, { "name": "Profile", "description": "The linked number's own About text, display name and picture." }, { "name": "Privacy", "description": "The linked number's privacy settings." }, { "name": "Groups", "description": "WhatsApp groups the account belongs to, read live from WhatsApp." }, { "name": "Communities", "description": "Communities and the groups linked to them. Create one with `POST .../groups` and `community: true`." }, { "name": "Channels", "description": "WhatsApp channels: follow, read, react. Post with `POST /v1/messages` and `to` set to the channel id." }, { "name": "Calls", "description": "Reject incoming calls. Automatic rejection is a setting on the account (`PATCH /v1/accounts/{accountId}`)." }, { "name": "Sticker packs", "description": "WhatsApp sticker packs, read live from WhatsApp." }, { "name": "Orders", "description": "Catalog orders contacts send as messages, read live from WhatsApp." }, { "name": "Labels", "description": "WhatsApp Business labels. Consumer accounts answer `400 not_supported`." }, { "name": "Projects", "description": "For platforms that resell wuapi: each of your customers is a project with its own accounts, keys, webhook endpoints and usage, isolated from the others. Manage projects with an organization key; act inside one with a project key or the `Wuapi-Project` header." }, { "name": "Invitations", "description": "A hosted page you send to someone else, your customer, a store manager or a sales rep, so they link their own WhatsApp into one of your projects without an account, a dashboard or an API key. The page is public at `https://wuapi.dev/invite/{token}`, `noindex`, and shows nothing about your other projects, accounts or invitations." }, { "name": "Branding", "description": "What the invitation page and email show: your name, logo, accent color, support link, and whether the wuapi footer appears (hiding it needs the White label add-on)." }, { "name": "Webhooks", "description": "wuapi sends events to your webhook endpoints as `POST` requests with a JSON body (schema `Event`):\n\n`{id, object: \"event\", type, createdAt, organizationId, projectId, data: {object, previousAttributes?}}`\n\n`data.object` is the full resource in the same shape the REST API returns, or the event object named below. `data.previousAttributes` is set on `message.edited` (`{text}`) and `invitation.status_changed` (`{status}`).\n\n**Events** (`WebhookEventType`):\n\n| Events | When | `data.object` |\n|---|---|---|\n| `account.qr_code_issued`, `account.pairing_code_issued`, `account.connected`, `account.disconnected`, `account.failed` | Fired on real transitions: `account.qr_code_issued` when the account enters `qr_ready` (not on each QR rotation; poll the account for the current `qrCodeUrl`), `account.pairing_code_issued` when a new pairing code is issued, `account.disconnected` when the account loses its connection: at once when it does not recover on its own (`disconnectReason` `logged_out`, for example), or, for a drop the session reconnects from by itself, only if it is not `ready` again within a short reconnect grace (currently 20 seconds; `status` may then read `initializing` or `authenticating` while it keeps retrying), so a quick reconnect fires neither this nor `account.connected`; `account.connected` on `ready` (the first link, or back after `account.disconnected`), `account.failed` on `failed`. Deleting an account fires nothing. | `account` |\n| `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`, `message.deleted` | `message.sent` also fires for messages sent from the phone (`source: phone`) and for stories and channel posts. `message.deleted` carries the row with `deletedAt` set and the content cleared. | `message` |\n| `message.edited` | A message was edited. `previousAttributes.text` is the text before. | `message` |\n| `poll.voted` | Someone voted in a poll. | `poll_vote` |\n| `group.joined` | The account joined or created a group. | `group` |\n| `group.updated` | A group changed. | `group_change` |\n| `group.join_requested`, `group.join_request_revoked` | Someone asked to join a group that needs approval, or withdrew the request. | `group_join_request` |\n| `chat.updated` | A chat was archived, pinned, muted, marked read, deleted, cleared or a message starred, on the phone or another device. Live changes only; the initial full sync is not replayed. | `chat_change` |\n| `chat.presence_updated` | A contact is typing or recording in a chat. | `chat_presence` |\n| `contact.presence_updated` | A subscribed contact came online or went offline. Subscribe with `POST .../contacts/{contactId}/subscribe-presence`. | `contact_presence` |\n| `contact.picture_updated` | A contact or group picture changed or was removed. | `picture_change` |\n| `contact.updated` | A contact changed their About text. Fields WhatsApp did not send are `null`. | `contact` |\n| `blocklist.updated` | The blocklist changed. | `blocklist_change` |\n| `label.updated` | A label was edited or (un)assigned to a chat or message. The full sync replays labels this way, which is how the label list arrives. | `label_change` |\n| `call.received`, `call.ended` | `call.received` on an incoming call (reject it with `POST .../calls/{callId}/reject`), `call.ended` when it ends or is rejected. | `call` |\n| `channel.message_received`, `channel.message_updated` | A new message in a followed channel, or new views and reactions on one. Not stored. | `channel_message` |\n| `channel.updated` | The account followed, unfollowed, muted or unmuted a channel. | `channel_change` |\n| `history.synced` | A part of the history the phone sent after linking was stored. Only for accounts with `historySync: recent`: history import is off by default. | `history_sync` |\n| `project.created`, `project.updated`, `project.deleted` | `project.deleted` fires when the background purge finishes. | `project` |\n| `invitation.status_changed` | An invitation changed status (started, completed, failed, cancelled, resent). `url` is `null`. `expired` has no event. `previousAttributes.status` is the status before. | `invitation` |\n\nEverything beyond account, message and group joined/updated events needs the engine's extended events, which the hosted service turns on.\n\n**Projects.** Every event carries `projectId` (`null` when unassigned). An organization endpoint receives every project's events; a project endpoint receives only its project's.\n\n**Signature.** Every request carries `Wuapi-Signature: t=,v1=`, where `v1` is the HMAC-SHA256 of `\".\"` keyed with the endpoint's `secret` (`whsec_...`). Recompute it over the raw body, compare in constant time, and reject timestamps more than 5 minutes from your clock. The TypeScript SDK exports `verifyWebhook(rawBody, header, secret)`. Requests also carry `Wuapi-Event-Id` and `Wuapi-Event-Type`.\n\n**Delivery.** A 2xx within 10 seconds counts as delivered; redirects are not followed. Anything else is retried after 30s, 2m, 10m, 1h and 6h (6 attempts), then dropped. Events can arrive more than once and out of order: deduplicate on `id`." }, { "name": "Usage", "description": "Billable usage, and the per-project export for rebilling." } ], "paths": { "/v1/me": { "get": { "tags": [ "Me" ], "operationId": "getMe", "summary": "Get the current key", "description": "The organization, the API key and, when the request is scoped to a project, that project.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The request's context.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthContext" }, "example": { "object": "auth_context", "organization": { "object": "organization", "id": "w82t6y1u5i9o3p7a2s6d0f4g8h2j6k1l", "name": "Acme" }, "apiKey": { "object": "api_key", "id": "j48c2d5e8f1g4h7i0k3l6m9n2p5q8r1s", "name": "Production", "projectId": null, "keyPrefix": "wu_live_9c9c", "last4": "9c9c", "createdAt": "2026-09-24T08:15:40.000Z", "lastUsedAt": null, "revokedAt": null }, "project": { "object": "project", "id": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "name": "Northwind Dental", "externalId": "customer_8812", "metadata": { "plan": "growth" }, "status": "active", "maxAccounts": 3, "accountCount": 1, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "operationId": "getUsage", "summary": "Get usage", "description": "Billable usage for the current calendar month (UTC). Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "responses": { "200": { "description": "The usage.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "example": { "object": "usage", "period": { "startsAt": "2026-09-01T00:00:00.000Z", "endsAt": "2026-10-01T00:00:00.000Z" }, "currency": "usd", "billableAccountCount": 4, "accountUnitPriceCents": 450, "accountFeeCents": 1950, "proxyBytes": 5368709120, "includedProxyBytes": 2147483648, "billableProxyBytes": 3221225472, "proxyFeeCents": 297, "totalCents": 2247 } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/usage/by-project": { "get": { "tags": [ "Usage" ], "operationId": "getUsageByProject", "summary": "Get usage by project", "description": "The rebilling export for `month` (default the current month): one line per project, plus unassigned resources and totals. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "parameters": [ { "$ref": "#/components/parameters/Month" } ], "responses": { "200": { "description": "The report.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageReport" }, "example": { "object": "usage_report", "period": { "startsAt": "2026-09-01T00:00:00.000Z", "endsAt": "2026-10-01T00:00:00.000Z" }, "projects": [ { "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "externalId": "customer_8812", "name": "Northwind Dental", "billableAccountCount": 1, "accountCount": 1, "proxyBytes": 52428800, "sentMessageCount": 812, "receivedMessageCount": 1290 } ], "unassigned": { "billableAccountCount": 2, "accountCount": 2, "proxyBytes": 10485760, "sentMessageCount": 40, "receivedMessageCount": 51 }, "totals": { "billableAccountCount": 3, "accountCount": 3, "proxyBytes": 62914560, "sentMessageCount": 852, "receivedMessageCount": 1341 } } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/proxy-locations": { "get": { "tags": [ "Proxy locations" ], "operationId": "listProxyLocations", "summary": "List proxy locations", "description": "The catalog of supported `{country, city}` pairs for `proxyLocation`, ordered by country name, then by city population, largest first. Filter with `country`, or search with `q`.\n\nWith `q`, results are ranked instead: an exact match first, then a prefix (`bogo` finds Bogotá), then a later word (`york` finds New York City), then text anywhere in the name; ties go to the bigger city. `q` matches the city name, the city code, the country name and the ISO code (`cl` returns Chile's cities first), ignoring case and accents (`sao` finds São Paulo). It combines with `country`, and pages like any list.", "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Only this country (ISO 3166-1 alpha-2).", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "example": "CL" }, { "name": "q", "in": "query", "required": false, "description": "Search text: city name, city code, country name or ISO code. Case and accents are ignored.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "bogo" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of proxy locations.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyLocationItemList" }, "examples": { "catalog": { "summary": "GET /v1/proxy-locations?country=CL", "value": { "object": "list", "items": [ { "object": "proxy_location", "country": "CL", "countryName": "Chile", "city": "santiago", "cityName": "Santiago" } ], "nextCursor": null } }, "search": { "summary": "GET /v1/proxy-locations?q=bogo", "value": { "object": "list", "items": [ { "object": "proxy_location", "country": "CO", "countryName": "Colombia", "city": "bogotá", "cityName": "Bogotá" }, { "object": "proxy_location", "country": "ID", "countryName": "Indonesia", "city": "bogor", "cityName": "Bogor" } ], "nextCursor": null } } } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/accounts": { "get": { "tags": [ "Accounts" ], "operationId": "listAccounts", "summary": "List accounts", "description": "Accounts in scope, newest first. Deleted accounts are not listed.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/ProjectFilter" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of accounts.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountList" }, "example": { "object": "list", "items": [ { "object": "account", "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "projectId": null, "name": "Support line", "status": "ready", "reconnecting": false, "phone": "+584121234567", "profileName": "Acme Support", "proxyLocation": { "country": "VE", "city": "caracas", "strictCity": false }, "qrCodeUrl": null, "pairingCode": null, "pairingCodeExpiresAt": null, "billable": true, "disconnectReason": null, "lastError": null, "rejectCalls": false, "rejectCallsMessage": null, "pacing": { "messagesPerMinute": 0, "firstContactPerMinute": 0, "typing": { "enabled": false, "minMs": 800, "maxMs": 6000, "charsPerSecond": 25 }, "queueTimeoutMinutes": 60, "custom": false }, "historySync": "none", "metadata": {}, "linkedAt": "2026-09-20T14:02:11.000Z", "lastConnectedAt": "2026-09-24T08:15:40.000Z", "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "post": { "tags": [ "Accounts" ], "operationId": "createAccount", "summary": "Create an account", "description": "Start linking a new WhatsApp number. Choose where its residential proxy exits with `proxyLocation`, a pair from `GET /v1/proxy-locations` (ideally the number's own country). The account is returned with `status: initializing`. Poll `GET /v1/accounts/{accountId}` (or listen for `account.qr_code_issued`) until `status` is `qr_ready`, show `qrCodeUrl` to the phone owner (WhatsApp > Linked devices > Link a device), then wait for `ready`.\n\nTo link by phone number instead, pass `pairingPhone`: the code appears as `pairingCode` (and the `account.pairing_code_issued` event) once the session is up. For a page someone else opens to link their own number, use `POST /v1/invitations`.\n\nChat history is not imported unless you pass `historySync: recent`. WhatsApp sends recent history once, right after the number links; those messages are stored with `source: history` and `history.synced` fires.\n\nRequires an active subscription. Inside a project, `maxAccounts` applies.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreateRequest" }, "examples": { "qrCode": { "summary": "qrCode", "value": { "name": "Support line", "proxyLocation": { "country": "VE", "city": "caracas" } } }, "pairingCode": { "summary": "pairingCode", "value": { "name": "Support line", "proxyLocation": { "country": "VE", "city": "caracas" }, "pairingPhone": "+584121234567" } }, "inProject": { "summary": "inProject", "value": { "name": "Front desk", "proxyLocation": { "country": "CL", "city": "santiago" }, "projectId": "ext:customer_8812" } }, "withHistory": { "summary": "withHistory", "value": { "name": "Sales line", "proxyLocation": { "country": "VE", "city": "caracas" }, "historySync": "recent" } } } } } }, "responses": { "201": { "description": "Account created.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "projectId": null, "name": "Support line", "status": "initializing", "reconnecting": false, "phone": null, "profileName": null, "proxyLocation": { "country": "VE", "city": "caracas", "strictCity": false }, "qrCodeUrl": null, "pairingCode": null, "pairingCodeExpiresAt": null, "billable": false, "disconnectReason": null, "lastError": null, "rejectCalls": false, "rejectCallsMessage": null, "pacing": { "messagesPerMinute": 0, "firstContactPerMinute": 0, "typing": { "enabled": false, "minMs": 800, "maxMs": 6000, "charsPerSecond": 25 }, "queueTimeoutMinutes": 60, "custom": false }, "historySync": "none", "metadata": {}, "linkedAt": null, "lastConnectedAt": null, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-20T14:00:03.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `unsupported_proxy_location`: `proxyLocation` names a country or city that is not in `GET /v1/proxy-locations`.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`proxyLocation` is required. Pick one from GET /v1/proxy-locations.", "details": { "field": "proxyLocation" } } }, "unsupported_proxy_location": { "summary": "unsupported_proxy_location", "value": { "code": "unsupported_proxy_location", "message": "Santiago, CL is not a supported proxy location. See GET /v1/proxy-locations.", "details": { "field": "proxyLocation" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "402": { "description": "Payment required: an upgrade, a subscription or an add-on.\n\n- `upgrade_required`: The Free plan includes 1 connected account and it is taken (by a linked account, or one still linking: `details.accountId` names it). Upgrade in Billing to connect more. `details` has `maxAccounts` and `upgradeUrl`.\n- `free_limit_reached`: The Free plan's monthly limit is reached (2,000 messages sent and received, or 0.5 GB of proxy traffic). The organization's accounts are paused (`disconnectReason: free_limit_reached`, the device stays linked) and sends, new accounts and reconnects are refused until the month ends (UTC) or the organization upgrades; then they reconnect on their own. `details` has `limit` (`messages` or `proxy`), `month`, `resetsAt` and `upgradeUrl`.\n- `subscription_required`: The subscription is past due, so no new account can be linked until it is paid. `details.billingUrl` links to Billing.\n- `payment_required`: Proxy traffic is paused because an invoice is unpaid (a failed charge, a payment waiting on 3D Secure, or a past-due subscription). Sends and new sessions are refused until it is paid; the organization's accounts show `disconnectReason: proxy_paused` and reconnect on their own once it is. `details.billingUrl` links to Billing.\n- `proxy_spend_cap_reached`: Proxy traffic is paused because this month's proxy overage reached the organization's monthly spend cap (set in Billing, $50 by default). Sends and new sessions are refused until the cap is raised or the month ends (UTC); the accounts show `disconnectReason: proxy_paused` and reconnect on their own. `details.capCents` has the cap, `details.billingUrl` links to Billing.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upgrade_required": { "summary": "upgrade_required", "value": { "code": "upgrade_required", "message": "The Free plan includes 1 connected number. Upgrade in Billing to connect more.", "details": { "maxAccounts": 1, "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "upgrade_required_linking": { "summary": "upgrade_required (the free slot is still linking)", "value": { "code": "upgrade_required", "message": "You already have a number linking. Finish linking it, or delete it to start over. Upgrade in Billing to connect more numbers.", "details": { "maxAccounts": 1, "upgradeUrl": "https://wuapi.dev/app/billing", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr" } } }, "free_limit_reached": { "summary": "free_limit_reached", "value": { "code": "free_limit_reached", "message": "This organization reached the Free plan's 2,000 messages for this month. Its numbers are paused until the month ends; upgrade in Billing to resume now.", "details": { "limit": "messages", "month": "2026-09", "resetsAt": "2026-10-01T00:00:00.000Z", "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "subscription_required": { "summary": "subscription_required", "value": { "code": "subscription_required", "message": "The subscription is past due. Pay the open invoice in Billing to connect accounts.", "details": { "billingUrl": "https://wuapi.dev/app/billing" } } }, "payment_required": { "summary": "payment_required", "value": { "code": "payment_required", "message": "Proxy traffic is paused because an invoice is unpaid. Pay it or update the payment method in Billing; the numbers reconnect on their own once it is paid.", "details": { "billingUrl": "https://wuapi.dev/app/billing", "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "proxy_spend_cap_reached": { "summary": "proxy_spend_cap_reached", "value": { "code": "proxy_spend_cap_reached", "message": "Proxy traffic is paused because this month's proxy spend reached the organization's cap. Raise the limit in Billing to resume now, or it resumes when the month ends.", "details": { "billingUrl": "https://wuapi.dev/app/billing", "upgradeUrl": "https://wuapi.dev/app/billing", "capCents": 5000 } } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `project_limit_reached`: The project already has `maxAccounts` accounts.\n- `trial_account_limit`: Legacy free trials only (new organizations start on the Free plan): the trial includes one connected account until it converts. `details.upgradeUrl` links to Billing.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "project_limit_reached": { "summary": "project_limit_reached", "value": { "code": "project_limit_reached", "message": "This project already has its maximum of 3 account(s).", "details": { "maxAccounts": 3 } } }, "trial_account_limit": { "summary": "trial_account_limit (legacy trial)", "value": { "code": "trial_account_limit", "message": "The free trial includes 1 connected account until it converts.", "details": { "maxAccounts": 1, "upgradeUrl": "https://wuapi.dev/app/billing" } } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } } } } } }, "409": { "description": "Conflict.\n\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/accounts/{accountId}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "get": { "tags": [ "Accounts" ], "operationId": "getAccount", "summary": "Get an account", "description": "The account, with its current QR code or pairing code while it links.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The account.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "projectId": null, "name": "Support line", "status": "ready", "reconnecting": false, "phone": "+584121234567", "profileName": "Acme Support", "proxyLocation": { "country": "VE", "city": "caracas", "strictCity": false }, "qrCodeUrl": null, "pairingCode": null, "pairingCodeExpiresAt": null, "billable": true, "disconnectReason": null, "lastError": null, "rejectCalls": false, "rejectCallsMessage": null, "pacing": { "messagesPerMinute": 0, "firstContactPerMinute": 0, "typing": { "enabled": false, "minMs": 800, "maxMs": 6000, "charsPerSecond": 25 }, "queueTimeoutMinutes": 60, "custom": false }, "historySync": "none", "metadata": {}, "linkedAt": "2026-09-20T14:02:11.000Z", "lastConnectedAt": "2026-09-24T08:15:40.000Z", "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "patch": { "tags": [ "Accounts" ], "operationId": "updateAccount", "summary": "Update an account", "description": "Rename it, set automatic call rejection, or turn on and tune its pacing (anti-ban protections, off by default). Call settings are sent to the live session (the engine must know the account; it does not need to be `ready`). Pacing applies from the next send, without reconnecting. `historySync` is stored at once and applies to the next link: WhatsApp sends history only right after a number links. A `proxyLocation` change is checked before anything else is applied: a refused location (`400` or `429`) leaves the whole request unapplied.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpdateRequest" }, "examples": { "rejectCalls": { "summary": "rejectCalls", "value": { "rejectCalls": true, "rejectCallsMessage": "We cannot take calls on this number. Please write to us." } }, "recommendedPacing": { "summary": "recommendedPacing", "value": { "pacing": { "messagesPerMinute": 12, "firstContactPerMinute": 5, "typing": { "enabled": true, "minMs": 800, "maxMs": 6000, "charsPerSecond": 25 } } } }, "pacing": { "summary": "pacing", "value": { "pacing": { "messagesPerMinute": 20, "typing": { "enabled": true, "maxMs": 4000 }, "queueTimeoutMinutes": 120 } } }, "resetPacing": { "summary": "resetPacing", "value": { "pacing": null } }, "historySync": { "summary": "historySync", "value": { "historySync": "recent" } } } } } }, "responses": { "200": { "description": "The updated account.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "projectId": null, "name": "Support line", "status": "ready", "reconnecting": false, "phone": "+584121234567", "profileName": "Acme Support", "proxyLocation": { "country": "VE", "city": "caracas", "strictCity": false }, "qrCodeUrl": null, "pairingCode": null, "pairingCodeExpiresAt": null, "billable": true, "disconnectReason": null, "lastError": null, "rejectCalls": true, "rejectCallsMessage": "We cannot take calls on this number. Please write to us.", "pacing": { "messagesPerMinute": 0, "firstContactPerMinute": 0, "typing": { "enabled": false, "minMs": 800, "maxMs": 6000, "charsPerSecond": 25 }, "queueTimeoutMinutes": 60, "custom": false }, "historySync": "none", "metadata": {}, "linkedAt": "2026-09-20T14:02:11.000Z", "lastConnectedAt": "2026-09-24T08:15:40.000Z", "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds. Also a `proxyLocation` change of a connected account less than 10 minutes after its last one: `details.retryAfterMs` says when it may change again, and nothing in the request is applied.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } }, "location_cooldown": { "summary": "proxyLocation changed less than 10 minutes ago", "value": { "code": "rate_limited", "message": "This number's proxy location changed less than 10 minutes ago. Each change gives it a new IP address, so try again in 7 minutes.", "details": { "field": "proxyLocation", "retryAfterMs": 412000 } } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "delete": { "tags": [ "Accounts" ], "operationId": "deleteAccount", "summary": "Delete an account", "description": "Log the session out on WhatsApp, delete the account and stop billing for it. Fires no event.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Deleted.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/accounts/{accountId}/reconnect": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Accounts" ], "operationId": "reconnectAccount", "summary": "Reconnect an account", "description": "Restart the session. Produces a fresh QR code (or pairing code) when the link is no longer valid.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Reconnecting.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "projectId": null, "name": "Support line", "status": "initializing", "reconnecting": false, "phone": "+584121234567", "profileName": "Acme Support", "proxyLocation": { "country": "VE", "city": "caracas", "strictCity": false }, "qrCodeUrl": null, "pairingCode": null, "pairingCodeExpiresAt": null, "billable": true, "disconnectReason": null, "lastError": null, "rejectCalls": false, "rejectCallsMessage": null, "pacing": { "messagesPerMinute": 0, "firstContactPerMinute": 0, "typing": { "enabled": false, "minMs": 800, "maxMs": 6000, "charsPerSecond": 25 }, "queueTimeoutMinutes": 60, "custom": false }, "historySync": "none", "metadata": {}, "linkedAt": "2026-09-20T14:02:11.000Z", "lastConnectedAt": "2026-09-24T08:15:40.000Z", "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "402": { "description": "Payment required.\n\n- `free_limit_reached`: The Free plan's monthly limit is reached (2,000 messages sent and received, or 0.5 GB of proxy traffic). The organization's accounts are paused (`disconnectReason: free_limit_reached`, the device stays linked) and sends, new accounts and reconnects are refused until the month ends (UTC) or the organization upgrades; then they reconnect on their own. `details` has `limit` (`messages` or `proxy`), `month`, `resetsAt` and `upgradeUrl`.\n- `upgrade_required`: The account never linked and stopped, so starting it again takes the Free plan's only slot, which another account holds. `details` has `maxAccounts` and `upgradeUrl`.\n- `payment_required`: Proxy traffic is paused because an invoice is unpaid (a failed charge, a payment waiting on 3D Secure, or a past-due subscription). Sends and new sessions are refused until it is paid; the organization's accounts show `disconnectReason: proxy_paused` and reconnect on their own once it is. `details.billingUrl` links to Billing.\n- `proxy_spend_cap_reached`: Proxy traffic is paused because this month's proxy overage reached the organization's monthly spend cap (set in Billing, $50 by default). Sends and new sessions are refused until the cap is raised or the month ends (UTC); the accounts show `disconnectReason: proxy_paused` and reconnect on their own. `details.capCents` has the cap, `details.billingUrl` links to Billing.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "free_limit_reached": { "summary": "free_limit_reached", "value": { "code": "free_limit_reached", "message": "This organization reached the Free plan's 2,000 messages for this month. Its numbers are paused until the month ends; upgrade in Billing to resume now.", "details": { "limit": "messages", "month": "2026-09", "resetsAt": "2026-10-01T00:00:00.000Z", "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "upgrade_required": { "summary": "upgrade_required", "value": { "code": "upgrade_required", "message": "The Free plan includes 1 connected number. Upgrade in Billing to connect more.", "details": { "maxAccounts": 1, "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "payment_required": { "summary": "payment_required", "value": { "code": "payment_required", "message": "Proxy traffic is paused because an invoice is unpaid. Pay it or update the payment method in Billing; the numbers reconnect on their own once it is paid.", "details": { "billingUrl": "https://wuapi.dev/app/billing", "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "proxy_spend_cap_reached": { "summary": "proxy_spend_cap_reached", "value": { "code": "proxy_spend_cap_reached", "message": "Proxy traffic is paused because this month's proxy spend reached the organization's cap. Raise the limit in Billing to resume now, or it resumes when the month ends.", "details": { "billingUrl": "https://wuapi.dev/app/billing", "upgradeUrl": "https://wuapi.dev/app/billing", "capCents": 5000 } } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/accounts/{accountId}/logout": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Accounts" ], "operationId": "logoutAccount", "summary": "Log an account out", "description": "Unlink the phone and stop billing, keeping the account and its messages. Reconnect to link again.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Logged out.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "projectId": null, "name": "Support line", "status": "disconnected", "reconnecting": false, "phone": "+584121234567", "profileName": "Acme Support", "proxyLocation": { "country": "VE", "city": "caracas", "strictCity": false }, "qrCodeUrl": null, "pairingCode": null, "pairingCodeExpiresAt": null, "billable": false, "disconnectReason": "logged_out", "lastError": null, "rejectCalls": false, "rejectCallsMessage": null, "pacing": { "messagesPerMinute": 0, "firstContactPerMinute": 0, "typing": { "enabled": false, "minMs": 800, "maxMs": 6000, "charsPerSecond": 25 }, "queueTimeoutMinutes": 60, "custom": false }, "historySync": "none", "metadata": {}, "linkedAt": "2026-09-20T14:02:11.000Z", "lastConnectedAt": "2026-09-24T08:15:40.000Z", "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/accounts/{accountId}/pairing-code": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Accounts" ], "operationId": "createPairingCode", "summary": "Create a pairing code", "description": "Link by phone number instead of QR code: returns an 8-character code the phone owner types in WhatsApp > Linked devices > Link a device > Link with phone number instead. Works while the account is not linked (a session the engine lost is recreated first). The code lives about 160 seconds; ask again after `expiresAt`.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairingCodeRequest" }, "example": { "phone": "+584121234567" } } } }, "responses": { "201": { "description": "The pairing code.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairingCode" }, "example": { "object": "pairing_code", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "code": "ABCD-1234", "expiresAt": "2026-09-24T08:18:20.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "402": { "description": "Payment required.\n\n- `free_limit_reached`: The Free plan's monthly limit is reached (2,000 messages sent and received, or 0.5 GB of proxy traffic). The organization's accounts are paused (`disconnectReason: free_limit_reached`, the device stays linked) and sends, new accounts and reconnects are refused until the month ends (UTC) or the organization upgrades; then they reconnect on their own. `details` has `limit` (`messages` or `proxy`), `month`, `resetsAt` and `upgradeUrl`.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "free_limit_reached": { "summary": "free_limit_reached", "value": { "code": "free_limit_reached", "message": "This organization reached the Free plan's 2,000 messages for this month. Its numbers are paused until the month ends; upgrade in Billing to resume now.", "details": { "limit": "messages", "month": "2026-09", "resetsAt": "2026-10-01T00:00:00.000Z", "upgradeUrl": "https://wuapi.dev/app/billing" } } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `already_linked`: The account is already linked, so there is nothing to pair.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "already_linked": { "summary": "already_linked", "value": { "code": "already_linked", "message": "The account is already linked." } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/presence": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Accounts" ], "operationId": "setAccountPresence", "summary": "Set online or offline", "description": "Show the account as online or offline to contacts.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPresenceRequest" }, "example": { "state": "online" } } } }, "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/disappearing-timer": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "put": { "tags": [ "Accounts" ], "operationId": "setDefaultDisappearingTimer", "summary": "Set the default disappearing timer", "description": "The timer new chats start with.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisappearingTimerRequest" }, "example": { "durationSeconds": 86400 } } } }, "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/presence": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "sendChatPresence", "summary": "Show typing or recording", "description": "Show (`typing`, `recording`) or clear (`paused`) the indicator in a chat.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatPresenceRequest" }, "example": { "state": "typing" } } } }, "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/read": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "sendReadReceipts", "summary": "Send read receipts", "description": "Send read receipts (blue ticks) for messages in a chat. Without `messageIds`, every unread inbound message wuapi stores for the chat. In a group WhatsApp takes one receipt per author, so this makes one change per author.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadReceiptsRequest" }, "example": { "messageIds": [ "m1c4v8n2x7q0w5k9d3a6y1br8t2hjs4f" ] } } } }, "responses": { "200": { "description": "How many were marked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRead" }, "example": { "object": "chat_read", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "messageCount": 3 } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/mark-read": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "markChatRead", "summary": "Mark a chat read", "description": "Clear the chat's unread badge on the phone and other devices. Sends no read receipts; use `POST .../read` for those.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/mark-unread": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "markChatUnread", "summary": "Mark a chat unread", "description": "Put the unread badge back on the chat.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/archive": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "archiveChat", "summary": "Archive a chat", "description": "Archive the chat on the phone and other devices.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/unarchive": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "unarchiveChat", "summary": "Unarchive a chat", "description": "Move the chat out of the archive.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/pin": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "pinChat", "summary": "Pin a chat", "description": "Pin the chat to the top.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/unpin": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "unpinChat", "summary": "Unpin a chat", "description": "Unpin the chat.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/mute": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "muteChat", "summary": "Mute a chat", "description": "Mute notifications for the chat, for `durationSeconds` or until unmuted.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MuteRequest" }, "example": { "durationSeconds": 28800 } } } }, "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/unmute": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Chats" ], "operationId": "unmuteChat", "summary": "Unmute a chat", "description": "Turn the chat's notifications back on.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "delete": { "tags": [ "Chats" ], "operationId": "deleteChat", "summary": "Delete a chat", "description": "Delete the chat on the linked devices. Messages stored in wuapi are kept.", "parameters": [ { "name": "deleteMedia", "in": "query", "required": false, "description": "Also delete the chat's media.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Deleted.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/disappearing-timer": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "put": { "tags": [ "Chats" ], "operationId": "setChatDisappearingTimer", "summary": "Set a chat's disappearing timer", "description": "Messages in the chat disappear after `durationSeconds`; 0 turns it off.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisappearingTimerRequest" }, "example": { "durationSeconds": 604800 } } } }, "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/labels": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" } ], "post": { "tags": [ "Labels" ], "operationId": "addChatLabel", "summary": "Label a chat", "description": "WhatsApp Business accounts only; others answer `400 not_supported`.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignRequest" }, "example": { "labelId": "5" } } } }, "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/chats/{chatId}/labels/{labelId}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChatId" }, { "$ref": "#/components/parameters/LabelId" } ], "delete": { "tags": [ "Labels" ], "operationId": "removeChatLabel", "summary": "Remove a label from a chat", "description": "WhatsApp Business accounts only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Removed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/labels/{labelId}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/LabelId" } ], "put": { "tags": [ "Labels" ], "operationId": "upsertLabel", "summary": "Create or edit a label", "description": "Creates the label with this id, or edits it. WhatsApp Business accounts only; others answer `400 not_supported`.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelUpsertRequest" }, "example": { "name": "Paid", "color": 3 } } } }, "responses": { "200": { "description": "The label.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" }, "example": { "object": "label", "id": "5", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Paid", "color": 3 } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "delete": { "tags": [ "Labels" ], "operationId": "deleteLabel", "summary": "Delete a label", "description": "WhatsApp Business accounts only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Deleted.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/messages/{messageId}/labels": { "parameters": [ { "$ref": "#/components/parameters/MessageId" } ], "post": { "tags": [ "Labels" ], "operationId": "addMessageLabel", "summary": "Label a message", "description": "WhatsApp Business accounts only. The message must have reached WhatsApp and not be deleted.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignRequest" }, "example": { "labelId": "5" } } } }, "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/messages/{messageId}/labels/{labelId}": { "parameters": [ { "$ref": "#/components/parameters/MessageId" }, { "$ref": "#/components/parameters/LabelId" } ], "delete": { "tags": [ "Labels" ], "operationId": "removeMessageLabel", "summary": "Remove a label from a message", "description": "WhatsApp Business accounts only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Removed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/stories": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Stories" ], "operationId": "createStory", "summary": "Post a story", "description": "Queued like any send and stored as an outbound message with `chatId: stories`. The outcome arrives as `message.sent` or `message.failed`.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryCreateRequest" }, "examples": { "text": { "summary": "text", "value": { "type": "text", "text": "New hours from Monday: 8 to 18.", "backgroundColor": "#0F766E", "font": 1 } }, "image": { "summary": "image", "value": { "type": "image", "media": { "url": "https://example.com/promo.jpg" }, "text": "This week only" } } } } } }, "responses": { "202": { "description": "Queued.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "stories", "chatType": "story", "direction": "outbound", "source": "api", "from": "+584121234567", "to": "stories", "profileName": null, "username": null, "type": "text", "text": "New hours from Monday: 8 to 18.", "media": null, "location": null, "contact": null, "contacts": null, "poll": null, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": false, "replyToMessageId": null, "status": "queued", "error": null, "metadata": {}, "sentAt": null, "editedAt": null, "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "402": { "description": "Payment required: the Free plan's limits, or billing.\n\n- `free_limit_reached`: The Free plan's monthly limit is reached (2,000 messages sent and received, or 0.5 GB of proxy traffic). The organization's accounts are paused (`disconnectReason: free_limit_reached`, the device stays linked) and sends, new accounts and reconnects are refused until the month ends (UTC) or the organization upgrades; then they reconnect on their own. `details` has `limit` (`messages` or `proxy`), `month`, `resetsAt` and `upgradeUrl`.\n- `upgrade_required`: The organization is on the Free plan (its paid subscription ended) with more than 1 billable account. Sends are refused until the extra accounts are removed or it upgrades. `details` has `maxAccounts` and `upgradeUrl`.\n- `payment_required`: Proxy traffic is paused because an invoice is unpaid (a failed charge, a payment waiting on 3D Secure, or a past-due subscription). Sends and new sessions are refused until it is paid; the organization's accounts show `disconnectReason: proxy_paused` and reconnect on their own once it is. `details.billingUrl` links to Billing.\n- `proxy_spend_cap_reached`: Proxy traffic is paused because this month's proxy overage reached the organization's monthly spend cap (set in Billing, $50 by default). Sends and new sessions are refused until the cap is raised or the month ends (UTC); the accounts show `disconnectReason: proxy_paused` and reconnect on their own. `details.capCents` has the cap, `details.billingUrl` links to Billing.\n- `trial_proxy_limit_reached`: Legacy free trials only (new organizations start on the Free plan): the trial's 0.5 GB of proxy traffic is used up. Sends are refused until the trial ends. `details.upgradeUrl` links to Billing.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "free_limit_reached": { "summary": "free_limit_reached", "value": { "code": "free_limit_reached", "message": "This organization reached the Free plan's 2,000 messages for this month. Its numbers are paused until the month ends; upgrade in Billing to resume now.", "details": { "limit": "messages", "month": "2026-09", "resetsAt": "2026-10-01T00:00:00.000Z", "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "upgrade_required": { "summary": "upgrade_required", "value": { "code": "upgrade_required", "message": "The Free plan includes 1 connected number and this organization has more. Remove the extra numbers or upgrade in Billing to keep sending.", "details": { "maxAccounts": 1, "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "payment_required": { "summary": "payment_required", "value": { "code": "payment_required", "message": "Proxy traffic is paused because an invoice is unpaid. Pay it or update the payment method in Billing; the numbers reconnect on their own once it is paid.", "details": { "billingUrl": "https://wuapi.dev/app/billing", "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "proxy_spend_cap_reached": { "summary": "proxy_spend_cap_reached", "value": { "code": "proxy_spend_cap_reached", "message": "Proxy traffic is paused because this month's proxy spend reached the organization's cap. Raise the limit in Billing to resume now, or it resumes when the month ends.", "details": { "billingUrl": "https://wuapi.dev/app/billing", "upgradeUrl": "https://wuapi.dev/app/billing", "capCents": 5000 } } }, "trial_proxy_limit_reached": { "summary": "trial_proxy_limit_reached (legacy trial)", "value": { "code": "trial_proxy_limit_reached", "message": "The free trial includes 0.5 GB of proxy traffic and it is used up. Sends resume when the trial ends.", "details": { "limitMb": 512, "upgradeUrl": "https://wuapi.dev/app/billing" } } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/accounts/{accountId}/contacts/check": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Contacts" ], "operationId": "checkContacts", "summary": "Check numbers on WhatsApp", "description": "Which numbers have WhatsApp. Read-only: works for a suspended project.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCheckRequest" }, "example": { "phones": [ "+584241112233", "+584240000000" ] } } } }, "responses": { "200": { "description": "One result per number.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCheckList" }, "example": { "object": "list", "items": [ { "object": "contact_check", "phone": "+584241112233", "onWhatsApp": true, "contactId": "+584241112233", "businessName": null, "username": null }, { "object": "contact_check", "phone": "+584240000000", "onWhatsApp": false, "contactId": null, "businessName": null, "username": null } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/contacts/lookup": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Contacts" ], "operationId": "lookupContacts", "summary": "Look up contacts", "description": "About text, picture id, verified business name and device count. Read-only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactLookupRequest" }, "example": { "contactIds": [ "+584241112233" ] } } } }, "responses": { "200": { "description": "One contact per id.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" }, "example": { "object": "list", "items": [ { "object": "contact", "id": "+584241112233", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "lid": null, "username": null, "about": "Available", "pictureId": "1727164540", "businessName": null, "deviceCount": 2 } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.\n- `username_not_supported`: `contactIds` has a WhatsApp username (`@handle`). WhatsApp does not let a linked device look up usernames.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } }, "username_not_supported": { "summary": "username_not_supported", "value": { "code": "username_not_supported", "message": "`contactIds` takes contact ids, not usernames: WhatsApp does not let a linked device look up @lina.morales. Use the contact's number or lid: id.", "details": { "field": "contactIds", "value": "@lina.morales" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/contacts/{contactId}/picture": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ContactId" } ], "get": { "tags": [ "Contacts" ], "operationId": "getContactPicture", "summary": "Get a profile picture", "description": "The contact's profile picture, if this account can see it.", "parameters": [ { "name": "preview", "in": "query", "required": false, "description": "Return the small preview.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The picture.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Picture" }, "example": { "object": "picture", "id": "1727164540", "url": "https://pps.whatsapp.net/v/t61/example.jpg", "preview": false } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `picture_not_found`: The contact or group has no picture this account can see.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "picture_not_found": { "summary": "picture_not_found", "value": { "code": "picture_not_found", "message": "No picture." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/contacts/{contactId}/business-profile": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ContactId" } ], "get": { "tags": [ "Contacts" ], "operationId": "getBusinessProfile", "summary": "Get a business profile", "description": "The WhatsApp Business profile of a contact.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The business profile.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessProfile" }, "example": { "object": "business_profile", "contactId": "+584241112233", "address": "Av. Principal 12, Caracas", "email": "hola@example.com", "categories": [ { "id": "133436743388217", "name": "Shopping & retail" } ], "profileOptions": {}, "timeZone": "America/Caracas", "businessHours": [ { "dayOfWeek": "mon", "mode": "specific_hours", "openTime": "09:00", "closeTime": "18:00" } ] } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `business_profile_not_found`: The contact is not a WhatsApp Business account.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "business_profile_not_found": { "summary": "business_profile_not_found", "value": { "code": "business_profile_not_found", "message": "Not a business account." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/contacts/{contactId}/subscribe-presence": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ContactId" } ], "post": { "tags": [ "Contacts" ], "operationId": "subscribeContactPresence", "summary": "Subscribe to a contact's presence", "description": "Receive `contact.presence_updated` events for the contact. Needs the engine's extended events; otherwise `400 not_supported`.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/contacts/{contactId}/block": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ContactId" } ], "post": { "tags": [ "Contacts" ], "operationId": "blockContact", "summary": "Block a contact", "description": "The contact can no longer message or call the account.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/contacts/{contactId}/unblock": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ContactId" } ], "post": { "tags": [ "Contacts" ], "operationId": "unblockContact", "summary": "Unblock a contact", "description": "Remove the contact from the blocklist.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/blocklist": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "get": { "tags": [ "Contacts" ], "operationId": "listBlockedContacts", "summary": "List blocked contacts", "description": "The account's blocklist, read live from WhatsApp. `contactId` is the contact as WhatsApp lists it (often a LID); `phone` and `lid` add the number and the LID when the account knows them.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of blocked contacts.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockedContactList" }, "example": { "object": "list", "items": [ { "object": "blocked_contact", "contactId": "lid:201843727138927", "phone": "+584241112233", "lid": "lid:201843727138927" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/contact-link": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "get": { "tags": [ "Contacts" ], "operationId": "getContactLink", "summary": "Get the account's contact link", "description": "The account's own contact QR link.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The link.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactLink" }, "example": { "object": "contact_link", "url": "https://wa.me/qr/ABCDEFGHIJKL1" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/contact-link/reset": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Contacts" ], "operationId": "resetContactLink", "summary": "Reset the account's contact link", "description": "Revoke the current contact link and return a new one.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The new link.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactLink" }, "example": { "object": "contact_link", "url": "https://wa.me/qr/ABCDEFGHIJKL1" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/links/resolve": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Contacts" ], "operationId": "resolveLink", "summary": "Resolve a contact or business link", "description": "Who a contact QR link or a business message link points to. Read-only. `400 not_supported` when WhatsApp does not offer link resolution to this account.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResolveRequest" }, "example": { "kind": "contact", "code": "https://wa.me/qr/ABCDEFGHIJKL1" } } } }, "responses": { "200": { "description": "The link's target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedLink" }, "example": { "object": "resolved_link", "kind": "contact", "contactId": "+584241112233", "type": "contact", "profileName": "Maria", "businessName": null, "verifiedLevel": null, "prefilledText": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events, or this feature where WhatsApp does not offer it to the account.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "WhatsApp does not offer contact link resolution to this account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `link_not_found`: WhatsApp does not know the link.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "link_not_found": { "summary": "link_not_found", "value": { "code": "link_not_found", "message": "Link not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/bots": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "get": { "tags": [ "Contacts" ], "operationId": "listBots", "summary": "List WhatsApp AI bots", "description": "WhatsApp's AI bot directory as the account sees it. `400 not_supported` when WhatsApp does not offer it to this account (WhatsApp's AI assistant is not available in every country or on every account).", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of bots.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotList" }, "example": { "object": "list", "items": [ { "object": "bot", "id": "867051314767696@bot", "personaId": null, "name": "AI assistant", "description": null, "category": null, "default": true, "prompts": [], "commands": [] } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events, or this feature where WhatsApp does not offer it to the account.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "WhatsApp does not offer the AI bot directory to this account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/profile": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "patch": { "tags": [ "Profile" ], "operationId": "updateProfile", "summary": "Update the About text or display name", "description": "WhatsApp cannot be read back here, so this answers 204. `about` and `name` are two changes on WhatsApp.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpdateRequest" }, "example": { "about": "Replies within one business day.", "name": "Acme Support" } } } }, "responses": { "204": { "description": "Updated.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/profile/picture": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "put": { "tags": [ "Profile" ], "operationId": "setProfilePicture", "summary": "Set the profile picture", "description": "JPEG, from an https URL or base64.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PictureUploadRequest" }, "example": { "url": "https://example.com/avatar.jpg" } } } }, "responses": { "200": { "description": "The new picture.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Picture" }, "example": { "object": "picture", "id": "1727164540", "url": null, "preview": false } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "delete": { "tags": [ "Profile" ], "operationId": "deleteProfilePicture", "summary": "Delete the profile picture", "description": "Remove the account's profile picture.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Deleted.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/privacy": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "get": { "tags": [ "Privacy" ], "operationId": "getPrivacySettings", "summary": "Get privacy settings", "description": "The account's privacy settings, read live from WhatsApp.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The settings.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacySettings" }, "example": { "object": "privacy_settings", "groupAdd": "contacts", "lastSeen": "contacts", "stories": "contacts", "profile": "all", "readReceipts": "all", "online": "all", "callAdd": "all", "messages": null, "defense": null, "stickers": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "patch": { "tags": [ "Privacy" ], "operationId": "updatePrivacySettings", "summary": "Change privacy settings", "description": "Change one or more settings. Each setting is one change on WhatsApp. Returns every setting after the change.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyUpdateRequest" }, "example": { "lastSeen": "contacts", "readReceipts": "all" } } } }, "responses": { "200": { "description": "The settings.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacySettings" }, "example": { "object": "privacy_settings", "groupAdd": "contacts", "lastSeen": "contacts", "stories": "contacts", "profile": "all", "readReceipts": "all", "online": "all", "callAdd": "all", "messages": null, "defense": null, "stickers": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/privacy/stories": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "get": { "tags": [ "Privacy" ], "operationId": "getStoryPrivacy", "summary": "Get story privacy", "description": "Who sees the account's stories.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The lists.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryPrivacy" }, "example": { "object": "story_privacy", "lists": [ { "type": "contacts", "contactIds": [], "default": true } ] } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/calls/{callId}/reject": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/CallId" } ], "post": { "tags": [ "Calls" ], "operationId": "rejectCall", "summary": "Reject an incoming call", "description": "Use the `id` and `from` of a `call.received` event. For automatic rejection, set `rejectCalls` on the account.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallRejectRequest" }, "example": { "from": "+584241112233" } } } }, "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/sticker-packs/{stickerPackId}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/StickerPackId" } ], "get": { "tags": [ "Sticker packs" ], "operationId": "getStickerPack", "summary": "Get a sticker pack", "description": "A sticker pack and its stickers.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The pack.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StickerPack" }, "example": { "object": "sticker_pack", "id": "4a0b1c2d-sticker-pack", "name": "Office life", "publisher": "Acme", "description": null, "animated": false, "trayImageId": null, "stickers": [] } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `sticker_pack_not_found`: WhatsApp does not know the sticker pack.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "sticker_pack_not_found": { "summary": "sticker_pack_not_found", "value": { "code": "sticker_pack_not_found", "message": "Sticker pack not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/orders/{orderId}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/OrderId" } ], "get": { "tags": [ "Orders" ], "operationId": "getOrder", "summary": "Get an order", "description": "Details of a catalog order received as a message.", "parameters": [ { "name": "token", "in": "query", "required": true, "description": "The order's token, from the order message.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The order.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "object": "order", "id": "1234567890123456", "currency": "usd", "subtotalCents": 2500, "totalCents": 2500, "products": [ { "id": "sku-1", "name": "Mug", "quantity": 1, "priceCents": 2500, "currency": "usd", "imageUrl": null } ], "createdAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `order_not_found`: WhatsApp does not know the order, or the token does not match.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "order_not_found": { "summary": "order_not_found", "value": { "code": "order_not_found", "message": "Order not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/messages": { "post": { "tags": [ "Messages" ], "operationId": "sendMessage", "summary": "Send a message", "description": "Queue a message from a `ready` account to a contact, a group, or a channel the account administers. It is returned with `status: queued`; the outcome arrives as `message.sent` / `message.failed`, or read it with `GET /v1/messages/{messageId}`. An account that dropped from `ready` for a reconnect less than the offline tolerance ago (currently 3 minutes) still takes it: it waits for the account, is sent once the account is back (in order, with the same WhatsApp message id if an earlier attempt was cut off), and fails with `account_offline` if the account is not back within the tolerance or goes down for good (logged out, banned, replaced, deleted). The account's pacing (12 per minute and 5 per minute to first contacts by default, see `pacing` on the account) keeps it queued and retried for up to `pacing.queueTimeoutMinutes` (60 by default) before it fails with `rate_limited`. A recipient without WhatsApp fails with `error.code: not_on_whatsapp`.\n\nSend `Idempotency-Key` so a retry never sends twice.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" }, "examples": { "text": { "summary": "text", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "+584241112233", "type": "text", "text": "Your order has shipped.", "metadata": { "orderId": "A-1042" } } }, "document": { "summary": "document", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "+584241112233", "type": "document", "media": { "url": "https://example.com/invoice.pdf", "filename": "invoice.pdf" }, "text": "Your invoice" } }, "voiceNote": { "summary": "voiceNote", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "+584241112233", "type": "voice", "media": { "url": "https://example.com/note.ogg", "mimeType": "audio/ogg; codecs=opus" } } }, "poll": { "summary": "poll", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "120363041234567890@g.us", "type": "poll", "poll": { "name": "Lunch?", "options": [ "Pizza", "Sushi", "Tacos" ], "selectableCount": 1 } } }, "calendarEvent": { "summary": "calendarEvent", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "120363041234567890@g.us", "type": "calendar_event", "calendarEvent": { "name": "Launch review", "startsAt": "2026-10-01T15:00:00Z", "callType": "video" } } }, "contacts": { "summary": "contacts", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "+584241112233", "type": "contacts", "contacts": [ { "name": "Sales", "phone": "+584121111111" }, { "name": "Support", "phone": "+584122222222" } ] } }, "mentionAll": { "summary": "mentionAll", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "120363041234567890@g.us", "type": "text", "text": "Meeting in 10 minutes.", "mentionAll": true } }, "reply": { "summary": "reply", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "+584241112233", "type": "text", "text": "Tomorrow.", "replyToMessageId": "m1c4v8n2x7q0w5k9d3a6y1br8t2hjs4f" } }, "channelPost": { "summary": "channelPost", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "120363198765432101@newsletter", "type": "text", "text": "Version 2.4 is out." } }, "location": { "summary": "location", "value": { "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "to": "+584241112233", "type": "location", "location": { "latitude": 10.4806, "longitude": -66.9036, "name": "Caracas office", "address": "Av. Francisco de Miranda" } } } } } } }, "responses": { "202": { "description": "Queued.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "chatType": "direct", "direction": "outbound", "source": "api", "from": "+584121234567", "to": "+584241112233", "profileName": null, "username": null, "type": "text", "text": "Your order has shipped.", "media": null, "location": null, "contact": null, "contacts": null, "poll": null, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": false, "replyToMessageId": null, "status": "queued", "error": null, "metadata": { "orderId": "A-1042" }, "sentAt": null, "editedAt": null, "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `username_not_supported`: `to` is a WhatsApp username (`@handle`) this account has no chat with. WhatsApp does not let a linked device look up usernames.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "username_not_supported": { "summary": "username_not_supported", "value": { "code": "username_not_supported", "message": "This account has no chat with @lina.morales. WhatsApp does not let a linked device look a username up yet, so a username only works for a contact that already chatted with this account and whose username WhatsApp shared. Send to the contact's number or lid: id instead.", "details": { "username": "lina.morales" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "402": { "description": "Payment required: the Free plan's limits, or billing.\n\n- `free_limit_reached`: The Free plan's monthly limit is reached (2,000 messages sent and received, or 0.5 GB of proxy traffic). The organization's accounts are paused (`disconnectReason: free_limit_reached`, the device stays linked) and sends, new accounts and reconnects are refused until the month ends (UTC) or the organization upgrades; then they reconnect on their own. `details` has `limit` (`messages` or `proxy`), `month`, `resetsAt` and `upgradeUrl`.\n- `upgrade_required`: The organization is on the Free plan (its paid subscription ended) with more than 1 billable account. Sends are refused until the extra accounts are removed or it upgrades. `details` has `maxAccounts` and `upgradeUrl`.\n- `payment_required`: Proxy traffic is paused because an invoice is unpaid (a failed charge, a payment waiting on 3D Secure, or a past-due subscription). Sends and new sessions are refused until it is paid; the organization's accounts show `disconnectReason: proxy_paused` and reconnect on their own once it is. `details.billingUrl` links to Billing.\n- `proxy_spend_cap_reached`: Proxy traffic is paused because this month's proxy overage reached the organization's monthly spend cap (set in Billing, $50 by default). Sends and new sessions are refused until the cap is raised or the month ends (UTC); the accounts show `disconnectReason: proxy_paused` and reconnect on their own. `details.capCents` has the cap, `details.billingUrl` links to Billing.\n- `trial_proxy_limit_reached`: Legacy free trials only (new organizations start on the Free plan): the trial's 0.5 GB of proxy traffic is used up. Sends are refused until the trial ends. `details.upgradeUrl` links to Billing.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "free_limit_reached": { "summary": "free_limit_reached", "value": { "code": "free_limit_reached", "message": "This organization reached the Free plan's 2,000 messages for this month. Its numbers are paused until the month ends; upgrade in Billing to resume now.", "details": { "limit": "messages", "month": "2026-09", "resetsAt": "2026-10-01T00:00:00.000Z", "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "upgrade_required": { "summary": "upgrade_required", "value": { "code": "upgrade_required", "message": "The Free plan includes 1 connected number and this organization has more. Remove the extra numbers or upgrade in Billing to keep sending.", "details": { "maxAccounts": 1, "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "payment_required": { "summary": "payment_required", "value": { "code": "payment_required", "message": "Proxy traffic is paused because an invoice is unpaid. Pay it or update the payment method in Billing; the numbers reconnect on their own once it is paid.", "details": { "billingUrl": "https://wuapi.dev/app/billing", "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "proxy_spend_cap_reached": { "summary": "proxy_spend_cap_reached", "value": { "code": "proxy_spend_cap_reached", "message": "Proxy traffic is paused because this month's proxy spend reached the organization's cap. Raise the limit in Billing to resume now, or it resumes when the month ends.", "details": { "billingUrl": "https://wuapi.dev/app/billing", "upgradeUrl": "https://wuapi.dev/app/billing", "capCents": 5000 } } }, "trial_proxy_limit_reached": { "summary": "trial_proxy_limit_reached (legacy trial)", "value": { "code": "trial_proxy_limit_reached", "message": "The free trial includes 0.5 GB of proxy traffic and it is used up. Sends resume when the trial ends.", "details": { "limitMb": 512, "upgradeUrl": "https://wuapi.dev/app/billing" } } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "get": { "tags": [ "Messages" ], "operationId": "listMessages", "summary": "List messages", "description": "Messages in scope, newest first.", "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Only this account's messages.", "schema": { "type": "string" } }, { "name": "chatId", "in": "query", "required": false, "description": "Only this chat: a contact id, a group id, a channel id or `stories`.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Only inbound or outbound messages.", "schema": { "$ref": "#/components/schemas/MessageDirection" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/ProjectFilter" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of messages.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" }, "example": { "object": "list", "items": [ { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "chatType": "direct", "direction": "outbound", "source": "api", "from": "+584121234567", "to": "+584241112233", "profileName": null, "username": null, "type": "text", "text": "Your order has shipped.", "media": null, "location": null, "contact": null, "contacts": null, "poll": null, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": false, "replyToMessageId": null, "status": "delivered", "error": null, "metadata": { "orderId": "A-1042" }, "sentAt": "2026-09-24T08:15:40.000Z", "editedAt": null, "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/messages/{messageId}": { "parameters": [ { "$ref": "#/components/parameters/MessageId" } ], "get": { "tags": [ "Messages" ], "operationId": "getMessage", "summary": "Get a message", "description": "A message and its current status.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The message.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "chatType": "direct", "direction": "outbound", "source": "api", "from": "+584121234567", "to": "+584241112233", "profileName": null, "username": null, "type": "text", "text": "Your order has shipped.", "media": null, "location": null, "contact": null, "contacts": null, "poll": null, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": false, "replyToMessageId": null, "status": "delivered", "error": null, "metadata": { "orderId": "A-1042" }, "sentAt": "2026-09-24T08:15:40.000Z", "editedAt": null, "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "patch": { "tags": [ "Messages" ], "operationId": "editMessage", "summary": "Edit a message", "description": "Outbound text messages only, within WhatsApp's edit window (about 15 minutes; WhatsApp's refusal is returned as is). Fires `message.edited`.\n\nA text message still `queued` (never sent) is sent with the new text instead: `editedAt` stays `null` and `message.edited` does not fire. While a queued message is being handed to WhatsApp this answers `409 message_sending` for a few seconds.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEditRequest" }, "example": { "text": "Your order has shipped. Tracking: 1Z999." } } } }, "responses": { "200": { "description": "The edited message.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "chatType": "direct", "direction": "outbound", "source": "api", "from": "+584121234567", "to": "+584241112233", "profileName": null, "username": null, "type": "text", "text": "Your order has shipped. Tracking: 1Z999.", "media": null, "location": null, "contact": null, "contacts": null, "poll": null, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": false, "replyToMessageId": null, "status": "read", "error": null, "metadata": { "orderId": "A-1042" }, "sentAt": "2026-09-24T08:15:40.000Z", "editedAt": "2026-09-24T08:15:40.000Z", "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `message_sending`: The message was queued and is being handed to WhatsApp right now. Retry in a few seconds: it is then `sent` (and the change goes to WhatsApp) or `failed`.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "message_sending": { "summary": "message_sending", "value": { "code": "message_sending", "message": "The message is being handed to WhatsApp right now. Retry in a few seconds: it will then be sent (and can be deleted or edited on WhatsApp) or failed." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "delete": { "tags": [ "Messages" ], "operationId": "deleteMessage", "summary": "Delete a message", "description": "Outbound messages only. For everyone by default: the row stays with `deletedAt` set and its content cleared, and `message.deleted` fires.\n\nA message still `queued` (never sent) is cancelled instead: it never goes out, it ends `failed` with `error.code: cancelled`, and `message.failed` fires. While a queued message is being handed to WhatsApp this answers `409 message_sending` for a few seconds.", "parameters": [ { "name": "forEveryone", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "`false` deletes it on the linked devices only and keeps the row unchanged." }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Deleted.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `message_sending`: The message was queued and is being handed to WhatsApp right now. Retry in a few seconds: it is then `sent` (and the change goes to WhatsApp) or `failed`.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "message_sending": { "summary": "message_sending", "value": { "code": "message_sending", "message": "The message is being handed to WhatsApp right now. Retry in a few seconds: it will then be sent (and can be deleted or edited on WhatsApp) or failed." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/messages/{messageId}/react": { "parameters": [ { "$ref": "#/components/parameters/MessageId" } ], "post": { "tags": [ "Messages" ], "operationId": "reactToMessage", "summary": "React to a message", "description": "An empty `emoji` removes the reaction.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactRequest" }, "example": { "emoji": "👍" } } } }, "responses": { "204": { "description": "Sent.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/messages/{messageId}/vote": { "parameters": [ { "$ref": "#/components/parameters/MessageId" } ], "post": { "tags": [ "Messages" ], "operationId": "voteInPoll", "summary": "Vote in a poll", "description": "Options are validated against the stored poll. Returns the poll with its tally, your vote included.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteRequest" }, "example": { "options": [ "Sushi" ] } } } }, "responses": { "200": { "description": "The poll message.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "120363041234567890@g.us", "chatType": "group", "direction": "outbound", "source": "api", "from": "+584121234567", "to": "120363041234567890@g.us", "profileName": null, "username": null, "type": "poll", "text": null, "media": null, "location": null, "contact": null, "contacts": null, "poll": { "name": "Lunch?", "options": [ { "name": "Pizza", "voteCount": 1 }, { "name": "Sushi", "voteCount": 2 } ], "selectableCount": 1, "voterCount": 3 }, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": false, "replyToMessageId": null, "status": "read", "error": null, "metadata": {}, "sentAt": null, "editedAt": null, "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/messages/{messageId}/star": { "parameters": [ { "$ref": "#/components/parameters/MessageId" } ], "post": { "tags": [ "Messages" ], "operationId": "starMessage", "summary": "Star a message", "description": "Star the message on the phone and other devices.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The message.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "chatType": "direct", "direction": "outbound", "source": "api", "from": "+584121234567", "to": "+584241112233", "profileName": null, "username": null, "type": "text", "text": "Your order has shipped.", "media": null, "location": null, "contact": null, "contacts": null, "poll": null, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": true, "replyToMessageId": null, "status": "read", "error": null, "metadata": { "orderId": "A-1042" }, "sentAt": "2026-09-24T08:15:40.000Z", "editedAt": null, "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/messages/{messageId}/unstar": { "parameters": [ { "$ref": "#/components/parameters/MessageId" } ], "post": { "tags": [ "Messages" ], "operationId": "unstarMessage", "summary": "Unstar a message", "description": "Remove the star.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The message.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "chatType": "direct", "direction": "outbound", "source": "api", "from": "+584121234567", "to": "+584241112233", "profileName": null, "username": null, "type": "text", "text": "Your order has shipped.", "media": null, "location": null, "contact": null, "contacts": null, "poll": null, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": false, "replyToMessageId": null, "status": "read", "error": null, "metadata": { "orderId": "A-1042" }, "sentAt": "2026-09-24T08:15:40.000Z", "editedAt": null, "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "get": { "tags": [ "Groups" ], "operationId": "listGroups", "summary": "List groups", "description": "Every group of the account, read live from WhatsApp.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of groups.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupList" }, "example": { "object": "list", "items": [ { "object": "group", "id": "120363041234567890@g.us", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Launch team", "description": "Coordination for the September launch.", "ownerId": "+584121234567", "community": false, "locked": false, "announce": false, "participants": [ { "contactId": "+584121234567", "name": "Acme Support", "role": "owner" }, { "contactId": "+584241112233", "name": "Maria", "role": "member" }, { "contactId": "lid:201843727138927", "name": null, "role": "member" } ], "createdAt": "2026-09-01T12:00:00.000Z" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "post": { "tags": [ "Groups" ], "operationId": "createGroup", "summary": "Create a group or community", "description": "With `community: true`, creates a community (`participants` may be empty); link groups to it with `POST .../groups/{groupId}/subgroups`.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupCreateRequest" }, "examples": { "group": { "summary": "group", "value": { "name": "Launch team", "participants": [ "+584241112233" ] } }, "community": { "summary": "community", "value": { "name": "Acme customers", "community": true } } } } } }, "responses": { "201": { "description": "Created.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" }, "example": { "object": "group", "id": "120363041234567890@g.us", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Launch team", "description": "Coordination for the September launch.", "ownerId": "+584121234567", "community": false, "locked": false, "announce": false, "participants": [ { "contactId": "+584121234567", "name": "Acme Support", "role": "owner" }, { "contactId": "+584241112233", "name": "Maria", "role": "member" }, { "contactId": "lid:201843727138927", "name": null, "role": "member" } ], "createdAt": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/join": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "tags": [ "Groups" ], "operationId": "joinGroup", "summary": "Join a group by invite", "description": "Join with an invite code or link.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupJoinRequest" }, "example": { "code": "https://chat.whatsapp.com/AbCdEf123456" } } } }, "responses": { "200": { "description": "The joined group.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupJoin" }, "example": { "object": "group_join", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "groupId": "120363041234567890@g.us" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `invite_not_found`: The invite code was revoked or does not exist.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "invite_not_found": { "summary": "invite_not_found", "value": { "code": "invite_not_found", "message": "The invite link was revoked or does not exist." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/invites/{code}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/InviteCode" } ], "get": { "tags": [ "Groups" ], "operationId": "getGroupInvite", "summary": "Preview a group invite", "description": "The group behind an invite code, without joining.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The group.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" }, "example": { "object": "group", "id": "120363041234567890@g.us", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Launch team", "description": "Coordination for the September launch.", "ownerId": "+584121234567", "community": false, "locked": false, "announce": false, "participants": [ { "contactId": "+584121234567", "name": "Acme Support", "role": "owner" }, { "contactId": "+584241112233", "name": "Maria", "role": "member" }, { "contactId": "lid:201843727138927", "name": null, "role": "member" } ], "createdAt": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `invite_not_found`: The invite code was revoked or does not exist.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "invite_not_found": { "summary": "invite_not_found", "value": { "code": "invite_not_found", "message": "The invite link was revoked or does not exist." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "get": { "tags": [ "Groups" ], "operationId": "getGroup", "summary": "Get a group", "description": "The group and its participants, read live from WhatsApp.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The group.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" }, "example": { "object": "group", "id": "120363041234567890@g.us", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Launch team", "description": "Coordination for the September launch.", "ownerId": "+584121234567", "community": false, "locked": false, "announce": false, "participants": [ { "contactId": "+584121234567", "name": "Acme Support", "role": "owner" }, { "contactId": "+584241112233", "name": "Maria", "role": "member" }, { "contactId": "lid:201843727138927", "name": null, "role": "member" } ], "createdAt": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "patch": { "tags": [ "Groups" ], "operationId": "updateGroup", "summary": "Update a group", "description": "Change the name, description or settings. Admins only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUpdateRequest" }, "example": { "name": "Launch team (Q4)", "announce": true, "joinApproval": true } } } }, "responses": { "200": { "description": "The updated group.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" }, "example": { "object": "group", "id": "120363041234567890@g.us", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Launch team (Q4)", "description": "Coordination for the September launch.", "ownerId": "+584121234567", "community": false, "locked": false, "announce": true, "participants": [ { "contactId": "+584121234567", "name": "Acme Support", "role": "owner" }, { "contactId": "+584241112233", "name": "Maria", "role": "member" }, { "contactId": "lid:201843727138927", "name": null, "role": "member" } ], "createdAt": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/leave": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "post": { "tags": [ "Groups" ], "operationId": "leaveGroup", "summary": "Leave a group", "description": "The account leaves the group.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Left.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/participants/add": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "post": { "tags": [ "Groups" ], "operationId": "addGroupParticipants", "summary": "Add participants", "description": "Add contacts to the group. A contact whose privacy forbids it gets an `inviteCode` instead. Each contact gets its own result.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIdsRequest" }, "example": { "contactIds": [ "+584241112233" ] } } } }, "responses": { "200": { "description": "One result per contact.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResultList" }, "example": { "object": "list", "items": [ { "object": "participant_result", "contactId": "+584241112233", "error": null, "inviteCode": null } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/participants/remove": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "post": { "tags": [ "Groups" ], "operationId": "removeGroupParticipants", "summary": "Remove participants", "description": "Remove contacts from the group. Each contact gets its own result.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIdsRequest" }, "example": { "contactIds": [ "+584241112233" ] } } } }, "responses": { "200": { "description": "One result per contact.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResultList" }, "example": { "object": "list", "items": [ { "object": "participant_result", "contactId": "+584241112233", "error": null, "inviteCode": null } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/participants/promote": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "post": { "tags": [ "Groups" ], "operationId": "promoteGroupParticipants", "summary": "Promote participants", "description": "Make participants admins. Each contact gets its own result.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIdsRequest" }, "example": { "contactIds": [ "+584241112233" ] } } } }, "responses": { "200": { "description": "One result per contact.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResultList" }, "example": { "object": "list", "items": [ { "object": "participant_result", "contactId": "+584241112233", "error": null, "inviteCode": null } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/participants/demote": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "post": { "tags": [ "Groups" ], "operationId": "demoteGroupParticipants", "summary": "Demote participants", "description": "Make admins regular participants. Each contact gets its own result.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIdsRequest" }, "example": { "contactIds": [ "+584241112233" ] } } } }, "responses": { "200": { "description": "One result per contact.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResultList" }, "example": { "object": "list", "items": [ { "object": "participant_result", "contactId": "+584241112233", "error": null, "inviteCode": null } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/invite-link": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "get": { "tags": [ "Groups" ], "operationId": "getGroupInviteLink", "summary": "Get the invite link", "description": "The group's current invite link. Admins only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The link.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInviteLink" }, "example": { "object": "group_invite_link", "groupId": "120363041234567890@g.us", "url": "https://chat.whatsapp.com/AbCdEf123456" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/invite-link/reset": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "post": { "tags": [ "Groups" ], "operationId": "resetGroupInviteLink", "summary": "Reset the invite link", "description": "Revoke the current invite link and return a new one. Admins only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The new link.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInviteLink" }, "example": { "object": "group_invite_link", "groupId": "120363041234567890@g.us", "url": "https://chat.whatsapp.com/AbCdEf123456" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/picture": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "put": { "tags": [ "Groups" ], "operationId": "setGroupPicture", "summary": "Set a group's picture", "description": "JPEG. Admins only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PictureUploadRequest" }, "example": { "url": "https://example.com/group.jpg" } } } }, "responses": { "200": { "description": "The new picture.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Picture" }, "example": { "object": "picture", "id": "1727164540", "url": null, "preview": false } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "delete": { "tags": [ "Groups" ], "operationId": "deleteGroupPicture", "summary": "Delete a group's picture", "description": "Admins only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Deleted.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/join-requests": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "get": { "tags": [ "Groups" ], "operationId": "listGroupJoinRequests", "summary": "List join requests", "description": "Pending requests to join the group. Admins only.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of requests.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupJoinRequestItemList" }, "example": { "object": "list", "items": [ { "object": "group_join_request", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "groupId": "120363041234567890@g.us", "contactId": "+584241112233", "requestedAt": "2026-09-24T08:15:40.000Z" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/join-requests/approve": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "post": { "tags": [ "Groups" ], "operationId": "approveGroupJoinRequests", "summary": "Approve join requests", "description": "Approve pending requests. Admins only. Each contact gets its own result.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIdsRequest" }, "example": { "contactIds": [ "+584241112233" ] } } } }, "responses": { "200": { "description": "One result per contact.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResultList" }, "example": { "object": "list", "items": [ { "object": "participant_result", "contactId": "+584241112233", "error": null, "inviteCode": null } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/join-requests/reject": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "post": { "tags": [ "Groups" ], "operationId": "rejectGroupJoinRequests", "summary": "Reject join requests", "description": "Reject pending requests. Admins only. Each contact gets its own result.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIdsRequest" }, "example": { "contactIds": [ "+584241112233" ] } } } }, "responses": { "200": { "description": "One result per contact.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantResultList" }, "example": { "object": "list", "items": [ { "object": "participant_result", "contactId": "+584241112233", "error": null, "inviteCode": null } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/subgroups": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "get": { "tags": [ "Communities" ], "operationId": "listSubgroups", "summary": "List a community's groups", "description": "Groups linked to the community.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of groups.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubgroupList" }, "example": { "object": "list", "items": [ { "object": "subgroup", "id": "120363055512345678@g.us", "name": "Announcements", "default": true } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "post": { "tags": [ "Communities" ], "operationId": "linkSubgroup", "summary": "Link a group to a community", "description": "Admins of both only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubgroupLinkRequest" }, "example": { "groupId": "120363055512345678@g.us" } } } }, "responses": { "204": { "description": "Linked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/subgroups/{subgroupId}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" }, { "$ref": "#/components/parameters/SubgroupId" } ], "delete": { "tags": [ "Communities" ], "operationId": "unlinkSubgroup", "summary": "Unlink a group from a community", "description": "Admins only.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Unlinked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/groups/{groupId}/community-participants": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/GroupId" } ], "get": { "tags": [ "Communities" ], "operationId": "listCommunityParticipants", "summary": "List a community's members", "description": "Members across the community's linked groups.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of members.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityParticipantList" }, "example": { "object": "list", "items": [ { "object": "community_participant", "contactId": "+584241112233" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `group_not_found`: WhatsApp does not know the group.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "group_not_found": { "summary": "group_not_found", "value": { "code": "group_not_found", "message": "Group not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "get": { "tags": [ "Channels" ], "operationId": "listChannels", "summary": "List followed channels", "description": "Channels the account follows, read live from WhatsApp.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of channels.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelList" }, "example": { "object": "list", "items": [ { "object": "channel", "id": "120363198765432101@newsletter", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Acme News", "description": "Product updates.", "inviteCode": "0029VaABCDEFghijKLmn1234", "subscriberCount": 1204, "verified": false, "status": "active", "role": "owner", "muted": false, "pictureUrl": null, "previewUrl": null, "createdAt": "2026-08-02T10:00:00.000Z" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } }, "post": { "tags": [ "Channels" ], "operationId": "createChannel", "summary": "Create a channel", "description": "The account becomes its owner. Post to it with `POST /v1/messages` and `to` set to its id.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelCreateRequest" }, "example": { "name": "Acme News", "description": "Product updates." } } } }, "responses": { "201": { "description": "Created.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" }, "example": { "object": "channel", "id": "120363198765432101@newsletter", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Acme News", "description": "Product updates.", "inviteCode": "0029VaABCDEFghijKLmn1234", "subscriberCount": 1204, "verified": false, "status": "active", "role": "owner", "muted": false, "pictureUrl": null, "previewUrl": null, "createdAt": "2026-08-02T10:00:00.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels/invites/{code}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/InviteCode" } ], "get": { "tags": [ "Channels" ], "operationId": "getChannelInvite", "summary": "Preview a channel invite", "description": "The channel behind an invite code.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The channel.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" }, "example": { "object": "channel", "id": "120363198765432101@newsletter", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Acme News", "description": "Product updates.", "inviteCode": "0029VaABCDEFghijKLmn1234", "subscriberCount": 1204, "verified": false, "status": "active", "role": "owner", "muted": false, "pictureUrl": null, "previewUrl": null, "createdAt": "2026-08-02T10:00:00.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `invite_not_found`: The invite code was revoked or does not exist.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "invite_not_found": { "summary": "invite_not_found", "value": { "code": "invite_not_found", "message": "The invite link was revoked or does not exist." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels/{channelId}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChannelId" } ], "get": { "tags": [ "Channels" ], "operationId": "getChannel", "summary": "Get a channel", "description": "A channel, read live from WhatsApp.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The channel.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" }, "example": { "object": "channel", "id": "120363198765432101@newsletter", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Acme News", "description": "Product updates.", "inviteCode": "0029VaABCDEFghijKLmn1234", "subscriberCount": 1204, "verified": false, "status": "active", "role": "owner", "muted": false, "pictureUrl": null, "previewUrl": null, "createdAt": "2026-08-02T10:00:00.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels/{channelId}/follow": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChannelId" } ], "post": { "tags": [ "Channels" ], "operationId": "followChannel", "summary": "Follow a channel", "description": "Start receiving the channel's messages.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels/{channelId}/unfollow": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChannelId" } ], "post": { "tags": [ "Channels" ], "operationId": "unfollowChannel", "summary": "Unfollow a channel", "description": "Stop following the channel.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels/{channelId}/mute": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChannelId" } ], "post": { "tags": [ "Channels" ], "operationId": "muteChannel", "summary": "Mute a channel", "description": "Mute the channel's notifications.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels/{channelId}/unmute": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChannelId" } ], "post": { "tags": [ "Channels" ], "operationId": "unmuteChannel", "summary": "Unmute a channel", "description": "Turn the channel's notifications back on.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels/{channelId}/messages": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChannelId" } ], "get": { "tags": [ "Channels" ], "operationId": "listChannelMessages", "summary": "List a channel's messages", "description": "Messages in the channel, newest first, read live from WhatsApp.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of messages.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelMessageList" }, "example": { "object": "list", "items": [ { "object": "channel_message", "id": "142", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "channelId": "120363198765432101@newsletter", "type": "text", "text": "Version 2.4 is out.", "viewCount": 860, "reactions": { "🎉": 41 }, "sentAt": "2026-09-24T08:15:40.000Z" } ], "nextCursor": "142" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels/{channelId}/messages/{channelMessageId}/react": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChannelId" }, { "$ref": "#/components/parameters/ChannelMessageId" } ], "post": { "tags": [ "Channels" ], "operationId": "reactToChannelMessage", "summary": "React to a channel message", "description": "An empty `emoji` removes the reaction.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactRequest" }, "example": { "emoji": "🎉" } } } }, "responses": { "204": { "description": "Sent.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/accounts/{accountId}/channels/{channelId}/mark-viewed": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ChannelId" } ], "post": { "tags": [ "Channels" ], "operationId": "markChannelMessagesViewed", "summary": "Mark channel messages viewed", "description": "Count the account as a viewer of these messages.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkViewedRequest" }, "example": { "channelMessageIds": [ "141", "142" ] } } } }, "responses": { "204": { "description": "Done.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `not_supported`: WhatsApp cannot do this for this account: labels on a consumer account, presence subscriptions without extended events.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "not_supported": { "summary": "not_supported", "value": { "code": "not_supported", "message": "Labels need a WhatsApp Business account." } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `whatsapp_forbidden`: WhatsApp refused: the account is not a member, not an admin, or not allowed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "whatsapp_forbidden": { "summary": "whatsapp_forbidden", "value": { "code": "whatsapp_forbidden", "message": "Only group admins can do this." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.\n- `channel_not_found`: WhatsApp does not know the channel.\n- `whatsapp_not_found`: WhatsApp does not know the target.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } }, "channel_not_found": { "summary": "channel_not_found", "value": { "code": "channel_not_found", "message": "Channel not found." } }, "whatsapp_not_found": { "summary": "whatsapp_not_found", "value": { "code": "whatsapp_not_found", "message": "Not found on WhatsApp." } } } } } }, "409": { "description": "Conflict.\n\n- `account_not_ready`: The account is not connected (`status` is not `ready`). `details.status` is its current status when wuapi knows it.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_ready": { "summary": "account_not_ready", "value": { "code": "account_not_ready", "message": "The account is not connected. Link it by QR code or pairing code and wait for status ready.", "details": { "status": "disconnected" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } }, "500": { "description": "Internal error.\n\n- `internal_error`: Something failed unexpectedly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "code": "internal_error", "message": "Something went wrong on our side." } } } } } }, "502": { "description": "WhatsApp failed.\n\n- `whatsapp_error`: WhatsApp failed the operation. Retrying may work.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whatsapp_error": { "summary": "whatsapp_error", "value": { "code": "whatsapp_error", "message": "WhatsApp failed the operation: timed out." } } } } } }, "503": { "description": "Engine unavailable.\n\n- `engine_unavailable`: The WhatsApp engine is unreachable. Retry shortly.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "engine_unavailable": { "summary": "engine_unavailable", "value": { "code": "engine_unavailable", "message": "The WhatsApp engine is unreachable. Retry shortly." } } } } } } } } }, "/v1/webhook-endpoints": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "Endpoints in scope. Secrets are never included.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/ProjectFilter" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of endpoints.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" }, "example": { "object": "list", "items": [ { "object": "webhook_endpoint", "id": "n97p31n8b5c7z2y4u6ebt5gr1ew3qa8s", "projectId": null, "url": "https://example.com/webhooks/wuapi", "events": [ "message.received", "account.disconnected" ], "active": true, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-20T14:00:03.000Z" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "At most 5 organization endpoints and 5 per project; one more answers `400 invalid_request`. The `secret` is returned only here and by rotate-secret.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreateRequest" }, "example": { "url": "https://example.com/webhooks/wuapi", "events": [ "message.received", "account.disconnected" ] } } } }, "responses": { "201": { "description": "Created.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "n97p31n8b5c7z2y4u6ebt5gr1ew3qa8s", "projectId": null, "url": "https://example.com/webhooks/wuapi", "events": [ "message.received", "account.disconnected" ], "active": true, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-20T14:00:03.000Z", "secret": "whsec_3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } } } } } }, "409": { "description": "Conflict.\n\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/webhook-endpoints/{webhookEndpointId}": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookEndpoint", "summary": "Get a webhook endpoint", "description": "The endpoint, without its secret.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The endpoint.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "n97p31n8b5c7z2y4u6ebt5gr1ew3qa8s", "projectId": null, "url": "https://example.com/webhooks/wuapi", "events": [ "message.received", "account.disconnected" ], "active": true, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-20T14:00:03.000Z" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Change the URL, the events, or pause it with `active: false`.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdateRequest" }, "example": { "active": false } } } }, "responses": { "200": { "description": "The endpoint.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "n97p31n8b5c7z2y4u6ebt5gr1ew3qa8s", "projectId": null, "url": "https://example.com/webhooks/wuapi", "events": [ "message.received", "account.disconnected" ], "active": false, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-20T14:00:03.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Stop delivering to it.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "204": { "description": "Deleted.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/webhook-endpoints/{webhookEndpointId}/rotate-secret": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookEndpointSecret", "summary": "Rotate the signing secret", "description": "A new `secret` replaces the old one, which stops working at once.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The endpoint with its new secret.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "n97p31n8b5c7z2y4u6ebt5gr1ew3qa8s", "projectId": null, "url": "https://example.com/webhooks/wuapi", "events": [ "message.received", "account.disconnected" ], "active": true, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-20T14:00:03.000Z", "secret": "whsec_3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/projects": { "post": { "tags": [ "Projects" ], "operationId": "createProject", "summary": "Create a project", "description": "Fires `project.created`. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreateRequest" }, "example": { "name": "Northwind Dental", "externalId": "customer_8812", "metadata": { "plan": "growth" }, "maxAccounts": 3 } } } }, "responses": { "201": { "description": "Created.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "object": "project", "id": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "name": "Northwind Dental", "externalId": "customer_8812", "metadata": { "plan": "growth" }, "status": "active", "maxAccounts": 3, "accountCount": 1, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "409": { "description": "Conflict.\n\n- `already_exists`: A project with this `externalId` already exists (`details.projectId`).\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "already_exists": { "summary": "already_exists", "value": { "code": "already_exists", "message": "A project with this externalId already exists.", "details": { "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v" } } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "get": { "tags": [ "Projects" ], "operationId": "listProjects", "summary": "List projects", "description": "Live projects, newest first. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "externalId", "in": "query", "required": false, "description": "Exact match.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Only projects with this status.", "schema": { "$ref": "#/components/schemas/ProjectStatus" } } ], "responses": { "200": { "description": "A page of projects.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" }, "example": { "object": "list", "items": [ { "object": "project", "id": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "name": "Northwind Dental", "externalId": "customer_8812", "metadata": { "plan": "growth" }, "status": "active", "maxAccounts": 3, "accountCount": 1, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/projects/{projectId}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "get": { "tags": [ "Projects" ], "operationId": "getProject", "summary": "Get a project", "description": "A project, by id or `ext:`. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "responses": { "200": { "description": "The project.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "object": "project", "id": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "name": "Northwind Dental", "externalId": "customer_8812", "metadata": { "plan": "growth" }, "status": "active", "maxAccounts": 3, "accountCount": 1, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "patch": { "tags": [ "Projects" ], "operationId": "updateProject", "summary": "Update, suspend or resume a project", "description": "`status: suspended` refuses every send and write in the project (`403 project_suspended`) while reads and inbound keep working. Fires `project.updated`. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdateRequest" }, "example": { "status": "suspended" } } } }, "responses": { "200": { "description": "The project.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "object": "project", "id": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "name": "Northwind Dental", "externalId": "customer_8812", "metadata": { "plan": "growth" }, "status": "suspended", "maxAccounts": 3, "accountCount": 1, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `already_exists`: A project with this `externalId` already exists (`details.projectId`).", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "already_exists": { "summary": "already_exists", "value": { "code": "already_exists", "message": "A project with this externalId already exists.", "details": { "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v" } } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "delete": { "tags": [ "Projects" ], "operationId": "deleteProject", "summary": "Delete a project", "description": "Answers at once: from then on the project is 404, its keys answer 401 and its `externalId` can be reused. In the background its accounts are logged out and deleted, then its webhook endpoints removed, and `project.deleted` fires. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "responses": { "204": { "description": "Deleted.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/projects/{projectId}/api-keys": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "get": { "tags": [ "Projects" ], "operationId": "listProjectApiKeys", "summary": "List a project's API keys", "description": "Every key of the project, revoked ones included. Never the key itself. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of keys.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" }, "example": { "object": "list", "items": [ { "object": "api_key", "id": "j48c2d5e8f1g4h7i0k3l6m9n2p5q8r1s", "name": "Northwind production", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "keyPrefix": "wu_live_9c9c", "last4": "9c9c", "createdAt": "2026-09-24T08:15:40.000Z", "lastUsedAt": null, "revokedAt": null } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "post": { "tags": [ "Projects" ], "operationId": "createProjectApiKey", "summary": "Create a project API key", "description": "A key that reaches only this project's resources. At most 20 active keys per project. The `key` is shown only here. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" }, "example": { "name": "Northwind production" } } } }, "responses": { "201": { "description": "Created.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" }, "example": { "object": "api_key", "id": "j48c2d5e8f1g4h7i0k3l6m9n2p5q8r1s", "name": "Northwind production", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "keyPrefix": "wu_live_9c9c", "last4": "9c9c", "createdAt": "2026-09-24T08:15:40.000Z", "lastUsedAt": null, "revokedAt": null, "key": "wu_live_9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/projects/{projectId}/api-keys/{apiKeyId}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ApiKeyId" } ], "delete": { "tags": [ "Projects" ], "operationId": "revokeProjectApiKey", "summary": "Revoke a project API key", "description": "The key stops working at once. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "responses": { "204": { "description": "Revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/projects/{projectId}/usage": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "get": { "tags": [ "Projects" ], "operationId": "getProjectUsage", "summary": "Get a project's usage", "description": "The project's usage for `month`. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "parameters": [ { "$ref": "#/components/parameters/Month" } ], "responses": { "200": { "description": "The usage.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUsage" }, "example": { "object": "project_usage", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "period": { "startsAt": "2026-09-01T00:00:00.000Z", "endsAt": "2026-10-01T00:00:00.000Z" }, "billableAccountCount": 1, "accountCount": 1, "proxyBytes": 52428800, "sentMessageCount": 812, "receivedMessageCount": 1290 } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/invitations": { "post": { "tags": [ "Invitations" ], "operationId": "createInvitation", "summary": "Create an invitation", "description": "A hosted page (`url`) where someone else links their own WhatsApp into your project: they pick where the number's proxy exits (unless you set `proxyLocation`), then scan a QR code or type a pairing code. The account is created in the project when they start, and `invitation.status_changed` fires at each step. With `inviteeEmail`, the invitation is emailed when email is enabled (`emailSentAt`).", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreateRequest" }, "examples": { "email": { "summary": "email", "value": { "projectId": "ext:customer_8812", "inviteeName": "Maria Perez", "inviteeEmail": "maria@example.com", "accountName": "Front desk", "proxyLocation": { "country": "MX", "city": "mexicocity" }, "returnUrl": "https://app.example.com/settings/whatsapp", "metadata": { "store": "cdmx-2" } } }, "pairingCodeOnly": { "summary": "pairingCodeOnly", "value": { "inviteePhone": "+525512345678", "methods": [ "pairing_code" ], "expiresInDays": 1 } } } } } }, "responses": { "201": { "description": "Created. `url` is returned only here and on resend.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" }, "example": { "object": "invitation", "id": "q64x2v7b1n9m3c8z5a0s4d6f2g7h1j3k", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "status": "pending", "url": "https://wuapi.dev/invite/9f2c6a1e0b7d4c3a8e5f1b2d7c9a0e4f6b8d1c3a5e7f9b0d2c4e6a8b1d3f5a7c", "inviteeName": "Maria Perez", "inviteeEmail": "maria@example.com", "inviteePhone": null, "suggestedCountry": "MX", "proxyLocation": { "country": "MX", "city": "mexicocity", "strictCity": false }, "methods": [ "qr_code", "pairing_code" ], "historySync": "none", "accountName": "Front desk", "accountId": null, "failureReason": null, "returnUrl": "https://app.example.com/settings/whatsapp", "metadata": { "store": "cdmx-2" }, "emailSentAt": "2026-09-24T08:15:40.000Z", "expiresAt": "2026-10-01T08:15:40.000Z", "viewedAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.\n- `unsupported_proxy_location`: `proxyLocation` names a country or city that is not in `GET /v1/proxy-locations`.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } }, "unsupported_proxy_location": { "summary": "unsupported_proxy_location", "value": { "code": "unsupported_proxy_location", "message": "Santiago, CL is not a supported proxy location. See GET /v1/proxy-locations.", "details": { "field": "proxyLocation" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "402": { "description": "Payment required: an upgrade or a subscription.\n\n- `upgrade_required`: The Free plan includes 1 connected account and it is taken. Upgrade in Billing to invite more. `details` has `maxAccounts` and `upgradeUrl`.\n- `free_limit_reached`: The Free plan's monthly limit is reached (2,000 messages sent and received, or 0.5 GB of proxy traffic). The organization's accounts are paused (`disconnectReason: free_limit_reached`, the device stays linked) and sends, new accounts and reconnects are refused until the month ends (UTC) or the organization upgrades; then they reconnect on their own. `details` has `limit` (`messages` or `proxy`), `month`, `resetsAt` and `upgradeUrl`.\n- `subscription_required`: The subscription is past due, so no new account can be linked until it is paid. `details.billingUrl` links to Billing.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upgrade_required": { "summary": "upgrade_required", "value": { "code": "upgrade_required", "message": "The Free plan includes 1 connected number. Upgrade in Billing to connect more.", "details": { "maxAccounts": 1, "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "free_limit_reached": { "summary": "free_limit_reached", "value": { "code": "free_limit_reached", "message": "This organization reached the Free plan's 2,000 messages for this month. Its numbers are paused until the month ends; upgrade in Billing to resume now.", "details": { "limit": "messages", "month": "2026-09", "resetsAt": "2026-10-01T00:00:00.000Z", "upgradeUrl": "https://wuapi.dev/app/billing" } } }, "subscription_required": { "summary": "subscription_required", "value": { "code": "subscription_required", "message": "The subscription is past due. Pay the open invoice in Billing to connect accounts.", "details": { "billingUrl": "https://wuapi.dev/app/billing" } } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.\n- `project_limit_reached`: The project already has `maxAccounts` accounts.\n- `trial_account_limit`: Legacy free trials only (new organizations start on the Free plan): the trial includes one connected account until it converts. `details.upgradeUrl` links to Billing.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } }, "project_limit_reached": { "summary": "project_limit_reached", "value": { "code": "project_limit_reached", "message": "This project already has its maximum of 3 account(s).", "details": { "maxAccounts": 3 } } }, "trial_account_limit": { "summary": "trial_account_limit (legacy trial)", "value": { "code": "trial_account_limit", "message": "The free trial includes 1 connected account until it converts.", "details": { "maxAccounts": 1, "upgradeUrl": "https://wuapi.dev/app/billing" } } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } } } } } }, "409": { "description": "Conflict.\n\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "get": { "tags": [ "Invitations" ], "operationId": "listInvitations", "summary": "List invitations", "description": "Invitations in scope, newest first. `url` is always `null` here.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only this status.", "schema": { "$ref": "#/components/schemas/InvitationStatus" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/ProjectFilter" }, { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "A page of invitations.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationList" }, "example": { "object": "list", "items": [ { "object": "invitation", "id": "q64x2v7b1n9m3c8z5a0s4d6f2g7h1j3k", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "status": "completed", "url": null, "inviteeName": "Maria Perez", "inviteeEmail": "maria@example.com", "inviteePhone": null, "suggestedCountry": "MX", "proxyLocation": { "country": "MX", "city": "mexicocity", "strictCity": false }, "methods": [ "qr_code", "pairing_code" ], "historySync": "none", "accountName": "Front desk", "accountId": "k51c7w3xq9t2m8zr4d6hy0ne5b1p8sva", "failureReason": null, "returnUrl": "https://app.example.com/settings/whatsapp", "metadata": { "store": "cdmx-2" }, "emailSentAt": "2026-09-24T08:15:40.000Z", "expiresAt": "2026-10-01T08:15:40.000Z", "viewedAt": "2026-09-24T08:20:02.000Z", "startedAt": "2026-09-24T08:20:31.000Z", "completedAt": "2026-09-24T08:22:10.000Z", "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:22:10.000Z" } ], "nextCursor": null } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/invitations/{invitationId}": { "parameters": [ { "$ref": "#/components/parameters/InvitationId" } ], "get": { "tags": [ "Invitations" ], "operationId": "getInvitation", "summary": "Get an invitation", "description": "`url` is always `null` here.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" } ], "responses": { "200": { "description": "The invitation.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" }, "example": { "object": "invitation", "id": "q64x2v7b1n9m3c8z5a0s4d6f2g7h1j3k", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "status": "completed", "url": null, "inviteeName": "Maria Perez", "inviteeEmail": "maria@example.com", "inviteePhone": null, "suggestedCountry": "MX", "proxyLocation": { "country": "MX", "city": "mexicocity", "strictCity": false }, "methods": [ "qr_code", "pairing_code" ], "historySync": "none", "accountName": "Front desk", "accountId": "k51c7w3xq9t2m8zr4d6hy0ne5b1p8sva", "failureReason": null, "returnUrl": "https://app.example.com/settings/whatsapp", "metadata": { "store": "cdmx-2" }, "emailSentAt": "2026-09-24T08:15:40.000Z", "expiresAt": "2026-10-01T08:15:40.000Z", "viewedAt": "2026-09-24T08:20:02.000Z", "startedAt": "2026-09-24T08:20:31.000Z", "completedAt": "2026-09-24T08:22:10.000Z", "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:22:10.000Z" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/invitations/{invitationId}/cancel": { "parameters": [ { "$ref": "#/components/parameters/InvitationId" } ], "post": { "tags": [ "Invitations" ], "operationId": "cancelInvitation", "summary": "Cancel an invitation", "description": "The link stops working. Cancelling a cancelled invitation changes nothing. An account the invitee already started stays in the project, unlinked.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The cancelled invitation.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" }, "example": { "object": "invitation", "id": "q64x2v7b1n9m3c8z5a0s4d6f2g7h1j3k", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "status": "cancelled", "url": null, "inviteeName": "Maria Perez", "inviteeEmail": "maria@example.com", "inviteePhone": null, "suggestedCountry": "MX", "proxyLocation": { "country": "MX", "city": "mexicocity", "strictCity": false }, "methods": [ "qr_code", "pairing_code" ], "historySync": "none", "accountName": "Front desk", "accountId": null, "failureReason": null, "returnUrl": "https://app.example.com/settings/whatsapp", "metadata": { "store": "cdmx-2" }, "emailSentAt": "2026-09-24T08:15:40.000Z", "expiresAt": "2026-10-01T08:15:40.000Z", "viewedAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `already_completed`: The invitation is completed, so it cannot be cancelled or resent.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "already_completed": { "summary": "already_completed", "value": { "code": "already_completed", "message": "The invitation is completed; there is nothing to cancel." } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/invitations/{invitationId}/resend": { "parameters": [ { "$ref": "#/components/parameters/InvitationId" } ], "post": { "tags": [ "Invitations" ], "operationId": "resendInvitation", "summary": "Resend an invitation", "description": "Rotates the token (the old `url` stops working), moves the invitation back to `pending` with a new expiry of the same length, and emails it again when it has an `inviteeEmail`. An account the invitee started is kept, so they resume where they left off.", "parameters": [ { "$ref": "#/components/parameters/WuapiProject" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The invitation with its new `url`.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Original-Request": { "$ref": "#/components/headers/OriginalRequest" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" }, "example": { "object": "invitation", "id": "q64x2v7b1n9m3c8z5a0s4d6f2g7h1j3k", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "status": "pending", "url": "https://wuapi.dev/invite/9f2c6a1e0b7d4c3a8e5f1b2d7c9a0e4f6b8d1c3a5e7f9b0d2c4e6a8b1d3f5a7c", "inviteeName": "Maria Perez", "inviteeEmail": "maria@example.com", "inviteePhone": null, "suggestedCountry": "MX", "proxyLocation": { "country": "MX", "city": "mexicocity", "strictCity": false }, "methods": [ "qr_code", "pairing_code" ], "historySync": "none", "accountName": "Front desk", "accountId": null, "failureReason": null, "returnUrl": "https://app.example.com/settings/whatsapp", "metadata": { "store": "cdmx-2" }, "emailSentAt": "2026-09-24T08:15:40.000Z", "expiresAt": "2026-10-01T08:15:40.000Z", "viewedAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.\n- `project_suspended`: The resource belongs to a suspended project. Reads keep working; writes are refused until it is resumed.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } }, "project_suspended": { "summary": "project_suspended", "value": { "code": "project_suspended", "message": "This project is suspended. Reads keep working; sends and changes are refused until it is resumed." } } } } } }, "404": { "description": "Not found.\n\n- `project_not_found`: No live project in this organization matches `Wuapi-Project` or the `projectId` given.\n- `not_found`: The route does not exist, or the resource does not exist or is outside the key's scope. Another project's ids answer 404, never 403.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "project_not_found": { "summary": "project_not_found", "value": { "code": "project_not_found", "message": "No project in this organization matches Wuapi-Project." } }, "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Account not found." } } } } } }, "409": { "description": "Conflict.\n\n- `already_completed`: The invitation is completed, so it cannot be cancelled or resent.\n- `idempotency_conflict`: The `Idempotency-Key` belongs to a request still running, or was used with a different method, path or body.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "already_completed": { "summary": "already_completed", "value": { "code": "already_completed", "message": "The invitation is completed; there is nothing to cancel." } }, "idempotency_conflict": { "summary": "idempotency_conflict", "value": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used with a different request." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } }, "/v1/branding": { "get": { "tags": [ "Branding" ], "operationId": "getBranding", "summary": "Get branding", "description": "What the invitation page and email show. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "responses": { "200": { "description": "The branding. Fields are `null` until set.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branding" }, "example": { "object": "branding", "displayName": "Northwind Cloud", "logoUrl": "https://cdn.example.com/logo.png", "accentColor": "#0F766E", "supportUrl": "https://help.example.com", "hideWuapiBranding": true } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } }, "patch": { "tags": [ "Branding" ], "operationId": "updateBranding", "summary": "Update branding", "description": "`displayName` is required the first time. Without an accent color the page uses wuapi's own. `hideWuapiBranding: true` needs the White label add-on ($100/month): without it the call answers `402 addon_required` and changes nothing. Organization keys only (project keys get `403 forbidden`); the `Wuapi-Project` header does not change the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingUpdateRequest" }, "example": { "displayName": "Northwind Cloud", "logoUrl": "https://cdn.example.com/logo.png", "accentColor": "#0F766E", "supportUrl": "https://help.example.com", "hideWuapiBranding": true } } } }, "responses": { "200": { "description": "The branding.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branding" }, "example": { "object": "branding", "displayName": "Northwind Cloud", "logoUrl": "https://cdn.example.com/logo.png", "accentColor": "#0F766E", "supportUrl": "https://help.example.com", "hideWuapiBranding": true } } } }, "400": { "description": "Invalid request.\n\n- `invalid_request`: The body, a query or path parameter, or the cursor is invalid. `details.field` names the field when there is one.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "message": "`text` is required.", "details": { "field": "text" } } } } } } }, "401": { "description": "Unauthorized.\n\n- `unauthorized`: The API key is missing, malformed or revoked.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } } }, "402": { "description": "Payment required: a subscription or an add-on.\n\n- `addon_required`: `hideWuapiBranding: true` needs the White label add-on ($100/month on the usage subscription).", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "addon_required": { "summary": "addon_required", "value": { "code": "addon_required", "message": "Hiding the wuapi branding needs the White label add-on ($100/month). Add it from Billing or Branding in the dashboard.", "details": { "addon": "white_label", "priceCents": 10000 } } } } } } }, "403": { "description": "Forbidden.\n\n- `forbidden`: The key cannot reach this: a project key naming another project in `Wuapi-Project` or `projectId`, or a project key on an organization-only route.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "This API key belongs to another project than the one in Wuapi-Project." } } } } } }, "429": { "description": "Rate limited. Wait the number of seconds in `Retry-After`.\n\n- `rate_limited`: 600 requests per minute per API key, or WhatsApp is pacing this account. Wait `Retry-After` seconds.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "message": "Too many requests. The limit is 600 per minute per API key." } } } } } } } } } }, "webhooks": { "event": { "post": { "tags": [ "Webhooks" ], "operationId": "receiveEvent", "summary": "Receive an event", "description": "What wuapi sends to your webhook endpoints. Answer 2xx within 10 seconds.", "security": [], "parameters": [ { "name": "Wuapi-Signature", "in": "header", "required": true, "description": "`t=,v1=.\">`.", "schema": { "type": "string" } }, { "name": "Wuapi-Event-Id", "in": "header", "required": true, "description": "The event `id`.", "schema": { "type": "string" } }, { "name": "Wuapi-Event-Type", "in": "header", "required": true, "description": "The event `type`.", "schema": { "$ref": "#/components/schemas/WebhookEventType" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered." }, "4XX": { "description": "Anything else is retried." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key: `wu_live_` followed by 48 hex characters." } }, "headers": { "RequestId": { "description": "Request id (`req_`). Quote it when you contact support.", "schema": { "type": "string", "example": "req_4f1c2a9b8e7d6c5b4a3f2e1d" } }, "RateLimitLimit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer", "example": 600 } }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "example": 597 } }, "RateLimitReset": { "description": "Seconds until the window resets.", "schema": { "type": "integer", "example": 42 } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 12 } }, "IdempotentReplayed": { "description": "`true` when this response is a replay of an earlier request with the same `Idempotency-Key`.", "schema": { "type": "string", "enum": [ "true" ] } }, "OriginalRequest": { "description": "On a replay: the `x-request-id` of the request that produced the stored response. Absent when that request predates this header.", "schema": { "type": "string", "example": "req_4f1c2a9b8e7d6c5b4a3f2e1d" } } }, "parameters": { "AccountId": { "name": "accountId", "in": "path", "required": true, "description": "Account ID.", "schema": { "type": "string" }, "example": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr" }, "MessageId": { "name": "messageId", "in": "path", "required": true, "description": "Message ID (a wuapi id, not WhatsApp's).", "schema": { "type": "string" }, "example": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e" }, "GroupId": { "name": "groupId", "in": "path", "required": true, "description": "Group id, for example `120363041234567890@g.us`. URL-encode `@` as `%40` if your client does not.", "schema": { "type": "string" }, "example": "120363041234567890@g.us" }, "SubgroupId": { "name": "subgroupId", "in": "path", "required": true, "description": "Id of the group to unlink from the community (`...@g.us`).", "schema": { "type": "string" }, "example": "120363055512345678@g.us" }, "ChatId": { "name": "chatId", "in": "path", "required": true, "description": "The chat: a contact id (`+584241112233`, bare digits, or `lid:`), a group id or a channel id.", "schema": { "type": "string" }, "example": "+584241112233" }, "ContactId": { "name": "contactId", "in": "path", "required": true, "description": "The contact: an E.164 number (`+584241112233`), bare digits, or `lid:`.", "schema": { "type": "string" }, "example": "+584241112233" }, "LabelId": { "name": "labelId", "in": "path", "required": true, "description": "Label ID as WhatsApp numbers them (1 to 64 characters). Reuse an id to edit that label.", "schema": { "type": "string" }, "example": "5" }, "CallId": { "name": "callId", "in": "path", "required": true, "description": "Call ID, from the `call.received` event.", "schema": { "type": "string" }, "example": "3EB0C4A1F2D7B96E5A10" }, "StickerPackId": { "name": "stickerPackId", "in": "path", "required": true, "description": "Sticker pack ID.", "schema": { "type": "string" }, "example": "4a0b1c2d-sticker-pack" }, "OrderId": { "name": "orderId", "in": "path", "required": true, "description": "Order ID from an inbound order message.", "schema": { "type": "string" }, "example": "1234567890123456" }, "ChannelId": { "name": "channelId", "in": "path", "required": true, "description": "Channel id, `@newsletter`.", "schema": { "type": "string" }, "example": "120363198765432101@newsletter" }, "InviteCode": { "name": "code", "in": "path", "required": true, "description": "The code from an invite link (`https://chat.whatsapp.com/` or `https://whatsapp.com/channel/`).", "schema": { "type": "string" }, "example": "AbCdEf123456" }, "ChannelMessageId": { "name": "channelMessageId", "in": "path", "required": true, "description": "The channel message's `id`, from `GET .../channels/{channelId}/messages` or `channel.message_received`.", "schema": { "type": "string" }, "example": "142" }, "WebhookEndpointId": { "name": "webhookEndpointId", "in": "path", "required": true, "description": "Webhook endpoint ID.", "schema": { "type": "string" }, "example": "n97p31n8b5c7z2y4u6ebt5gr1ew3qa8s" }, "ProjectId": { "name": "projectId", "in": "path", "required": true, "description": "Project ID, or `ext:` to address it by your own id.", "schema": { "type": "string" }, "example": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v" }, "ApiKeyId": { "name": "apiKeyId", "in": "path", "required": true, "description": "API key ID.", "schema": { "type": "string" }, "example": "j48c2d5e8f1g4h7i0k3l6m9n2p5q8r1s" }, "InvitationId": { "name": "invitationId", "in": "path", "required": true, "description": "Invitation ID.", "schema": { "type": "string" }, "example": "q64x2v7b1n9m3c8z5a0s4d6f2g7h1j3k" }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous page's `nextCursor`. An invalid or expired cursor answers `400 invalid_request`.", "schema": { "type": "string" } }, "ProjectFilter": { "name": "projectId", "in": "query", "required": false, "description": "Filter by project: a project id, `ext:`, or `none` for resources in no project. With an organization scope and no filter, the list covers every project and the unassigned resources. With a project scope the list is always that project's; naming another project answers `403 forbidden`. An unknown project answers `404 project_not_found`.", "schema": { "type": "string" }, "example": "ext:customer_8812" }, "Month": { "name": "month", "in": "query", "required": false, "description": "Month in UTC as `YYYY-MM`. Defaults to the current month. Selects the month of `proxyBytes`, `sentMessageCount` and `receivedMessageCount`; `accountCount` and `billableAccountCount` are always current counts.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "example": "2026-09" }, "WuapiProject": { "name": "Wuapi-Project", "in": "header", "required": false, "description": "Act inside one project: its id, or `ext:`. At most 200 characters.\n\n| Credential | `Wuapi-Project` | Scope |\n|---|---|---|\n| Organization key | absent | the whole organization: every project and the unassigned resources |\n| Organization key | a project of this organization | that project only (`404 project_not_found` when no live project matches) |\n| Project key | absent, or its own project | its project only |\n| Project key | another project | `403 forbidden` |\n\nA resource outside the scope answers `404 not_found`, never 403. Resources created in a project scope belong to that project. Writes to a suspended project's resources answer `403 project_suspended`.", "schema": { "type": "string", "maxLength": 200 }, "example": "ext:customer_8812" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Make the request safe to retry. The first 2xx response is stored for 24 hours and replayed for the same key in the same scope, with `Idempotent-Replayed: true`. Reusing a key with a different method, path or body, or while the first request is still running, answers `409 idempotency_conflict`. Responses that are not 2xx are not stored, so a failed request can be retried with the same key. At most 255 characters.", "schema": { "type": "string", "maxLength": 255 }, "example": "order-A-1042-shipped" } }, "schemas": { "Error": { "type": "object", "description": "Every error response has this shape.", "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the list in the API description).", "examples": [ "invalid_request" ] }, "message": { "type": "string", "description": "Human-readable explanation.", "examples": [ "`text` is required." ] }, "details": { "type": "object", "additionalProperties": true, "description": "Extra context. `field` names the offending field." } }, "required": [ "code", "message" ] }, "ProxyLocation": { "type": "object", "description": "Where the account's residential proxy exits. The supported pairs are listed by `GET /v1/proxy-locations`. The city is preferred unless `strictCity` is `true`.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2, uppercase.", "pattern": "^[A-Z]{2}$" }, "city": { "type": "string", "description": "City code from `GET /v1/proxy-locations`: lowercase, one word, accents kept (`newyorkcity`, `bogotá`, `sãopaulo`). The unaccented form is accepted on input and stored with its accents." }, "strictCity": { "type": "boolean", "default": false, "description": "`false` (the default): the city is preferred. If no residential IP is free in that city when the number needs a new exit, it may get an exit in another city of the same country instead of staying offline, and it stays on that exit while the exit is healthy. `true`: the exact city is required, and the number may stay offline longer while no residential IP is free there. The country is always exact. Always present in responses." } }, "required": [ "country", "city", "strictCity" ] }, "ProxyLocationInput": { "type": "object", "description": "Where the account's residential proxy should exit, on create. The supported pairs are listed by `GET /v1/proxy-locations`. The city is preferred unless `strictCity` is `true`.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2, uppercase.", "pattern": "^[A-Z]{2}$" }, "city": { "type": "string", "description": "City code from `GET /v1/proxy-locations`: lowercase, one word, accents kept (`newyorkcity`, `bogotá`, `sãopaulo`). The unaccented form is accepted on input and stored with its accents." }, "strictCity": { "type": "boolean", "default": false, "description": "`false` (the default): the city is preferred. If no residential IP is free in that city when the number needs a new exit, it may get an exit in another city of the same country instead of staying offline, and it stays on that exit while the exit is healthy. `true`: the exact city is required, and the number may stay offline longer while no residential IP is free there. The country is always exact." } }, "required": [ "country", "city" ] }, "ProxyLocationUpdate": { "type": "object", "description": "A change to an account's proxy location: `{country, city}` moves it, `{strictCity}` alone switches whether its city is exact, both do both. An omitted `strictCity` keeps the current one. Any change gives the number a new exit IP and reconnects its session; WhatsApp may ask the phone to confirm the link again. `country` and `city` go together.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2, uppercase.", "pattern": "^[A-Z]{2}$" }, "city": { "type": "string", "description": "City code from `GET /v1/proxy-locations`: lowercase, one word, accents kept (`newyorkcity`, `bogotá`, `sãopaulo`). The unaccented form is accepted on input and stored with its accents." }, "strictCity": { "type": "boolean", "description": "Require the exact city (`true`) or prefer it (`false`)." } }, "minProperties": 1 }, "ProxyLocationItem": { "type": "object", "description": "A supported `{country, city}` pair for `proxyLocation`.", "properties": { "object": { "type": "string", "const": "proxy_location", "description": "Always `proxy_location`.", "readOnly": true }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2, uppercase. Use it in `proxyLocation.country`.", "pattern": "^[A-Z]{2}$" }, "countryName": { "type": "string", "description": "The country's English name." }, "city": { "type": "string", "description": "City code: lowercase, one word, accents kept (`newyorkcity`, `bogotá`). Use it in `proxyLocation.city`." }, "cityName": { "type": "string", "description": "The city's display name." } }, "required": [ "object", "country", "countryName", "city", "cityName" ], "examples": [ { "object": "proxy_location", "country": "CL", "countryName": "Chile", "city": "santiago", "cityName": "Santiago" } ] }, "ProxyLocationItemList": { "type": "object", "description": "A page of `ProxyLocationItem` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProxyLocationItem" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "AccountStatus": { "type": "string", "enum": [ "initializing", "qr_ready", "authenticating", "ready", "disconnected", "failed" ], "description": "Lifecycle of an account.\n- `initializing`: The session is starting.\n- `qr_ready`: Scan `qrCodeUrl`, or type `pairingCode`, on the phone.\n- `authenticating`: The phone accepted; the session is finishing linking.\n- `ready`: Linked and connected. Sends and live calls work.\n- `disconnected`: Not connected. `POST .../reconnect` to try again.\n- `failed`: The session gave up. `POST .../reconnect` to start over." }, "AccountPacingTyping": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Show \"typing...\" in the chat before each message. Default `false`; recommended `true` for bulk, cold or marketing sends." }, "minMs": { "type": "integer", "description": "Shortest typing time, in milliseconds. Default 800.", "minimum": 0, "maximum": 10000 }, "maxMs": { "type": "integer", "description": "Longest typing time, in milliseconds. At least `minMs`. Default 6000.", "minimum": 0, "maximum": 20000 }, "charsPerSecond": { "type": "integer", "description": "Typing speed: the time shown is the text length divided by this, clamped to `minMs`..`maxMs`. Default 25.", "minimum": 5, "maximum": 100 } }, "required": [ "enabled", "minMs", "maxMs", "charsPerSecond" ] }, "AccountPacing": { "type": "object", "description": "The pacing this account sends with: its own values over the defaults. The anti-ban protections are off by default (no per-minute cap, no first-contact cap, no typing), so messages go out one after another as fast as WhatsApp accepts them. Turn them on with `PATCH /v1/accounts/{accountId}`; recommended for bulk, cold or marketing sends: `messagesPerMinute` 12, `firstContactPerMinute` 5, `typing.enabled` true.", "properties": { "messagesPerMinute": { "type": "integer", "description": "Sends per minute from this number, with a random 1 to 3 second gap between them. `0` (the default) means no cap and no gap. Recommended 12.", "minimum": 0, "maximum": 30 }, "firstContactPerMinute": { "type": "integer", "description": "Sends per minute to people who never wrote to this number. `0` (the default) means no cap. At most `messagesPerMinute` when that is set, otherwise at most 30. Recommended 5.", "minimum": 0, "maximum": 30 }, "typing": { "$ref": "#/components/schemas/AccountPacingTyping" }, "queueTimeoutMinutes": { "type": "integer", "description": "How long a paced message waits in the queue before it fails with `rate_limited`. Default 60.", "minimum": 1, "maximum": 1440 }, "custom": { "type": "boolean", "description": "`true` when any value differs from the defaults (every protection off, a 60 minute queue timeout)." } }, "required": [ "messagesPerMinute", "firstContactPerMinute", "typing", "queueTimeoutMinutes", "custom" ] }, "Account": { "type": "object", "description": "A WhatsApp number linked as a device.", "properties": { "object": { "type": "string", "const": "account", "description": "Always `account`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "projectId": { "type": [ "string", "null" ], "description": "Project the resource belongs to, `null` when it is in no project. Set at creation and never changes." }, "name": { "type": [ "string", "null" ], "description": "Your label for the account." }, "status": { "$ref": "#/components/schemas/AccountStatus" }, "reconnecting": { "type": "boolean", "description": "`true` while the account, after being `ready`, is reconnecting on its own (`status` `disconnected`, `initializing` or `authenticating`) within the offline tolerance (currently 3 minutes): messages sent meanwhile wait for it. `false` when `ready`, when it is down for a reason it does not recover from, and once the tolerance runs out. Drops shorter than the reconnect grace (currently 20 seconds) fire no webhook." }, "phone": { "type": [ "string", "null" ], "description": "Linked number in E.164, once known." }, "profileName": { "type": [ "string", "null" ], "description": "The linked number's WhatsApp display name." }, "proxyLocation": { "oneOf": [ { "$ref": "#/components/schemas/ProxyLocation" }, { "type": "null" } ], "description": "Where the account's residential proxy exits. `null` only on accounts linked before proxy locations existed." }, "qrCodeUrl": { "type": [ "string", "null" ], "description": "PNG data URL of the QR code to scan. Set only while `status` is `qr_ready` and the account does not link by pairing code." }, "pairingCode": { "type": [ "string", "null" ], "description": "Pairing code (`XXXX-XXXX`) to type on the phone, for accounts linking by phone number. `null` once `ready`." }, "pairingCodeExpiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When `pairingCode` stops working, about 160 seconds after it was issued." }, "billable": { "type": "boolean", "description": "Billable from the moment linking finished (`linkedAt` set) until the account is deleted or logged out." }, "disconnectReason": { "type": [ "string", "null" ], "description": "Why the account left `ready`, for example `logged_out` or `session_not_found`. On the Free plan: `link_timeout` (not linked within 15 minutes; reconnect for a new QR code) or `free_limit_reached` (the month's Free limit was reached; the device stays linked and the account reconnects on its own when the month ends, UTC, or when the organization upgrades). While proxy traffic is paused (an unpaid invoice, or the monthly proxy spend cap): `proxy_paused` (the device stays linked and the account reconnects on its own when the pause lifts)." }, "lastError": { "type": [ "string", "null" ], "description": "The last error the session reported." }, "rejectCalls": { "type": "boolean", "description": "Reject incoming calls automatically." }, "rejectCallsMessage": { "type": [ "string", "null" ], "description": "Message sent to the caller after an automatic reject." }, "pacing": { "$ref": "#/components/schemas/AccountPacing" }, "historySync": { "allOf": [ { "$ref": "#/components/schemas/HistorySyncSetting" } ], "description": "Whether the recent chats the phone sends right after linking are imported. `none` by default. WhatsApp sends this history once, right after the number links, so a change applies to the next link. A number that is already linked gets no new history, not even after a reconnect." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Your labels. Set from an invitation's `metadata` when the invitee links the number." }, "linkedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When linking first finished." }, "lastConnectedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "object", "id", "projectId", "name", "status", "reconnecting", "phone", "profileName", "proxyLocation", "qrCodeUrl", "pairingCode", "pairingCodeExpiresAt", "billable", "disconnectReason", "lastError", "rejectCalls", "rejectCallsMessage", "pacing", "historySync", "metadata", "linkedAt", "lastConnectedAt", "createdAt", "updatedAt" ], "examples": [ { "object": "account", "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "projectId": null, "name": "Support line", "status": "ready", "reconnecting": false, "phone": "+584121234567", "profileName": "Acme Support", "proxyLocation": { "country": "VE", "city": "caracas", "strictCity": false }, "qrCodeUrl": null, "pairingCode": null, "pairingCodeExpiresAt": null, "billable": true, "disconnectReason": null, "lastError": null, "rejectCalls": false, "rejectCallsMessage": null, "pacing": { "messagesPerMinute": 0, "firstContactPerMinute": 0, "typing": { "enabled": false, "minMs": 800, "maxMs": 6000, "charsPerSecond": 25 }, "queueTimeoutMinutes": 60, "custom": false }, "historySync": "none", "metadata": {}, "linkedAt": "2026-09-20T14:02:11.000Z", "lastConnectedAt": "2026-09-24T08:15:40.000Z", "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } ] }, "AccountList": { "type": "object", "description": "A page of `Account` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "AccountPacingUpdate": { "type": [ "object", "null" ], "description": "Merged over the stored pacing; omitted fields keep their value. `pacing: null` resets everything to the defaults, with every protection off. `0` turns a cap off. Out-of-range values answer `400 invalid_request` with `details: {field, min, max}`. Recommended for bulk, cold or marketing sends: `{\"messagesPerMinute\": 12, \"firstContactPerMinute\": 5, \"typing\": {\"enabled\": true}}`.", "additionalProperties": false, "properties": { "messagesPerMinute": { "type": [ "integer", "null" ], "description": "0 to 30. `0` turns the per-minute cap and its gap off. `null` resets it to the default (off).", "minimum": 0, "maximum": 30 }, "firstContactPerMinute": { "type": [ "integer", "null" ], "description": "0 to `messagesPerMinute` (0 to 30 while that is off). `0` turns the first-contact cap off. `null` resets it to the default (off).", "minimum": 0, "maximum": 30 }, "typing": { "type": [ "object", "null" ], "additionalProperties": false, "description": "Fields you send are merged over the stored ones. `null` on a field, or on `typing`, resets it.", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Turn the typing indicator before each message on or off. `null` resets it to the default (off)." }, "minMs": { "type": [ "integer", "null" ], "description": "0 to 10000.", "minimum": 0, "maximum": 10000 }, "maxMs": { "type": [ "integer", "null" ], "description": "`minMs` to 20000.", "minimum": 0, "maximum": 20000 }, "charsPerSecond": { "type": [ "integer", "null" ], "description": "5 to 100.", "minimum": 5, "maximum": 100 } } }, "queueTimeoutMinutes": { "type": [ "integer", "null" ], "description": "1 to 1440. `null` resets it to 60.", "minimum": 1, "maximum": 1440 } } }, "HistorySyncSetting": { "type": "string", "enum": [ "none", "recent" ], "description": "- `none`: Do not import chat history. Only messages sent and received after linking are stored.\n- `recent`: Import the recent chats the phone sends right after linking. They are stored with `source: history` and `history.synced` fires." }, "AccountCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Label, at most 100 characters.", "maxLength": 100 }, "proxyLocation": { "allOf": [ { "$ref": "#/components/schemas/ProxyLocationInput" } ], "description": "Required. Where the account's residential proxy exits: a pair from `GET /v1/proxy-locations`, ideally the number's own country. Missing: `400 invalid_request`; not in the catalog: `400 unsupported_proxy_location`." }, "pairingPhone": { "type": "string", "description": "Link by pairing code instead of QR code: the number to link, E.164 or digits. The code appears as `pairingCode` (and the `account.pairing_code_issued` event) once the session is up; `qrCodeUrl` stays `null`.", "maxLength": 32 }, "projectId": { "type": "string", "description": "Organization keys only: create the account in this project (id or `ext:`). A project scope uses its own project; naming another answers `403 forbidden`.", "maxLength": 200 }, "historySync": { "allOf": [ { "$ref": "#/components/schemas/HistorySyncSetting" } ], "description": "Import the recent chats the phone sends when the number links: `recent`. Default `none`, no history. WhatsApp sends this history once, right after linking." } }, "required": [ "proxyLocation" ] }, "AccountUpdateRequest": { "type": "object", "description": "Provide at least one field. Call settings go to the live session, so the engine must know the account (any status). Pacing and `historySync` are stored even before the account has a session. A `proxyLocation` change moves a live session to the new exit.", "properties": { "name": { "type": "string", "maxLength": 100 }, "rejectCalls": { "type": "boolean", "description": "Reject incoming calls automatically." }, "rejectCallsMessage": { "type": "string", "description": "Sent to the caller after an automatic reject (not for group calls). At most 1000 characters.", "maxLength": 1000 }, "pacing": { "$ref": "#/components/schemas/AccountPacingUpdate" }, "historySync": { "allOf": [ { "$ref": "#/components/schemas/HistorySyncSetting" } ], "description": "Import history at the next link, or not. WhatsApp sends this history once, right after the number links, so a change applies to the next link. A number that is already linked gets no new history, not even after a reconnect." }, "proxyLocation": { "allOf": [ { "$ref": "#/components/schemas/ProxyLocationUpdate" } ], "description": "Move the number, or switch whether its city is exact. A location change: the number gets a new exit IP and its session reconnects." } }, "minProperties": 1 }, "PairingCodeRequest": { "type": "object", "properties": { "phone": { "type": "string", "description": "The number to link, E.164 (`+584121234567`) or digits.", "maxLength": 32 } }, "required": [ "phone" ] }, "PairingCode": { "type": "object", "description": "A pairing code.", "properties": { "object": { "type": "string", "const": "pairing_code", "description": "Always `pairing_code`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "code": { "type": "string", "description": "Type this on the phone: WhatsApp > Linked devices > Link a device > Link with phone number instead." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "About 160 seconds after it was issued." } }, "required": [ "object", "accountId", "code", "expiresAt" ], "examples": [ { "object": "pairing_code", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "code": "ABCD-1234", "expiresAt": "2026-09-24T08:18:20.000Z" } ] }, "AccountPresenceRequest": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "online", "offline" ], "description": "- `online`: Contacts see the account online.\n- `offline`: Contacts see it offline." } }, "required": [ "state" ] }, "DisappearingTimerRequest": { "type": "object", "properties": { "durationSeconds": { "type": "integer", "enum": [ 0, 86400, 604800, 7776000 ], "description": "0 turns it off; otherwise 24 hours, 7 days or 90 days." } }, "required": [ "durationSeconds" ] }, "MessageDirection": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "- `inbound`: Sent by a contact to the account.\n- `outbound`: Sent by the account." }, "MessageSource": { "type": "string", "enum": [ "api", "phone", "contact", "history" ], "description": "- `api`: Sent through wuapi.\n- `phone`: Sent from the phone itself.\n- `contact`: Received from a contact.\n- `history`: Imported from the phone's history sync. Fires no per-message events." }, "MessageType": { "type": "string", "enum": [ "text", "image", "video", "audio", "voice", "document", "sticker", "location", "contact", "contacts", "poll", "reaction", "calendar_event", "unknown" ], "description": "- `text`: Text.\n- `image`: Image, with an optional caption in `text`.\n- `video`: Video.\n- `audio`: Audio file.\n- `voice`: Audio sent or received as a voice note.\n- `document`: Document.\n- `sticker`: Sticker.\n- `location`: A location.\n- `contact`: One contact card.\n- `contacts`: Several contact cards.\n- `poll`: A poll.\n- `reaction`: A reaction: `text` is the emoji (empty when removed), `replyToMessageId` the message reacted to.\n- `calendar_event`: A WhatsApp calendar event.\n- `unknown`: A type wuapi does not model." }, "MessageStatus": { "type": "string", "enum": [ "queued", "sent", "delivered", "read", "failed", "received" ], "description": "- `queued`: Waiting to be sent (paced or retrying).\n- `sent`: WhatsApp accepted it.\n- `delivered`: It reached the phone.\n- `read`: The recipient read it.\n- `failed`: It was not sent. See `error`.\n- `received`: An inbound message." }, "ChatType": { "type": "string", "enum": [ "direct", "group", "channel", "story" ], "description": "- `direct`: A chat with one contact. `chatId` is the contact id.\n- `group`: A group. `chatId` is the group id.\n- `channel`: A channel. `chatId` is the channel id.\n- `story`: The account's stories. `chatId` is `stories`." }, "MessageMedia": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "description": "Inbound: a URL to download it. Outbound: the URL you sent." }, "mimeType": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] } }, "required": [ "url", "mimeType", "filename" ] }, "MessageLocation": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "latitude", "longitude", "name", "address" ] }, "MessageContact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string", "description": "E.164." } }, "required": [ "name", "phone" ] }, "MessagePoll": { "type": "object", "description": "The poll and its current tally. Votes arrive as `poll.voted` events.", "properties": { "name": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "voteCount": { "type": "integer" } }, "required": [ "name", "voteCount" ] } }, "selectableCount": { "type": "integer", "description": "How many options a voter may pick; 0 means any number." }, "voterCount": { "type": "integer", "description": "People who voted." } }, "required": [ "name", "options", "selectableCount", "voterCount" ] }, "MessageCalendarEvent": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "location": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } }, "required": [ "name", "address", "latitude", "longitude" ] }, "callType": { "type": [ "string", "null" ], "enum": [ "audio", "video", null ], "description": "Set when the calendar event is a scheduled WhatsApp call.\n- `audio`: A scheduled voice call.\n- `video`: A scheduled video call." }, "joinUrl": { "type": [ "string", "null" ], "description": "The call link WhatsApp generated, on received calendar events. wuapi never generates one." }, "allowExtraGuests": { "type": "boolean" }, "cancelled": { "type": "boolean" } }, "required": [ "name", "description", "startsAt", "endsAt", "location", "callType", "joinUrl", "allowExtraGuests", "cancelled" ] }, "MessageError": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "not_on_whatsapp", "rate_limited", "send_failed", "account_offline", "cancelled", "payment_required", "proxy_spend_cap_reached" ], "description": "- `not_on_whatsapp`: The recipient has no WhatsApp.\n- `rate_limited`: Still paced after `pacing.queueTimeoutMinutes`.\n- `send_failed`: WhatsApp or the engine refused it, or its `media.url` could not be downloaded (the message names the host and its answer).\n- `account_offline`: The account was reconnecting for longer than the offline tolerance, or went down for good, while the message waited for it.\n- `cancelled`: Deleted with `DELETE /v1/messages/{messageId}` while it was still queued; it was never sent.\n- `payment_required`: It was queued before proxy traffic paused for an unpaid invoice, and the pause lasted more than 24 hours.\n- `proxy_spend_cap_reached`: It was queued before proxy traffic paused at the monthly proxy spend cap, and the pause lasted more than 24 hours." }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "Message": { "type": "object", "description": "A message in a chat, stored by wuapi.", "properties": { "object": { "type": "string", "const": "message", "description": "Always `message`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "projectId": { "type": [ "string", "null" ], "description": "Project the resource belongs to, `null` when it is in no project. Set at creation and never changes." }, "accountId": { "type": "string", "description": "The account this belongs to." }, "chatId": { "type": "string", "description": "The chat: the contact id for a direct chat, the group id, the channel id, or `stories`." }, "chatType": { "$ref": "#/components/schemas/ChatType" }, "direction": { "$ref": "#/components/schemas/MessageDirection" }, "source": { "$ref": "#/components/schemas/MessageSource" }, "from": { "type": "string", "description": "Sender: a contact id, or the account's own number on outbound messages." }, "to": { "type": "string", "description": "Recipient: a contact id, the group id, the channel id, or `stories`." }, "profileName": { "type": [ "string", "null" ], "description": "The sender's WhatsApp display name, on inbound messages." }, "username": { "type": [ "string", "null" ], "description": "The sender's WhatsApp username (lowercase, without the `@`), on inbound messages when WhatsApp shared it. A contact who hides their number (`from` is `lid:`) is often only recognizable by it." }, "type": { "$ref": "#/components/schemas/MessageType" }, "text": { "type": [ "string", "null" ], "description": "Text, or the caption of media." }, "media": { "oneOf": [ { "$ref": "#/components/schemas/MessageMedia" }, { "type": "null" } ] }, "location": { "oneOf": [ { "$ref": "#/components/schemas/MessageLocation" }, { "type": "null" } ] }, "contact": { "oneOf": [ { "$ref": "#/components/schemas/MessageContact" }, { "type": "null" } ], "description": "The contact card (the first one when several were sent)." }, "contacts": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MessageContact" }, "description": "Every card of a `contacts` message." }, "poll": { "oneOf": [ { "$ref": "#/components/schemas/MessagePoll" }, { "type": "null" } ] }, "calendarEvent": { "oneOf": [ { "$ref": "#/components/schemas/MessageCalendarEvent" }, { "type": "null" } ] }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Mentioned contact ids." }, "forwarded": { "type": "boolean" }, "viewOnce": { "type": "boolean" }, "starred": { "type": "boolean" }, "replyToMessageId": { "type": [ "string", "null" ], "description": "The wuapi id of the quoted (or reacted-to) message." }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "error": { "oneOf": [ { "$ref": "#/components/schemas/MessageError" }, { "type": "null" } ], "description": "Why it failed, when `status` is `failed`." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Your metadata, as sent." }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "WhatsApp's own timestamp of the message." }, "editedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Set when the text was edited (`message.edited`)." }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Set when it was deleted for everyone (`message.deleted`); the content is cleared." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "object", "id", "projectId", "accountId", "chatId", "chatType", "direction", "source", "from", "to", "profileName", "username", "type", "text", "media", "location", "contact", "contacts", "poll", "calendarEvent", "mentions", "forwarded", "viewOnce", "starred", "replyToMessageId", "status", "error", "metadata", "sentAt", "editedAt", "deletedAt", "createdAt", "updatedAt" ], "examples": [ { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "chatType": "direct", "direction": "outbound", "source": "api", "from": "+584121234567", "to": "+584241112233", "profileName": null, "username": null, "type": "text", "text": "Your order has shipped.", "media": null, "location": null, "contact": null, "contacts": null, "poll": null, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": false, "replyToMessageId": null, "status": "queued", "error": null, "metadata": { "orderId": "A-1042" }, "sentAt": null, "editedAt": null, "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } ] }, "MessageList": { "type": "object", "description": "A page of `Message` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "DisappearingSeconds": { "type": "integer", "enum": [ 0, 86400, 604800, 7776000 ], "description": "A disappearing-messages timer: 0 (off), 24 hours, 7 days or 90 days." }, "SendMedia": { "type": "object", "description": "A file to send, fetched by our servers.", "properties": { "url": { "type": "string", "description": "Public `http(s)` URL our servers download (up to 5 redirects, 60 seconds, 100 MB), as `wuapi-media-fetcher/1.0 (+https://wuapi.dev)`. Private and internal addresses are refused; hosts with hotlink protection may refuse the download, which fails the message with a message naming the host and its answer (`fetch media from upload.wikimedia.org: HTTP 403`).", "format": "uri", "maxLength": 2048 }, "mimeType": { "type": "string", "description": "Guessed from the URL extension when omitted. Voice notes: send ogg/opus, nothing is transcoded.", "maxLength": 255 }, "filename": { "type": "string", "maxLength": 255 } }, "required": [ "url" ] }, "SendVideoMedia": { "type": "object", "description": "A video to send, fetched by our servers.", "properties": { "url": { "type": "string", "description": "Public `http(s)` URL our servers download (up to 5 redirects, 60 seconds, 100 MB), as `wuapi-media-fetcher/1.0 (+https://wuapi.dev)`. Private and internal addresses are refused; hosts with hotlink protection may refuse the download, which fails the message with a message naming the host and its answer (`fetch media from upload.wikimedia.org: HTTP 403`).", "format": "uri", "maxLength": 2048 }, "mimeType": { "type": "string", "description": "Guessed from the URL extension when omitted. Voice notes: send ogg/opus, nothing is transcoded.", "maxLength": 255 }, "filename": { "type": "string", "maxLength": 255 }, "gifPlayback": { "type": "boolean", "description": "Play it as a GIF." } }, "required": [ "url" ] }, "SendContact": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 256 }, "phone": { "type": "string", "description": "E.164 or digits.", "maxLength": 32 } }, "required": [ "name", "phone" ] }, "SendLocation": { "type": "object", "description": "A pin on the map.", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "name": { "type": "string", "maxLength": 256 }, "address": { "type": "string", "maxLength": 512 } }, "required": [ "latitude", "longitude" ] }, "SendPoll": { "type": "object", "description": "A poll.", "properties": { "name": { "type": "string", "maxLength": 255 }, "options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "2 to 12 unique, non-blank options of at most 100 characters.", "minItems": 2, "maxItems": 12, "uniqueItems": true }, "selectableCount": { "type": "integer", "description": "How many options a voter may pick. 0 (default) means any number; at most the number of options.", "minimum": 0 } }, "required": [ "name", "options" ] }, "SendCalendarEvent": { "type": "object", "description": "A calendar event.", "properties": { "name": { "type": "string", "maxLength": 256 }, "description": { "type": "string", "maxLength": 2048 }, "startsAt": { "type": "string", "description": "ISO 8601.", "format": "date-time" }, "endsAt": { "type": "string", "description": "Not before `startsAt`.", "format": "date-time" }, "location": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 256 }, "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "name" ] }, "callType": { "type": "string", "enum": [ "audio", "video" ], "description": "Make it a scheduled WhatsApp call. WhatsApp generates the call link, not wuapi." }, "allowExtraGuests": { "type": "boolean" } }, "required": [ "name", "startsAt" ] }, "SendLinkPreview": { "type": "object", "description": "Text only. wuapi does not fetch previews; you provide them.", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string", "maxLength": 256 }, "description": { "type": "string", "maxLength": 1024 }, "thumbnailBase64": { "type": "string", "description": "JPEG, base64.", "maxLength": 200000 } }, "required": [ "url", "title" ] }, "SendTextMessageRequest": { "type": "object", "description": "A text message, with an optional link preview.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`), a WhatsApp username (`@handle`) of a contact this account already chats with, a group id, or a channel id (to post in a channel the account administers). WhatsApp does not let a linked device look up other usernames: those answer `400 username_not_supported`.", "maxLength": 64 }, "type": { "type": "string", "const": "text", "description": "`text`. A body without `type` is also sent as text." }, "text": { "type": "string", "description": "The message. Not blank; at most 4096 characters.", "minLength": 1, "maxLength": 4096 }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "linkPreview": { "$ref": "#/components/schemas/SendLinkPreview" }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "text" ] }, "SendImageMessageRequest": { "type": "object", "description": "An image, with an optional caption.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`), a WhatsApp username (`@handle`) of a contact this account already chats with, a group id, or a channel id (to post in a channel the account administers). WhatsApp does not let a linked device look up other usernames: those answer `400 username_not_supported`.", "maxLength": 64 }, "type": { "type": "string", "const": "image", "description": "`image`." }, "media": { "$ref": "#/components/schemas/SendMedia" }, "text": { "type": "string", "description": "Caption. At most 4096 characters.", "maxLength": 4096 }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "viewOnce": { "type": "boolean", "description": "The recipient can open it once." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "media" ] }, "SendVideoMessageRequest": { "type": "object", "description": "A video, with an optional caption.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`), a WhatsApp username (`@handle`) of a contact this account already chats with, a group id, or a channel id (to post in a channel the account administers). WhatsApp does not let a linked device look up other usernames: those answer `400 username_not_supported`.", "maxLength": 64 }, "type": { "type": "string", "const": "video", "description": "`video`." }, "media": { "$ref": "#/components/schemas/SendVideoMedia" }, "text": { "type": "string", "description": "Caption. At most 4096 characters.", "maxLength": 4096 }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "viewOnce": { "type": "boolean", "description": "The recipient can open it once." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "media" ] }, "SendAudioMessageRequest": { "type": "object", "description": "An audio file.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`) or a group id. Channels take only `text`, `image`, `video` and `document`.", "maxLength": 64 }, "type": { "type": "string", "const": "audio", "description": "`audio`." }, "media": { "$ref": "#/components/schemas/SendMedia" }, "text": { "type": "string", "description": "Caption. At most 4096 characters.", "maxLength": 4096 }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "viewOnce": { "type": "boolean", "description": "The recipient can open it once." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "media" ] }, "SendVoiceMessageRequest": { "type": "object", "description": "An audio sent as a voice note. Send ogg/opus: nothing is transcoded.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`) or a group id. Channels take only `text`, `image`, `video` and `document`.", "maxLength": 64 }, "type": { "type": "string", "const": "voice", "description": "`voice`." }, "media": { "$ref": "#/components/schemas/SendMedia" }, "text": { "type": "string", "description": "Caption. At most 4096 characters.", "maxLength": 4096 }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "viewOnce": { "type": "boolean", "description": "The recipient can open it once." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "media" ] }, "SendDocumentMessageRequest": { "type": "object", "description": "A document, with an optional caption.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`), a WhatsApp username (`@handle`) of a contact this account already chats with, a group id, or a channel id (to post in a channel the account administers). WhatsApp does not let a linked device look up other usernames: those answer `400 username_not_supported`.", "maxLength": 64 }, "type": { "type": "string", "const": "document", "description": "`document`." }, "media": { "$ref": "#/components/schemas/SendMedia" }, "text": { "type": "string", "description": "Caption. At most 4096 characters.", "maxLength": 4096 }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "media" ] }, "SendStickerMessageRequest": { "type": "object", "description": "A sticker.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`) or a group id. Channels take only `text`, `image`, `video` and `document`.", "maxLength": 64 }, "type": { "type": "string", "const": "sticker", "description": "`sticker`." }, "media": { "$ref": "#/components/schemas/SendMedia" }, "text": { "type": "string", "description": "Caption. At most 4096 characters.", "maxLength": 4096 }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "media" ] }, "SendLocationMessageRequest": { "type": "object", "description": "A location pin.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`) or a group id. Channels take only `text`, `image`, `video` and `document`.", "maxLength": 64 }, "type": { "type": "string", "const": "location", "description": "`location`." }, "location": { "$ref": "#/components/schemas/SendLocation" }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "location" ] }, "SendContactMessageRequest": { "type": "object", "description": "One contact card.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`) or a group id. Channels take only `text`, `image`, `video` and `document`.", "maxLength": 64 }, "type": { "type": "string", "const": "contact", "description": "`contact`." }, "contact": { "$ref": "#/components/schemas/SendContact" }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "contact" ] }, "SendContactsMessageRequest": { "type": "object", "description": "2 to 20 contact cards in one message. Use `contact` for one.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`) or a group id. Channels take only `text`, `image`, `video` and `document`.", "maxLength": 64 }, "type": { "type": "string", "const": "contacts", "description": "`contacts`." }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/SendContact" }, "description": "2 to 20 cards.", "minItems": 2, "maxItems": 20 }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "contacts" ] }, "SendPollMessageRequest": { "type": "object", "description": "A poll.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`) or a group id. Channels take only `text`, `image`, `video` and `document`.", "maxLength": 64 }, "type": { "type": "string", "const": "poll", "description": "`poll`." }, "poll": { "$ref": "#/components/schemas/SendPoll" }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "poll" ] }, "SendCalendarEventMessageRequest": { "type": "object", "description": "A calendar event, optionally a scheduled WhatsApp call.", "properties": { "accountId": { "type": "string", "description": "The account to send from. It must be `ready`.", "maxLength": 64 }, "to": { "type": "string", "description": "A contact id (E.164, digits or `lid:`) or a group id. Channels take only `text`, `image`, `video` and `document`.", "maxLength": 64 }, "type": { "type": "string", "const": "calendar_event", "description": "`calendar_event`." }, "calendarEvent": { "$ref": "#/components/schemas/SendCalendarEvent" }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to mention. At most 256. Not for channel posts.", "maxItems": 256 }, "mentionAll": { "type": "boolean", "description": "Groups only: mention every participant." }, "forwarded": { "type": "boolean", "description": "Mark as forwarded." }, "disappearingSeconds": { "$ref": "#/components/schemas/DisappearingSeconds", "description": "Match the chat's disappearing timer." }, "replyToMessageId": { "type": "string", "description": "A wuapi message id in the same chat to quote. Any type. Not for channel posts.", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." } }, "required": [ "accountId", "to", "type", "calendarEvent" ] }, "SendMessageRequest": { "description": "One schema per `type`; each requires its own field (`text`, `media`, `location`, `contact`, `contacts`, `poll` or `calendarEvent`). A body without `type` is sent as `text`. To a channel: `text`, `image`, `video` or `document`, with no `replyToMessageId`, `mentions` or `mentionAll`.", "oneOf": [ { "$ref": "#/components/schemas/SendTextMessageRequest" }, { "$ref": "#/components/schemas/SendImageMessageRequest" }, { "$ref": "#/components/schemas/SendVideoMessageRequest" }, { "$ref": "#/components/schemas/SendAudioMessageRequest" }, { "$ref": "#/components/schemas/SendVoiceMessageRequest" }, { "$ref": "#/components/schemas/SendDocumentMessageRequest" }, { "$ref": "#/components/schemas/SendStickerMessageRequest" }, { "$ref": "#/components/schemas/SendLocationMessageRequest" }, { "$ref": "#/components/schemas/SendContactMessageRequest" }, { "$ref": "#/components/schemas/SendContactsMessageRequest" }, { "$ref": "#/components/schemas/SendPollMessageRequest" }, { "$ref": "#/components/schemas/SendCalendarEventMessageRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/SendTextMessageRequest", "image": "#/components/schemas/SendImageMessageRequest", "video": "#/components/schemas/SendVideoMessageRequest", "audio": "#/components/schemas/SendAudioMessageRequest", "voice": "#/components/schemas/SendVoiceMessageRequest", "document": "#/components/schemas/SendDocumentMessageRequest", "sticker": "#/components/schemas/SendStickerMessageRequest", "location": "#/components/schemas/SendLocationMessageRequest", "contact": "#/components/schemas/SendContactMessageRequest", "contacts": "#/components/schemas/SendContactsMessageRequest", "poll": "#/components/schemas/SendPollMessageRequest", "calendar_event": "#/components/schemas/SendCalendarEventMessageRequest" } } }, "MessageEditRequest": { "type": "object", "properties": { "text": { "type": "string", "description": "The new text.", "maxLength": 4096 } }, "required": [ "text" ] }, "VoteRequest": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "string" }, "description": "Names of this poll's options. `[]` retracts the vote." } }, "required": [ "options" ] }, "ReactRequest": { "type": "object", "properties": { "emoji": { "type": "string", "description": "One emoji. An empty string removes the reaction.", "maxLength": 32 } }, "required": [ "emoji" ] }, "LabelAssignRequest": { "type": "object", "properties": { "labelId": { "type": "string", "maxLength": 64 } }, "required": [ "labelId" ] }, "StoryMedia": { "type": "object", "description": "An image or video for a story, fetched by our servers.", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public `http(s)` URL our servers download (up to 5 redirects, 60 seconds, 100 MB), as `wuapi-media-fetcher/1.0 (+https://wuapi.dev)`. Private and internal addresses are refused; hosts with hotlink protection may refuse the download, which fails the message with a message naming the host and its answer (`fetch media from upload.wikimedia.org: HTTP 403`)." }, "mimeType": { "type": "string", "maxLength": 255 } }, "required": [ "url" ] }, "TextStoryCreateRequest": { "type": "object", "description": "A text story.", "properties": { "type": { "type": "string", "const": "text", "description": "`text`. A body without `type` is also posted as text." }, "text": { "type": "string", "description": "The story. Not blank; at most 4096 characters.", "minLength": 1, "maxLength": 4096 }, "backgroundColor": { "type": "string", "description": "`#RRGGBB`.", "pattern": "^#[0-9a-fA-F]{6}$" }, "font": { "type": "integer", "enum": [ 0, 1, 2, 6, 7, 8, 9, 10 ], "description": "WhatsApp's font." } }, "required": [ "type", "text" ] }, "MediaStoryCreateRequest": { "type": "object", "description": "An image or video story, with an optional caption.", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "media": { "$ref": "#/components/schemas/StoryMedia" }, "text": { "type": "string", "description": "Caption. At most 4096 characters.", "maxLength": 4096 } }, "required": [ "type", "media" ] }, "StoryCreateRequest": { "description": "A text story (`type: text`, requires `text`) or a media story (`type: image` or `video`, requires `media`). A body without `type` is posted as `text`.", "oneOf": [ { "$ref": "#/components/schemas/TextStoryCreateRequest" }, { "$ref": "#/components/schemas/MediaStoryCreateRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextStoryCreateRequest", "image": "#/components/schemas/MediaStoryCreateRequest", "video": "#/components/schemas/MediaStoryCreateRequest" } } }, "ChatPresenceRequest": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "typing", "recording", "paused" ], "description": "- `typing`: Show typing.\n- `recording`: Show recording audio.\n- `paused`: Clear the indicator." } }, "required": [ "state" ] }, "ReadReceiptsRequest": { "type": "object", "properties": { "messageIds": { "type": "array", "items": { "type": "string" }, "description": "wuapi ids of inbound messages in this chat. Default: every unread inbound message wuapi stores for the chat. At most 500.", "maxItems": 500 } } }, "ChatRead": { "type": "object", "description": "Read receipts sent.", "properties": { "object": { "type": "string", "const": "chat_read", "description": "Always `chat_read`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "chatId": { "type": "string" }, "messageCount": { "type": "integer", "description": "Messages marked read." } }, "required": [ "object", "accountId", "chatId", "messageCount" ], "examples": [ { "object": "chat_read", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "messageCount": 3 } ] }, "MuteRequest": { "type": "object", "properties": { "durationSeconds": { "type": "integer", "description": "How long to mute. 0 or absent: until unmuted.", "minimum": 0, "maximum": 315360000 } } }, "LabelUpsertRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "color": { "type": "integer", "description": "WhatsApp's label color index.", "minimum": 0, "maximum": 19, "default": 0 } }, "required": [ "name" ] }, "Label": { "type": "object", "description": "A WhatsApp Business label.", "properties": { "object": { "type": "string", "const": "label", "description": "Always `label`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "name": { "type": "string" }, "color": { "type": "integer", "minimum": 0, "maximum": 19 } }, "required": [ "object", "id", "accountId", "name", "color" ], "examples": [ { "object": "label", "id": "5", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Paid", "color": 3 } ] }, "ContactCheckRequest": { "type": "object", "properties": { "phones": { "type": "array", "items": { "type": "string" }, "description": "1 to 50 phone numbers (E.164 or digits).", "minItems": 1, "maxItems": 50 } }, "required": [ "phones" ] }, "ContactCheck": { "type": "object", "description": "Whether a number has WhatsApp.", "properties": { "object": { "type": "string", "const": "contact_check", "description": "Always `contact_check`.", "readOnly": true }, "phone": { "type": "string", "description": "The number, in E.164." }, "onWhatsApp": { "type": "boolean" }, "contactId": { "type": [ "string", "null" ], "description": "A contact id: E.164 (`+584241112233`), or `lid:` when WhatsApp hides the number. `null` when not on WhatsApp." }, "businessName": { "type": [ "string", "null" ], "description": "The verified business name, for business accounts." }, "username": { "type": [ "string", "null" ], "description": "The number's WhatsApp username (lowercase, without the `@`), when this account already learned it. A check never asks WhatsApp for it." } }, "required": [ "object", "phone", "onWhatsApp", "contactId", "businessName", "username" ], "examples": [ { "object": "contact_check", "phone": "+584241112233", "onWhatsApp": true, "contactId": "+584241112233", "businessName": null, "username": null } ] }, "ContactCheckList": { "type": "object", "description": "A page of `ContactCheck` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContactCheck" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "ContactLookupRequest": { "type": "object", "properties": { "contactIds": { "type": "array", "items": { "type": "string" }, "description": "1 to 50 contact ids (E.164, digits or `lid:`).", "minItems": 1, "maxItems": 50 } }, "required": [ "contactIds" ] }, "Contact": { "type": "object", "description": "A WhatsApp user, as this account sees it. Fields WhatsApp did not send are `null`.", "properties": { "object": { "type": "string", "const": "contact", "description": "Always `contact`.", "readOnly": true }, "id": { "type": "string", "description": "A contact id: E.164 (`+584241112233`), or `lid:` when WhatsApp hides the number.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "lid": { "type": [ "string", "null" ], "description": "The contact's `lid:` id, when WhatsApp gave one." }, "username": { "type": [ "string", "null" ], "description": "The contact's WhatsApp username (lowercase, without the `@`), when they set one and WhatsApp shared it with this account." }, "about": { "type": [ "string", "null" ], "description": "About text." }, "pictureId": { "type": [ "string", "null" ] }, "businessName": { "type": [ "string", "null" ], "description": "Verified business name." }, "deviceCount": { "type": [ "integer", "null" ], "description": "Devices linked to the contact." } }, "required": [ "object", "id", "accountId", "lid", "username", "about", "pictureId", "businessName", "deviceCount" ], "examples": [ { "object": "contact", "id": "+584241112233", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "lid": null, "username": null, "about": "Available", "pictureId": "1727164540", "businessName": null, "deviceCount": 2 } ] }, "ContactList": { "type": "object", "description": "A page of `Contact` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "Picture": { "type": "object", "description": "A profile or group picture.", "properties": { "object": { "type": "string", "const": "picture", "description": "Always `picture`.", "readOnly": true }, "id": { "type": [ "string", "null" ], "description": "Picture id." }, "url": { "type": [ "string", "null" ], "description": "Download URL. `null` right after an upload." }, "preview": { "type": "boolean", "description": "`true` for the small preview." } }, "required": [ "object", "id", "url", "preview" ], "examples": [ { "object": "picture", "id": "1727164540", "url": "https://pps.whatsapp.net/v/t61/example.jpg", "preview": false } ] }, "BusinessProfile": { "type": "object", "description": "A WhatsApp Business profile.", "properties": { "object": { "type": "string", "const": "business_profile", "description": "Always `business_profile`.", "readOnly": true }, "contactId": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "profileOptions": { "type": "object", "additionalProperties": { "type": "string" } }, "timeZone": { "type": [ "string", "null" ] }, "businessHours": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "string" }, "mode": { "type": "string" }, "openTime": { "type": [ "string", "null" ], "description": "Time of day." }, "closeTime": { "type": [ "string", "null" ], "description": "Time of day." } }, "required": [ "dayOfWeek", "mode", "openTime", "closeTime" ] } } }, "required": [ "object", "contactId", "address", "email", "categories", "profileOptions", "timeZone", "businessHours" ], "examples": [ { "object": "business_profile", "contactId": "+584241112233", "address": "Av. Principal 12, Caracas", "email": "hola@example.com", "categories": [ { "id": "133436743388217", "name": "Shopping & retail" } ], "profileOptions": {}, "timeZone": "America/Caracas", "businessHours": [ { "dayOfWeek": "mon", "mode": "specific_hours", "openTime": "09:00", "closeTime": "18:00" } ] } ] }, "BlockedContact": { "type": "object", "description": "A blocked contact.", "properties": { "object": { "type": "string", "const": "blocked_contact", "description": "Always `blocked_contact`.", "readOnly": true }, "contactId": { "type": "string", "description": "The contact as WhatsApp keeps it in the blocklist: E.164 (`+584241112233`), or `lid:` when WhatsApp lists it by LID (more and more common)." }, "phone": { "type": [ "string", "null" ], "description": "The contact's number (E.164) when the account knows it, the LID resolved. `null` otherwise." }, "lid": { "type": [ "string", "null" ], "description": "The contact's LID (`lid:`) when the account knows it. `null` otherwise." } }, "required": [ "object", "contactId", "phone", "lid" ], "examples": [ { "object": "blocked_contact", "contactId": "lid:201843727138927", "phone": "+584241112233", "lid": "lid:201843727138927" } ] }, "BlockedContactList": { "type": "object", "description": "A page of `BlockedContact` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BlockedContact" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "ContactLink": { "type": "object", "description": "The account's own contact QR link.", "properties": { "object": { "type": "string", "const": "contact_link", "description": "Always `contact_link`.", "readOnly": true }, "url": { "type": [ "string", "null" ] } }, "required": [ "object", "url" ], "examples": [ { "object": "contact_link", "url": "https://wa.me/qr/ABCDEFGHIJKL1" } ] }, "LinkResolveRequest": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "contact", "business" ], "description": "- `contact`: A contact QR link.\n- `business`: A business message link." }, "code": { "type": "string", "description": "The code or the full link.", "maxLength": 512 } }, "required": [ "kind", "code" ] }, "ResolvedLink": { "type": "object", "description": "Who a link points to.", "properties": { "object": { "type": "string", "const": "resolved_link", "description": "Always `resolved_link`.", "readOnly": true }, "kind": { "type": "string", "enum": [ "contact", "business" ] }, "contactId": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "description": "Contact links: the contact type." }, "profileName": { "type": [ "string", "null" ] }, "businessName": { "type": [ "string", "null" ], "description": "Business links." }, "verifiedLevel": { "type": [ "string", "null" ], "description": "Business links." }, "prefilledText": { "type": [ "string", "null" ], "description": "Business links: the prefilled message." } }, "required": [ "object", "kind", "contactId", "type", "profileName", "businessName", "verifiedLevel", "prefilledText" ], "examples": [ { "object": "resolved_link", "kind": "contact", "contactId": "+584241112233", "type": "contact", "profileName": "Maria", "businessName": null, "verifiedLevel": null, "prefilledText": null } ] }, "Bot": { "type": "object", "description": "A WhatsApp AI bot.", "properties": { "object": { "type": "string", "const": "bot", "description": "Always `bot`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "personaId": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "default": { "type": "boolean" }, "prompts": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "required": [ "name", "description" ] } } }, "required": [ "object", "id", "personaId", "name", "description", "category", "default", "prompts", "commands" ], "examples": [ { "object": "bot", "id": "867051314767696@bot", "personaId": null, "name": "AI assistant", "description": null, "category": null, "default": true, "prompts": [], "commands": [] } ] }, "BotList": { "type": "object", "description": "A page of `Bot` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Bot" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "ProfileUpdateRequest": { "type": "object", "description": "Provide `about`, `name` or both.", "properties": { "about": { "type": "string", "description": "The About text.", "maxLength": 139 }, "name": { "type": "string", "description": "Display name.", "maxLength": 25 } }, "minProperties": 1 }, "PictureUploadRequest": { "description": "Exactly one of `url` (https, fetched by our servers) or `base64` (JPEG).", "oneOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "url" ] }, { "type": "object", "properties": { "base64": { "type": "string", "maxLength": 5000000 } }, "required": [ "base64" ] } ] }, "PrivacySettings": { "type": "object", "description": "The account's privacy settings, with WhatsApp's values (`all`, `contacts`, `contact_blacklist`, `none`, ...).", "properties": { "object": { "type": "string", "const": "privacy_settings", "description": "Always `privacy_settings`.", "readOnly": true }, "groupAdd": { "type": [ "string", "null" ], "description": "Who can add the account to groups." }, "lastSeen": { "type": [ "string", "null" ] }, "stories": { "type": [ "string", "null" ], "description": "Who sees the account's stories." }, "profile": { "type": [ "string", "null" ], "description": "Who sees the profile picture." }, "readReceipts": { "type": [ "string", "null" ] }, "online": { "type": [ "string", "null" ] }, "callAdd": { "type": [ "string", "null" ] }, "messages": { "type": [ "string", "null" ] }, "defense": { "type": [ "string", "null" ] }, "stickers": { "type": [ "string", "null" ] } }, "required": [ "object", "groupAdd", "lastSeen", "stories", "profile", "readReceipts", "online", "callAdd", "messages", "defense", "stickers" ], "examples": [ { "object": "privacy_settings", "groupAdd": "contacts", "lastSeen": "contacts", "stories": "contacts", "profile": "all", "readReceipts": "all", "online": "all", "callAdd": "all", "messages": null, "defense": null, "stickers": null } ] }, "PrivacyUpdateRequest": { "type": "object", "description": "Any of the settings, with WhatsApp's values (`readReceipts`: `all` or `none`). Each setting is one change on WhatsApp.", "properties": { "groupAdd": { "type": "string", "maxLength": 32 }, "lastSeen": { "type": "string", "maxLength": 32 }, "stories": { "type": "string", "maxLength": 32 }, "profile": { "type": "string", "maxLength": 32 }, "readReceipts": { "type": "string", "maxLength": 32 }, "online": { "type": "string", "maxLength": 32 }, "callAdd": { "type": "string", "maxLength": 32 }, "messages": { "type": "string", "maxLength": 32 } }, "minProperties": 1 }, "StoryPrivacy": { "type": "object", "description": "Who sees the account's stories.", "properties": { "object": { "type": "string", "const": "story_privacy", "description": "Always `story_privacy`.", "readOnly": true }, "lists": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contacts", "blacklist", "whitelist" ], "description": "- `contacts`: All contacts.\n- `blacklist`: All contacts except `contactIds`.\n- `whitelist`: Only `contactIds`." }, "contactIds": { "type": "array", "items": { "type": "string" } }, "default": { "type": "boolean", "description": "The list in use." } }, "required": [ "type", "contactIds", "default" ] } } }, "required": [ "object", "lists" ], "examples": [ { "object": "story_privacy", "lists": [ { "type": "contacts", "contactIds": [], "default": true } ] } ] }, "CallRejectRequest": { "type": "object", "properties": { "from": { "type": "string", "description": "The caller, as in the `call.received` event (`data.object.from`).", "maxLength": 128 } }, "required": [ "from" ] }, "StickerPack": { "type": "object", "description": "A sticker pack.", "properties": { "object": { "type": "string", "const": "sticker_pack", "description": "Always `sticker_pack`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "name": { "type": "string" }, "publisher": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "animated": { "type": "boolean" }, "trayImageId": { "type": [ "string", "null" ] }, "stickers": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "directPath": { "type": [ "string", "null" ] }, "sizeBytes": { "type": "integer" }, "mimeType": { "type": [ "string", "null" ] }, "width": { "type": "integer" }, "height": { "type": "integer" }, "emojis": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "directPath", "sizeBytes", "mimeType", "width", "height", "emojis" ] } } }, "required": [ "object", "id", "name", "publisher", "description", "animated", "trayImageId", "stickers" ], "examples": [ { "object": "sticker_pack", "id": "4a0b1c2d-sticker-pack", "name": "Office life", "publisher": "Acme", "description": null, "animated": false, "trayImageId": null, "stickers": [] } ] }, "Order": { "type": "object", "description": "A catalog order.", "properties": { "object": { "type": "string", "const": "order", "description": "Always `order`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "currency": { "type": "string", "description": "Lowercase ISO 4217." }, "subtotalCents": { "type": "integer", "description": "In cents (minor units)." }, "totalCents": { "type": "integer" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "priceCents": { "type": "integer" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "quantity", "priceCents", "currency", "imageUrl" ] } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "currency", "subtotalCents", "totalCents", "products", "createdAt" ], "examples": [ { "object": "order", "id": "1234567890123456", "currency": "usd", "subtotalCents": 2500, "totalCents": 2500, "products": [ { "id": "sku-1", "name": "Mug", "quantity": 1, "priceCents": 2500, "currency": "usd", "imageUrl": null } ], "createdAt": "2026-09-24T08:15:40.000Z" } ] }, "GroupParticipant": { "type": "object", "properties": { "contactId": { "type": "string", "description": "A contact id: E.164 (`+584241112233`), or `lid:` when WhatsApp hides the number." }, "name": { "type": [ "string", "null" ], "description": "The member's name as this account knows it." }, "role": { "type": "string", "enum": [ "member", "admin", "owner" ], "description": "- `member`: A member.\n- `admin`: An admin.\n- `owner`: The creator (super admin)." } }, "required": [ "contactId", "name", "role" ] }, "Group": { "type": "object", "description": "A WhatsApp group, read live from WhatsApp.", "properties": { "object": { "type": "string", "const": "group", "description": "Always `group`.", "readOnly": true }, "id": { "type": "string", "description": "Group id (`...@g.us`).", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ], "description": "The creator's contact id." }, "community": { "type": "boolean", "description": "A community: it links other groups (its subgroups)." }, "locked": { "type": "boolean", "description": "Only admins can edit the group info." }, "announce": { "type": "boolean", "description": "Only admins can send." }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/GroupParticipant" } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "accountId", "name", "description", "ownerId", "community", "locked", "announce", "participants", "createdAt" ], "examples": [ { "object": "group", "id": "120363041234567890@g.us", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Launch team", "description": "Coordination for the September launch.", "ownerId": "+584121234567", "community": false, "locked": false, "announce": false, "participants": [ { "contactId": "+584121234567", "name": "Acme Support", "role": "owner" }, { "contactId": "+584241112233", "name": "Maria", "role": "member" }, { "contactId": "lid:201843727138927", "name": null, "role": "member" } ], "createdAt": "2026-09-01T12:00:00.000Z" } ] }, "GroupList": { "type": "object", "description": "A page of `Group` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "GroupCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "participants": { "type": "array", "items": { "type": "string" }, "description": "Contact ids. Required and non-empty unless `community` is true." }, "community": { "type": "boolean", "description": "Create a community instead of a group; `participants` may be empty." } }, "required": [ "name" ] }, "GroupUpdateRequest": { "type": "object", "description": "Provide at least one field.", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 2048 }, "announce": { "type": "boolean", "description": "Only admins can send." }, "locked": { "type": "boolean", "description": "Only admins can edit the group info." }, "joinApproval": { "type": "boolean", "description": "New members need admin approval." }, "memberAddMode": { "type": "string", "enum": [ "admins", "all_members" ], "description": "- `admins`: Only admins add members.\n- `all_members`: Any member adds members." } }, "minProperties": 1 }, "ContactIdsRequest": { "type": "object", "properties": { "contactIds": { "type": "array", "items": { "type": "string" }, "description": "1 to 256 contact ids.", "minItems": 1, "maxItems": 256 } }, "required": [ "contactIds" ] }, "ParticipantResult": { "type": "object", "description": "The outcome for one contact.", "properties": { "object": { "type": "string", "const": "participant_result", "description": "Always `participant_result`.", "readOnly": true }, "contactId": { "type": "string" }, "error": { "type": [ "string", "null" ], "description": "Why this contact failed, for example `privacy_restricted`, `already_member`, `not_on_whatsapp`. `null` when it worked." }, "inviteCode": { "type": [ "string", "null" ], "description": "Returned instead of an add when the person must be invited." } }, "required": [ "object", "contactId", "error", "inviteCode" ], "examples": [ { "object": "participant_result", "contactId": "+584241112233", "error": null, "inviteCode": null } ] }, "ParticipantResultList": { "type": "object", "description": "A page of `ParticipantResult` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ParticipantResult" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "GroupInviteLink": { "type": "object", "description": "A group's invite link.", "properties": { "object": { "type": "string", "const": "group_invite_link", "description": "Always `group_invite_link`.", "readOnly": true }, "groupId": { "type": "string" }, "url": { "type": "string" } }, "required": [ "object", "groupId", "url" ], "examples": [ { "object": "group_invite_link", "groupId": "120363041234567890@g.us", "url": "https://chat.whatsapp.com/AbCdEf123456" } ] }, "GroupJoinRequest": { "type": "object", "properties": { "code": { "type": "string", "description": "The invite code or the full `https://chat.whatsapp.com/...` link.", "maxLength": 256 } }, "required": [ "code" ] }, "GroupJoin": { "type": "object", "description": "The group the account joined.", "properties": { "object": { "type": "string", "const": "group_join", "description": "Always `group_join`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "groupId": { "type": [ "string", "null" ], "description": "The group joined." } }, "required": [ "object", "accountId", "groupId" ], "examples": [ { "object": "group_join", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "groupId": "120363041234567890@g.us" } ] }, "GroupJoinRequestItem": { "type": "object", "description": "A request to join a group that needs approval.", "properties": { "object": { "type": "string", "const": "group_join_request", "description": "Always `group_join_request`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "groupId": { "type": "string" }, "contactId": { "type": "string", "description": "A contact id: E.164 (`+584241112233`), or `lid:` when WhatsApp hides the number." }, "requestedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "accountId", "groupId", "contactId", "requestedAt" ], "examples": [ { "object": "group_join_request", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "groupId": "120363041234567890@g.us", "contactId": "+584241112233", "requestedAt": "2026-09-24T08:15:40.000Z" } ] }, "GroupJoinRequestItemList": { "type": "object", "description": "A page of `GroupJoinRequestItem` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/GroupJoinRequestItem" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "Subgroup": { "type": "object", "description": "A group linked to a community.", "properties": { "object": { "type": "string", "const": "subgroup", "description": "Always `subgroup`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "name": { "type": "string" }, "default": { "type": "boolean", "description": "The community's announcement group." } }, "required": [ "object", "id", "name", "default" ], "examples": [ { "object": "subgroup", "id": "120363055512345678@g.us", "name": "Announcements", "default": true } ] }, "SubgroupList": { "type": "object", "description": "A page of `Subgroup` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Subgroup" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "SubgroupLinkRequest": { "type": "object", "properties": { "groupId": { "type": "string", "description": "The group to link into the community (`...@g.us`).", "maxLength": 64 } }, "required": [ "groupId" ] }, "CommunityParticipant": { "type": "object", "description": "A member of a community's linked groups.", "properties": { "object": { "type": "string", "const": "community_participant", "description": "Always `community_participant`.", "readOnly": true }, "contactId": { "type": "string", "description": "A contact id: E.164 (`+584241112233`), or `lid:` when WhatsApp hides the number." } }, "required": [ "object", "contactId" ], "examples": [ { "object": "community_participant", "contactId": "+584241112233" } ] }, "CommunityParticipantList": { "type": "object", "description": "A page of `CommunityParticipant` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CommunityParticipant" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "Channel": { "type": "object", "description": "A WhatsApp channel.", "properties": { "object": { "type": "string", "const": "channel", "description": "Always `channel`.", "readOnly": true }, "id": { "type": "string", "description": "Channel id (`...@newsletter`).", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "inviteCode": { "type": [ "string", "null" ] }, "subscriberCount": { "type": "integer" }, "verified": { "type": "boolean" }, "status": { "type": [ "string", "null" ], "description": "WhatsApp's state of the channel, for example `active`." }, "role": { "type": [ "string", "null" ], "description": "The account's role: `owner`, `admin`, `subscriber`, ..." }, "muted": { "type": "boolean" }, "pictureUrl": { "type": [ "string", "null" ] }, "previewUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "accountId", "name", "description", "inviteCode", "subscriberCount", "verified", "status", "role", "muted", "pictureUrl", "previewUrl", "createdAt" ], "examples": [ { "object": "channel", "id": "120363198765432101@newsletter", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "name": "Acme News", "description": "Product updates.", "inviteCode": "0029VaABCDEFghijKLmn1234", "subscriberCount": 1204, "verified": false, "status": "active", "role": "owner", "muted": false, "pictureUrl": null, "previewUrl": null, "createdAt": "2026-08-02T10:00:00.000Z" } ] }, "ChannelList": { "type": "object", "description": "A page of `Channel` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "ChannelCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 2048 }, "pictureBase64": { "type": "string", "description": "JPEG, base64.", "maxLength": 5000000 } }, "required": [ "name" ] }, "ChannelMessage": { "type": "object", "description": "A message in a channel, read live from WhatsApp.", "properties": { "object": { "type": "string", "const": "channel_message", "description": "Always `channel_message`.", "readOnly": true }, "id": { "type": "string", "description": "WhatsApp's server id of the message in the channel.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "channelId": { "type": "string" }, "type": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "viewCount": { "type": [ "integer", "null" ] }, "reactions": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Count per emoji." }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "accountId", "channelId", "type", "text", "viewCount", "reactions", "sentAt" ], "examples": [ { "object": "channel_message", "id": "142", "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "channelId": "120363198765432101@newsletter", "type": "text", "text": "Version 2.4 is out.", "viewCount": 860, "reactions": { "🎉": 41 }, "sentAt": "2026-09-24T08:15:40.000Z" } ] }, "ChannelMessageList": { "type": "object", "description": "A page of `ChannelMessage` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMessage" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "MarkViewedRequest": { "type": "object", "properties": { "channelMessageIds": { "type": "array", "items": { "type": "string" }, "description": "1 to 100 channel message ids.", "minItems": 1, "maxItems": 100 } }, "required": [ "channelMessageIds" ] }, "WebhookEventType": { "type": "string", "enum": [ "account.qr_code_issued", "account.pairing_code_issued", "account.connected", "account.disconnected", "account.failed", "message.received", "message.sent", "message.delivered", "message.read", "message.failed", "message.edited", "message.deleted", "poll.voted", "group.joined", "group.updated", "group.join_requested", "group.join_request_revoked", "chat.updated", "chat.presence_updated", "contact.presence_updated", "contact.picture_updated", "contact.updated", "blocklist.updated", "label.updated", "call.received", "call.ended", "channel.message_received", "channel.message_updated", "channel.updated", "history.synced", "project.created", "project.updated", "project.deleted", "invitation.status_changed", "webhook.test" ], "description": "Event types. See the Webhooks tag for when each fires." }, "WebhookEndpoint": { "type": "object", "description": "A URL that receives events.", "properties": { "object": { "type": "string", "const": "webhook_endpoint", "description": "Always `webhook_endpoint`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "projectId": { "type": [ "string", "null" ], "description": "`null`: an organization endpoint, which receives every project's events. Set: a project endpoint, which receives only that project's events." }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "active": { "type": "boolean", "description": "Inactive endpoints receive nothing." }, "secret": { "type": "string", "description": "Signing secret (`whsec_...`). Returned only by create and rotate-secret." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "object", "id", "projectId", "url", "events", "active", "createdAt", "updatedAt" ], "examples": [ { "object": "webhook_endpoint", "id": "n97p31n8b5c7z2y4u6ebt5gr1ew3qa8s", "projectId": null, "url": "https://example.com/webhooks/wuapi", "events": [ "message.received", "account.disconnected" ], "active": true, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-20T14:00:03.000Z" } ] }, "WebhookEndpointList": { "type": "object", "description": "A page of `WebhookEndpoint` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "WebhookEndpointCreateRequest": { "type": "object", "properties": { "url": { "type": "string", "description": "Public https URL.", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "minItems": 1 }, "projectId": { "type": "string", "description": "Organization keys only: make it a project endpoint (id or `ext:`). Implied by a project scope.", "maxLength": 200 } }, "required": [ "url", "events" ] }, "WebhookEndpointUpdateRequest": { "type": "object", "description": "Provide at least one field.", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "minItems": 1 }, "active": { "type": "boolean" } }, "minProperties": 1 }, "Period": { "type": "object", "description": "A calendar month in UTC.", "properties": { "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } }, "required": [ "startsAt", "endsAt" ] }, "UsageLine": { "type": "object", "properties": { "billableAccountCount": { "type": "integer", "description": "Accounts billable right now." }, "accountCount": { "type": "integer", "description": "Accounts that are not deleted, right now." }, "proxyBytes": { "type": "integer", "description": "Proxy traffic in the month, in bytes." }, "sentMessageCount": { "type": "integer", "description": "API sends WhatsApp accepted, plus messages sent from the phone and seen live, in the month." }, "receivedMessageCount": { "type": "integer", "description": "Contacts' messages seen live in the month. History imports count for neither." } }, "required": [ "billableAccountCount", "accountCount", "proxyBytes", "sentMessageCount", "receivedMessageCount" ] }, "Usage": { "type": "object", "description": "Billable usage for the current calendar month (UTC).", "properties": { "object": { "type": "string", "const": "usage", "description": "Always `usage`.", "readOnly": true }, "period": { "$ref": "#/components/schemas/Period" }, "currency": { "type": "string", "description": "Always `usd`." }, "billableAccountCount": { "type": "integer", "description": "Accounts billable right now." }, "accountUnitPriceCents": { "type": "integer", "description": "Price of the band the last billable account falls in: 600 for account 1, 450 each for 2-50, 350 each from the 51st. Bands are graduated: each account is billed at its own band's price." }, "accountFeeCents": { "type": "integer", "description": "The graduated total for `billableAccountCount` accounts: 600 for account 1, 450 each for 2-50, 350 each from the 51st." }, "proxyBytes": { "type": "integer", "description": "Every byte of residential proxy traffic this month, included or not, traffic used on the Free plan included." }, "includedProxyBytes": { "type": "integer", "description": "This month's pooled proxy allowance: 0.5 GB (536870912 bytes) per billable account, counted at the most accounts billable this month." }, "billableProxyBytes": { "type": "integer", "description": "Proxy bytes past `includedProxyBytes`, leaving out traffic used on the Free plan (or during a legacy free trial). `proxyFeeCents` bills these only." }, "proxyFeeCents": { "type": "integer", "description": "`billableProxyBytes` at $0.99 per GB (1 GB = 1024^3 bytes), rounded to the cent. Traffic within the allowance costs nothing." }, "totalCents": { "type": "integer", "description": "`accountFeeCents` + `proxyFeeCents`." } }, "required": [ "object", "period", "currency", "billableAccountCount", "accountUnitPriceCents", "accountFeeCents", "proxyBytes", "includedProxyBytes", "billableProxyBytes", "proxyFeeCents", "totalCents" ], "examples": [ { "object": "usage", "period": { "startsAt": "2026-09-01T00:00:00.000Z", "endsAt": "2026-10-01T00:00:00.000Z" }, "currency": "usd", "billableAccountCount": 4, "accountUnitPriceCents": 450, "accountFeeCents": 1950, "proxyBytes": 5368709120, "includedProxyBytes": 2147483648, "billableProxyBytes": 3221225472, "proxyFeeCents": 297, "totalCents": 2247 } ] }, "UsageReportProject": { "type": "object", "properties": { "projectId": { "type": "string" }, "externalId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "billableAccountCount": { "type": "integer", "description": "Accounts billable right now." }, "accountCount": { "type": "integer", "description": "Accounts that are not deleted, right now." }, "proxyBytes": { "type": "integer", "description": "Proxy traffic in the month, in bytes." }, "sentMessageCount": { "type": "integer", "description": "API sends WhatsApp accepted, plus messages sent from the phone and seen live, in the month." }, "receivedMessageCount": { "type": "integer", "description": "Contacts' messages seen live in the month. History imports count for neither." } }, "required": [ "projectId", "externalId", "name", "billableAccountCount", "accountCount", "proxyBytes", "sentMessageCount", "receivedMessageCount" ] }, "UsageReport": { "type": "object", "description": "The rebilling export: one line per project, plus unassigned resources and totals.", "properties": { "object": { "type": "string", "const": "usage_report", "description": "Always `usage_report`.", "readOnly": true }, "period": { "$ref": "#/components/schemas/Period" }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/UsageReportProject" }, "description": "Every live project, plus deleted projects that used something in the month." }, "unassigned": { "$ref": "#/components/schemas/UsageLine" }, "totals": { "$ref": "#/components/schemas/UsageLine" } }, "required": [ "object", "period", "projects", "unassigned", "totals" ], "examples": [ { "object": "usage_report", "period": { "startsAt": "2026-09-01T00:00:00.000Z", "endsAt": "2026-10-01T00:00:00.000Z" }, "projects": [ { "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "externalId": "customer_8812", "name": "Northwind Dental", "billableAccountCount": 1, "accountCount": 1, "proxyBytes": 52428800, "sentMessageCount": 812, "receivedMessageCount": 1290 } ], "unassigned": { "billableAccountCount": 2, "accountCount": 2, "proxyBytes": 10485760, "sentMessageCount": 40, "receivedMessageCount": 51 }, "totals": { "billableAccountCount": 3, "accountCount": 3, "proxyBytes": 62914560, "sentMessageCount": 852, "receivedMessageCount": 1341 } } ] }, "ProjectUsage": { "type": "object", "description": "A project's usage.", "properties": { "object": { "type": "string", "const": "project_usage", "description": "Always `project_usage`.", "readOnly": true }, "projectId": { "type": "string" }, "period": { "$ref": "#/components/schemas/Period" }, "billableAccountCount": { "type": "integer", "description": "Accounts billable right now." }, "accountCount": { "type": "integer", "description": "Accounts that are not deleted, right now." }, "proxyBytes": { "type": "integer", "description": "Proxy traffic in the month, in bytes." }, "sentMessageCount": { "type": "integer", "description": "API sends WhatsApp accepted, plus messages sent from the phone and seen live, in the month." }, "receivedMessageCount": { "type": "integer", "description": "Contacts' messages seen live in the month. History imports count for neither." } }, "required": [ "object", "projectId", "period", "billableAccountCount", "accountCount", "proxyBytes", "sentMessageCount", "receivedMessageCount" ], "examples": [ { "object": "project_usage", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "period": { "startsAt": "2026-09-01T00:00:00.000Z", "endsAt": "2026-10-01T00:00:00.000Z" }, "billableAccountCount": 1, "accountCount": 1, "proxyBytes": 52428800, "sentMessageCount": 812, "receivedMessageCount": 1290 } ] }, "ProjectStatus": { "type": "string", "enum": [ "active", "suspended" ], "description": "- `active`: Normal.\n- `suspended`: Accounts stay linked and keep receiving; every send and write answers `403 project_suspended`." }, "Project": { "type": "object", "description": "A customer of your platform, or an environment.", "properties": { "object": { "type": "string", "const": "project", "description": "Always `project`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "name": { "type": "string" }, "externalId": { "type": [ "string", "null" ], "description": "Your own id for this customer, unique among live projects." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "maxAccounts": { "type": [ "integer", "null" ], "description": "Account limit. `null` means no limit." }, "accountCount": { "type": "integer", "description": "Accounts that are not deleted." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "object", "id", "name", "externalId", "metadata", "status", "maxAccounts", "accountCount", "createdAt", "updatedAt" ], "examples": [ { "object": "project", "id": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "name": "Northwind Dental", "externalId": "customer_8812", "metadata": { "plan": "growth" }, "status": "active", "maxAccounts": 3, "accountCount": 1, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } ] }, "ProjectList": { "type": "object", "description": "A page of `Project` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "ProjectCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "externalId": { "type": "string", "description": "1 to 128 characters: letters, digits and `. _ : @ -`.", "pattern": "^[A-Za-z0-9._:@-]{1,128}$" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Up to 50 string values; keys 1-64 printable ASCII characters not starting with `$` or `_`." }, "maxAccounts": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "name" ] }, "ProjectUpdateRequest": { "type": "object", "description": "Provide at least one field.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "externalId": { "type": [ "string", "null" ], "description": "`null` clears it.", "pattern": "^[A-Za-z0-9._:@-]{1,128}$" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50, "description": "Replaces the whole metadata object." }, "maxAccounts": { "type": [ "integer", "null" ], "description": "`null` removes the limit.", "minimum": 0, "maximum": 10000 }, "status": { "$ref": "#/components/schemas/ProjectStatus" } }, "minProperties": 1 }, "ApiKey": { "type": "object", "description": "An API key. The key itself is shown once.", "properties": { "object": { "type": "string", "const": "api_key", "description": "Always `api_key`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "name": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "Set for a project key, which reaches only that project." }, "keyPrefix": { "type": "string" }, "last4": { "type": "string" }, "key": { "type": "string", "description": "The key itself. Returned only when it is created." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "name", "projectId", "keyPrefix", "last4", "createdAt", "lastUsedAt", "revokedAt" ], "examples": [ { "object": "api_key", "id": "j48c2d5e8f1g4h7i0k3l6m9n2p5q8r1s", "name": "Northwind production", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "keyPrefix": "wu_live_9c9c", "last4": "9c9c", "createdAt": "2026-09-24T08:15:40.000Z", "lastUsedAt": null, "revokedAt": null } ] }, "ApiKeyList": { "type": "object", "description": "A page of `ApiKey` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "ApiKeyCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] }, "InvitationStatus": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "cancelled", "expired" ], "description": "- `pending`: Created or resent.\n- `in_progress`: The invitee started linking and the account exists.\n- `completed`: The account reached `ready`.\n- `failed`: Linking stopped (`failureReason`); the link keeps working and a retry reuses the account.\n- `cancelled`: Cancelled by you.\n- `expired`: Pending or failed past `expiresAt`. Computed on read, never stored." }, "InvitationMethod": { "type": "string", "enum": [ "qr_code", "pairing_code" ], "description": "- `qr_code`: Scan a live QR code.\n- `pairing_code`: Type an 8-character pairing code on the phone." }, "Invitation": { "type": "object", "description": "A hosted page someone else opens to link their own number into a project.", "properties": { "object": { "type": "string", "const": "invitation", "description": "Always `invitation`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "projectId": { "type": [ "string", "null" ], "description": "Project the resource belongs to, `null` when it is in no project. Set at creation and never changes." }, "status": { "$ref": "#/components/schemas/InvitationStatus" }, "url": { "type": [ "string", "null" ], "description": "The page to send. Returned only by create and resend: the token is stored hashed and cannot be shown again." }, "inviteeName": { "type": [ "string", "null" ], "description": "Shown on the page as \"Setting up for ...\"." }, "inviteeEmail": { "type": [ "string", "null" ], "description": "Where the invitation email goes." }, "inviteePhone": { "type": [ "string", "null" ], "description": "E.164. Preselects the country and prefills the pairing code form." }, "suggestedCountry": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 preselected on the page." }, "proxyLocation": { "oneOf": [ { "$ref": "#/components/schemas/ProxyLocation" }, { "type": "null" } ], "description": "Where the account's residential proxy will exit: set on create, or picked by the invitee on the page before the QR code or pairing code is shown. `null` until then." }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationMethod" }, "description": "Linking methods the page offers." }, "historySync": { "allOf": [ { "$ref": "#/components/schemas/HistorySyncSetting" } ], "description": "The `historySync` of the account the invitee links." }, "accountName": { "type": [ "string", "null" ], "description": "Name the account gets. Default: `inviteeName`, else the WhatsApp profile name." }, "accountId": { "type": [ "string", "null" ], "description": "The account created for the invitee. Set once `status` is `completed`." }, "failureReason": { "type": [ "string", "null" ], "description": "Why linking stopped, while `status` is `failed`: `abandoned` (in progress for 1 hour without linking), `qr_timeout`, `logged_out`, `temporary_ban`, `connect_failed` or `account_deleted`." }, "returnUrl": { "type": [ "string", "null" ], "description": "After linking, the page links back here with `?invitation_id=...&account_id=...`." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Copied onto the account on completion." }, "emailSentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the invitation email was last queued. `null` without an email, or when email is not enabled: send `url` yourself." }, "expiresAt": { "type": "string", "format": "date-time" }, "viewedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "First time the page was opened." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last time the invitee started linking." }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "object", "id", "projectId", "status", "url", "inviteeName", "inviteeEmail", "inviteePhone", "suggestedCountry", "proxyLocation", "methods", "historySync", "accountName", "accountId", "failureReason", "returnUrl", "metadata", "emailSentAt", "expiresAt", "viewedAt", "startedAt", "completedAt", "createdAt", "updatedAt" ], "examples": [ { "object": "invitation", "id": "q64x2v7b1n9m3c8z5a0s4d6f2g7h1j3k", "projectId": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "status": "pending", "url": "https://wuapi.dev/invite/9f2c6a1e0b7d4c3a8e5f1b2d7c9a0e4f6b8d1c3a5e7f9b0d2c4e6a8b1d3f5a7c", "inviteeName": "Maria Perez", "inviteeEmail": "maria@example.com", "inviteePhone": null, "suggestedCountry": "MX", "proxyLocation": { "country": "MX", "city": "mexicocity", "strictCity": false }, "methods": [ "qr_code", "pairing_code" ], "historySync": "none", "accountName": "Front desk", "accountId": null, "failureReason": null, "returnUrl": "https://app.example.com/settings/whatsapp", "metadata": { "store": "cdmx-2" }, "emailSentAt": "2026-09-24T08:15:40.000Z", "expiresAt": "2026-10-01T08:15:40.000Z", "viewedAt": null, "startedAt": null, "completedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } ] }, "InvitationList": { "type": "object", "description": "A page of `Invitation` objects.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`.", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. `null` on the last page." } }, "required": [ "object", "items", "nextCursor" ] }, "InvitationCreateRequest": { "type": "object", "description": "Every field is optional. The subscription gate, suspension and the project's `maxAccounts` are checked now and again when the invitee starts.", "properties": { "projectId": { "type": "string", "description": "Organization keys: the project the account lands in (id or `ext:`). A project key invites into its own project.", "maxLength": 200 }, "accountName": { "type": "string", "description": "Name of the account created on completion.", "maxLength": 100 }, "inviteeName": { "type": "string", "maxLength": 100 }, "inviteeEmail": { "type": "string", "description": "With an email, the invitation is emailed when email is enabled (see `emailSentAt`).", "format": "email", "maxLength": 254 }, "inviteePhone": { "type": "string", "description": "E.164.", "maxLength": 32 }, "suggestedCountry": { "type": "string", "description": "ISO 3166-1 alpha-2 preselected on the page when `proxyLocation` is not set. Derived from `inviteePhone` when absent.", "minLength": 2, "maxLength": 2 }, "proxyLocation": { "allOf": [ { "$ref": "#/components/schemas/ProxyLocationInput" } ], "description": "Preset where the account's proxy exits: a pair from `GET /v1/proxy-locations`. Without it the invitee picks the country and city on the page. Not in the catalog: `400 unsupported_proxy_location`." }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationMethod" }, "description": "Default both.", "minItems": 1 }, "historySync": { "allOf": [ { "$ref": "#/components/schemas/HistorySyncSetting" } ], "description": "Import the recent chats the invitee's phone sends when the number links: `recent`. Default `none`." }, "returnUrl": { "type": "string", "description": "https.", "format": "uri", "maxLength": 2048 }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 20, "description": "Up to 20 string values, keys 1 to 40 characters. Copied onto the account on completion." } } }, "Branding": { "type": "object", "description": "What the invitation page and email show.", "properties": { "object": { "type": "string", "const": "branding", "description": "Always `branding`.", "readOnly": true }, "displayName": { "type": [ "string", "null" ], "description": "Shown on the invitation page and email. `null` until set." }, "logoUrl": { "type": [ "string", "null" ], "description": "The logo the page and email show: a file uploaded in the dashboard when there is one, else the https URL you set." }, "accentColor": { "type": [ "string", "null" ], "description": "`#RRGGBB`." }, "supportUrl": { "type": [ "string", "null" ] }, "hideWuapiBranding": { "type": "boolean", "description": "Whether the \"Powered by wuapi\" footer is hidden right now: your setting, and only while the White label add-on is active." } }, "required": [ "object", "displayName", "logoUrl", "accentColor", "supportUrl", "hideWuapiBranding" ], "examples": [ { "object": "branding", "displayName": "Northwind Cloud", "logoUrl": "https://cdn.example.com/logo.png", "accentColor": "#0F766E", "supportUrl": "https://help.example.com", "hideWuapiBranding": true } ] }, "BrandingUpdateRequest": { "type": "object", "description": "Provide at least one field.", "properties": { "displayName": { "type": "string", "description": "1 to 60 characters after trimming. It cannot be cleared. Required while the organization has no branding yet: the first update without it answers `400 invalid_request` with `details.field: displayName`.", "minLength": 1, "maxLength": 60 }, "logoUrl": { "type": [ "string", "null" ], "description": "https URL; `null` clears it. Either one replaces a logo uploaded in the dashboard.", "format": "uri", "maxLength": 2048 }, "accentColor": { "type": [ "string", "null" ], "description": "`#RRGGBB`; `null` clears it.", "pattern": "^#[0-9a-fA-F]{6}$" }, "supportUrl": { "type": [ "string", "null" ], "description": "https URL; `null` clears it.", "format": "uri", "maxLength": 2048 }, "hideWuapiBranding": { "type": "boolean", "description": "Hide the \"Powered by wuapi\" footer on the page and the email line. `true` needs the White label add-on (`402 addon_required` without it); `false` always works." } }, "minProperties": 1 }, "Organization": { "type": "object", "properties": { "object": { "type": "string", "const": "organization", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "name": { "type": "string" } }, "required": [ "object", "id", "name" ] }, "AuthContext": { "type": "object", "description": "The organization, API key and project behind the current request.", "properties": { "object": { "type": "string", "const": "auth_context", "description": "Always `auth_context`.", "readOnly": true }, "organization": { "$ref": "#/components/schemas/Organization" }, "apiKey": { "$ref": "#/components/schemas/ApiKey" }, "project": { "oneOf": [ { "$ref": "#/components/schemas/Project" }, { "type": "null" } ], "description": "The project this request is scoped to (from the key or `Wuapi-Project`). `null` for the whole organization." } }, "required": [ "object", "organization", "apiKey", "project" ], "examples": [ { "object": "auth_context", "organization": { "object": "organization", "id": "w82t6y1u5i9o3p7a2s6d0f4g8h2j6k1l", "name": "Acme" }, "apiKey": { "object": "api_key", "id": "j48c2d5e8f1g4h7i0k3l6m9n2p5q8r1s", "name": "Production", "projectId": null, "keyPrefix": "wu_live_9c9c", "last4": "9c9c", "createdAt": "2026-09-24T08:15:40.000Z", "lastUsedAt": null, "revokedAt": null }, "project": { "object": "project", "id": "p23f9g0h1j2k3l4m5n6o7q8r9s0t1u2v", "name": "Northwind Dental", "externalId": "customer_8812", "metadata": { "plan": "growth" }, "status": "active", "maxAccounts": 3, "accountCount": 1, "createdAt": "2026-09-20T14:00:03.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } ] }, "PollVote": { "type": "object", "description": "A vote in a poll.", "properties": { "object": { "type": "string", "const": "poll_vote", "description": "Always `poll_vote`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "chatId": { "type": [ "string", "null" ] }, "messageId": { "type": [ "string", "null" ], "description": "The poll's wuapi id, when wuapi stores it." }, "voterId": { "type": "string", "description": "A contact id: E.164 (`+584241112233`), or `lid:` when WhatsApp hides the number." }, "options": { "type": "array", "items": { "type": "string" }, "description": "Option names; empty when the vote was retracted or the poll is unknown to the engine." }, "votedAt": { "type": "string", "format": "date-time" }, "poll": { "oneOf": [ { "$ref": "#/components/schemas/Message" }, { "type": "null" } ], "description": "The poll with its new tally, when wuapi stores it." } }, "required": [ "object", "accountId", "chatId", "messageId", "voterId", "options", "votedAt", "poll" ] }, "GroupChange": { "type": "object", "description": "A change to a group. Fields that did not change are `null` or empty.", "properties": { "object": { "type": "string", "const": "group_change", "description": "Always `group_change`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "groupId": { "type": "string" }, "actorId": { "type": [ "string", "null" ], "description": "Who made the change, when WhatsApp says." }, "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "promoted": { "type": "array", "items": { "type": "string" } }, "demoted": { "type": "array", "items": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "The new name, when it changed." }, "description": { "type": [ "string", "null" ], "description": "The new description, when it changed." }, "locked": { "type": [ "boolean", "null" ] }, "announce": { "type": [ "boolean", "null" ] }, "changes": { "type": "array", "items": { "type": "string", "enum": [ "participants_added", "participants_removed", "admins_changed", "name", "description", "settings" ] }, "description": "What moved." }, "changedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "accountId", "groupId", "actorId", "added", "removed", "promoted", "demoted", "name", "description", "locked", "announce", "changes", "changedAt" ] }, "ChatChange": { "type": "object", "description": "A chat changed on the phone or another device.", "properties": { "object": { "type": "string", "const": "chat_change", "description": "Always `chat_change`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "chatId": { "type": "string" }, "change": { "type": "string", "enum": [ "archive", "pin", "mute", "read", "delete", "clear", "star" ] }, "value": { "type": [ "boolean", "null" ], "description": "The new value (`true` = archived, pinned, muted, read, starred)." }, "messageId": { "type": [ "string", "null" ], "description": "Star changes: the wuapi id of the message, when stored." }, "muteExpiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Mute changes: when the mute ends. `null` for a mute with no end." } }, "required": [ "object", "accountId", "chatId", "change", "value", "messageId", "muteExpiresAt" ] }, "ChatPresence": { "type": "object", "description": "A contact is typing or recording in a chat.", "properties": { "object": { "type": "string", "const": "chat_presence", "description": "Always `chat_presence`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "chatId": { "type": "string" }, "contactId": { "type": "string" }, "state": { "type": "string", "enum": [ "typing", "recording", "paused" ] } }, "required": [ "object", "accountId", "chatId", "contactId", "state" ] }, "ContactPresence": { "type": "object", "description": "A subscribed contact came online or went offline.", "properties": { "object": { "type": "string", "const": "contact_presence", "description": "Always `contact_presence`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "contactId": { "type": "string" }, "online": { "type": "boolean" }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When shared." } }, "required": [ "object", "accountId", "contactId", "online", "lastSeenAt" ] }, "PictureChange": { "type": "object", "description": "A contact or group picture changed or was removed.", "properties": { "object": { "type": "string", "const": "picture_change", "description": "Always `picture_change`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "chatId": { "type": "string", "description": "The contact or group whose picture changed." }, "pictureId": { "type": [ "string", "null" ] }, "removed": { "type": "boolean" }, "changedBy": { "type": [ "string", "null" ], "description": "Who changed it (groups)." }, "changedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "accountId", "chatId", "pictureId", "removed", "changedBy", "changedAt" ] }, "BlocklistChange": { "type": "object", "description": "The blocklist changed.", "properties": { "object": { "type": "string", "const": "blocklist_change", "description": "Always `blocklist_change`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "changes": { "type": "array", "items": { "type": "object", "properties": { "contactId": { "type": "string", "description": "The contact: E.164 when the account knows the number, `lid:` otherwise." }, "action": { "type": "string", "enum": [ "block", "unblock" ] }, "phone": { "type": [ "string", "null" ], "description": "The contact's number (E.164) when known." }, "lid": { "type": [ "string", "null" ], "description": "The contact's LID (`lid:`) when known." } }, "required": [ "contactId", "action", "phone", "lid" ] }, "description": "Who was blocked or unblocked. When WhatsApp only says the list changed, wuapi compares it with the list it saw before and names the changes." }, "refetch": { "type": "boolean", "description": "`true` (with `changes` empty) when WhatsApp gave no changes and there was no earlier list to compare with: call `GET .../blocklist`." } }, "required": [ "object", "accountId", "changes", "refetch" ] }, "LabelChange": { "type": "object", "description": "A label was edited or (un)assigned.", "properties": { "object": { "type": "string", "const": "label_change", "description": "Always `label_change`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "kind": { "type": "string", "enum": [ "label", "chat", "message" ], "description": "- `label`: The label itself was edited.\n- `chat`: A chat was (un)labeled.\n- `message`: A message was (un)labeled." }, "labelId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "color": { "type": [ "integer", "null" ] }, "deleted": { "type": [ "boolean", "null" ] }, "chatId": { "type": [ "string", "null" ] }, "messageId": { "type": [ "string", "null" ], "description": "The wuapi id of the message, when stored." }, "labeled": { "type": [ "boolean", "null" ] } }, "required": [ "object", "accountId", "kind", "labelId", "name", "color", "deleted", "chatId", "messageId", "labeled" ] }, "Call": { "type": "object", "description": "A call to the account.", "properties": { "object": { "type": "string", "const": "call", "description": "Always `call`.", "readOnly": true }, "id": { "type": "string", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "from": { "type": "string", "description": "The caller's contact id." }, "video": { "type": "boolean", "description": "Reliable on `call.received` only." }, "groupId": { "type": [ "string", "null" ], "description": "Set for group calls." }, "endReason": { "type": [ "string", "null" ], "description": "Why it ended, on `call.ended`." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the call rang, on `call.received`." }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "On `call.ended`." } }, "required": [ "object", "id", "accountId", "from", "video", "groupId", "endReason", "startedAt", "endedAt" ] }, "ChannelChange": { "type": "object", "description": "The account followed, unfollowed, muted or unmuted a channel.", "properties": { "object": { "type": "string", "const": "channel_change", "description": "Always `channel_change`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "channelId": { "type": "string" }, "change": { "type": "string", "enum": [ "followed", "unfollowed", "muted", "unmuted" ] }, "name": { "type": [ "string", "null" ], "description": "On `followed`: the channel name." }, "role": { "type": [ "string", "null" ], "description": "On `unfollowed`: the role the account had." } }, "required": [ "object", "accountId", "channelId", "change", "name", "role" ] }, "HistorySync": { "type": "object", "description": "A part of the history the phone sent after linking was stored. Only for accounts with `historySync: recent`: history import is off by default.", "properties": { "object": { "type": "string", "const": "history_sync", "description": "Always `history_sync`.", "readOnly": true }, "accountId": { "type": "string", "description": "The account this belongs to." }, "chunk": { "type": [ "integer", "null" ] }, "syncType": { "type": [ "string", "null" ] }, "progress": { "type": [ "integer", "null" ] }, "part": { "type": [ "integer", "null" ] }, "conversationCount": { "type": "integer" }, "messageCount": { "type": "integer", "description": "Messages stored (with `source: history`)." }, "duplicateCount": { "type": "integer", "description": "Already stored." } }, "required": [ "object", "accountId", "chunk", "syncType", "progress", "part", "conversationCount", "messageCount", "duplicateCount" ] }, "AccountEvent": { "type": "object", "description": "Fired on real transitions: `account.qr_code_issued` when the account enters `qr_ready` (not on each QR rotation; poll the account for the current `qrCodeUrl`), `account.pairing_code_issued` when a new pairing code is issued, `account.disconnected` when the account loses its connection: at once when it does not recover on its own (`disconnectReason` `logged_out`, for example), or, for a drop the session reconnects from by itself, only if it is not `ready` again within a short reconnect grace (currently 20 seconds; `status` may then read `initializing` or `authenticating` while it keeps retrying), so a quick reconnect fires neither this nor `account.connected`; `account.connected` on `ready` (the first link, or back after `account.disconnected`), `account.failed` on `failed`. Deleting an account fires nothing.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "account.qr_code_issued", "account.pairing_code_issued", "account.connected", "account.disconnected", "account.failed" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Account" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "MessageEvent": { "type": "object", "description": "`message.sent` also fires for messages sent from the phone (`source: phone`) and for stories and channel posts. `message.deleted` carries the row with `deletedAt` set and the content cleared.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "message.received", "message.sent", "message.delivered", "message.read", "message.failed", "message.deleted" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Message" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "MessageEditedEvent": { "type": "object", "description": "A message was edited. `previousAttributes.text` is the text before.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "message.edited" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Message" }, "previousAttributes": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] } }, "required": [ "text" ] } }, "required": [ "object", "previousAttributes" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "PollVotedEvent": { "type": "object", "description": "Someone voted in a poll.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "poll.voted" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/PollVote" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "GroupJoinedEvent": { "type": "object", "description": "The account joined or created a group.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "group.joined" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Group" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "GroupUpdatedEvent": { "type": "object", "description": "A group changed.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "group.updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/GroupChange" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "GroupJoinRequestEvent": { "type": "object", "description": "Someone asked to join a group that needs approval, or withdrew the request.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "group.join_requested", "group.join_request_revoked" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/GroupJoinRequestItem" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "ChatUpdatedEvent": { "type": "object", "description": "A chat was archived, pinned, muted, marked read, deleted, cleared or a message starred, on the phone or another device. Live changes only; the initial full sync is not replayed.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "chat.updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ChatChange" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "ChatPresenceUpdatedEvent": { "type": "object", "description": "A contact is typing or recording in a chat.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "chat.presence_updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ChatPresence" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "ContactPresenceUpdatedEvent": { "type": "object", "description": "A subscribed contact came online or went offline. Subscribe with `POST .../contacts/{contactId}/subscribe-presence`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "contact.presence_updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ContactPresence" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "ContactPictureUpdatedEvent": { "type": "object", "description": "A contact or group picture changed or was removed.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "contact.picture_updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/PictureChange" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "ContactUpdatedEvent": { "type": "object", "description": "A contact changed their About text, or their WhatsApp username became known or changed. Fields WhatsApp did not send are `null`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "contact.updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Contact" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "BlocklistUpdatedEvent": { "type": "object", "description": "The blocklist changed.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "blocklist.updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/BlocklistChange" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "LabelUpdatedEvent": { "type": "object", "description": "A label was edited or (un)assigned to a chat or message. The full sync replays labels this way, which is how the label list arrives.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "label.updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/LabelChange" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "CallEvent": { "type": "object", "description": "`call.received` on an incoming call (reject it with `POST .../calls/{callId}/reject`), `call.ended` when it ends or is rejected.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "call.received", "call.ended" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Call" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "ChannelMessageEvent": { "type": "object", "description": "A new message in a followed channel, or new views and reactions on one. Not stored.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "channel.message_received", "channel.message_updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ChannelMessage" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "ChannelUpdatedEvent": { "type": "object", "description": "The account followed, unfollowed, muted or unmuted a channel.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "channel.updated" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ChannelChange" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "HistorySyncedEvent": { "type": "object", "description": "A part of the history the phone sent after linking was stored. Only for accounts with `historySync: recent`: history import is off by default.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "history.synced" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/HistorySync" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "ProjectEvent": { "type": "object", "description": "`project.deleted` fires when the background purge finishes.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "project.created", "project.updated", "project.deleted" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Project" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "InvitationStatusChangedEvent": { "type": "object", "description": "An invitation changed status (started, completed, failed, cancelled, resent). `url` is `null`. `expired` has no event. `previousAttributes.status` is the status before.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "invitation.status_changed" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the event belongs to, `null` when unassigned." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Invitation" }, "previousAttributes": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/InvitationStatus" } }, "required": [ "status" ] } }, "required": [ "object", "previousAttributes" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "WebhookTestEvent": { "type": "object", "description": "`webhook.test` is sent only when you press Send test event on an endpoint in the dashboard, to that endpoint, whether or not it subscribes to it. It is delivered once, with no retries.", "properties": { "id": { "type": "string", "description": "Event id (`evt_...`). Deduplicate on it.", "readOnly": true }, "object": { "type": "string", "const": "event", "readOnly": true }, "type": { "type": "string", "enum": [ "webhook.test" ] }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The endpoint's project, `null` for an organization endpoint." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "createdAt", "organizationId", "projectId", "data" ] }, "Event": { "description": "Body of every webhook request, discriminated by `type`.", "oneOf": [ { "$ref": "#/components/schemas/AccountEvent" }, { "$ref": "#/components/schemas/MessageEvent" }, { "$ref": "#/components/schemas/MessageEditedEvent" }, { "$ref": "#/components/schemas/PollVotedEvent" }, { "$ref": "#/components/schemas/GroupJoinedEvent" }, { "$ref": "#/components/schemas/GroupUpdatedEvent" }, { "$ref": "#/components/schemas/GroupJoinRequestEvent" }, { "$ref": "#/components/schemas/ChatUpdatedEvent" }, { "$ref": "#/components/schemas/ChatPresenceUpdatedEvent" }, { "$ref": "#/components/schemas/ContactPresenceUpdatedEvent" }, { "$ref": "#/components/schemas/ContactPictureUpdatedEvent" }, { "$ref": "#/components/schemas/ContactUpdatedEvent" }, { "$ref": "#/components/schemas/BlocklistUpdatedEvent" }, { "$ref": "#/components/schemas/LabelUpdatedEvent" }, { "$ref": "#/components/schemas/CallEvent" }, { "$ref": "#/components/schemas/ChannelMessageEvent" }, { "$ref": "#/components/schemas/ChannelUpdatedEvent" }, { "$ref": "#/components/schemas/HistorySyncedEvent" }, { "$ref": "#/components/schemas/ProjectEvent" }, { "$ref": "#/components/schemas/InvitationStatusChangedEvent" }, { "$ref": "#/components/schemas/WebhookTestEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "account.qr_code_issued": "#/components/schemas/AccountEvent", "account.pairing_code_issued": "#/components/schemas/AccountEvent", "account.connected": "#/components/schemas/AccountEvent", "account.disconnected": "#/components/schemas/AccountEvent", "account.failed": "#/components/schemas/AccountEvent", "message.received": "#/components/schemas/MessageEvent", "message.sent": "#/components/schemas/MessageEvent", "message.delivered": "#/components/schemas/MessageEvent", "message.read": "#/components/schemas/MessageEvent", "message.failed": "#/components/schemas/MessageEvent", "message.deleted": "#/components/schemas/MessageEvent", "message.edited": "#/components/schemas/MessageEditedEvent", "poll.voted": "#/components/schemas/PollVotedEvent", "group.joined": "#/components/schemas/GroupJoinedEvent", "group.updated": "#/components/schemas/GroupUpdatedEvent", "group.join_requested": "#/components/schemas/GroupJoinRequestEvent", "group.join_request_revoked": "#/components/schemas/GroupJoinRequestEvent", "chat.updated": "#/components/schemas/ChatUpdatedEvent", "chat.presence_updated": "#/components/schemas/ChatPresenceUpdatedEvent", "contact.presence_updated": "#/components/schemas/ContactPresenceUpdatedEvent", "contact.picture_updated": "#/components/schemas/ContactPictureUpdatedEvent", "contact.updated": "#/components/schemas/ContactUpdatedEvent", "blocklist.updated": "#/components/schemas/BlocklistUpdatedEvent", "label.updated": "#/components/schemas/LabelUpdatedEvent", "call.received": "#/components/schemas/CallEvent", "call.ended": "#/components/schemas/CallEvent", "channel.message_received": "#/components/schemas/ChannelMessageEvent", "channel.message_updated": "#/components/schemas/ChannelMessageEvent", "channel.updated": "#/components/schemas/ChannelUpdatedEvent", "history.synced": "#/components/schemas/HistorySyncedEvent", "project.created": "#/components/schemas/ProjectEvent", "project.updated": "#/components/schemas/ProjectEvent", "project.deleted": "#/components/schemas/ProjectEvent", "invitation.status_changed": "#/components/schemas/InvitationStatusChangedEvent", "webhook.test": "#/components/schemas/WebhookTestEvent" } }, "examples": [ { "id": "evt_5f2b0c9e1a7d3b6c4e8f0a12", "object": "event", "type": "message.received", "createdAt": "2026-09-24T08:15:40.000Z", "organizationId": "w82t6y1u5i9o3p7a2s6d0f4g8h2j6k1l", "projectId": null, "data": { "object": { "object": "message", "id": "m17d0a9w2sqc7k3v8x1n5ybr6t4hjp2e", "projectId": null, "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr", "chatId": "+584241112233", "chatType": "direct", "direction": "inbound", "source": "contact", "from": "+584241112233", "to": "+584121234567", "profileName": "Maria", "username": null, "type": "text", "text": "Is my order ready?", "media": null, "location": null, "contact": null, "contacts": null, "poll": null, "calendarEvent": null, "mentions": [], "forwarded": false, "viewOnce": false, "starred": false, "replyToMessageId": null, "status": "received", "error": null, "metadata": {}, "sentAt": "2026-09-24T08:15:40.000Z", "editedAt": null, "deletedAt": null, "createdAt": "2026-09-24T08:15:40.000Z", "updatedAt": "2026-09-24T08:15:40.000Z" } } } ] } } } }