{ "openapi": "3.1.0", "info": { "title": "NSMOM Communications API", "version": "1.1.0", "description": "Single-company employee workspace and OpenWA gateway with optional Hostinger incoming email metadata. Personal sessions use roles and CSRF; service API keys retain broad backend access. Owner/admin required for pairing QR, sync, automation changes, knowledge approval/rejection and catalogue publication. Other writes require operator or above; viewers may read. Default account971526584959. Live pairing is required. v5 catalogue publication and voice calling are unavailable." }, "servers": [ { "url": "/", "description": "The host running this gateway" } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] }, { "sessionCookie": [] }, { "localSessionCookie": [] } ], "paths": { "/health": { "get": { "operationId": "get__health", "summary": "Check gateway process health", "description": "No WhatsApp data or QR. A healthy process does not establish a connected phone.", "tags": [ "Connection" ], "security": [], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/auth/status": { "get": { "operationId": "get__auth_status", "summary": "Read owner-setup and personal-session state", "description": "Returns authenticated, needsSetup and, for an active session, user and csrfToken. Does not disclose credentials.", "tags": [ "Access" ], "security": [], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/auth/setup": { "post": { "operationId": "post__auth_setup", "summary": "Redeem the one-time owner setup token", "description": "Exact PUBLIC_URL Origin required. Creates the sole initial owner, consumes the bootstrap token and sets a personal session cookie.", "tags": [ "Access" ], "security": [], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string", "maxLength": 128 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "name": { "type": "string", "maxLength": 120 }, "password": { "type": "string", "minLength": 12, "maxLength": 256, "writeOnly": true } }, "required": [ "token", "email", "name", "password" ] } } } }, "responses": { "201": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/auth/login": { "post": { "operationId": "post__auth_login", "summary": "Sign in with a personal employee account", "description": "Exact PUBLIC_URL Origin required. Returns user and csrfToken; sets an HttpOnly session cookie. Rate limited.", "tags": [ "Access" ], "security": [], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "password": { "type": "string", "minLength": 12, "maxLength": 256, "writeOnly": true } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/auth/accept-invite": { "post": { "operationId": "post__auth_accept_invite", "summary": "Redeem a single-use employee invitation", "description": "Exact PUBLIC_URL Origin required. Email and role come from the invitation, not the redemption request.", "tags": [ "Access" ], "security": [], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "maxLength": 120 }, "password": { "type": "string", "minLength": 12, "maxLength": 256, "writeOnly": true } }, "required": [ "token", "name", "password" ] } } } }, "responses": { "201": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/auth/logout": { "post": { "operationId": "post__auth_logout", "summary": "Revoke the current personal session", "description": "Revoke the current personal session", "tags": [ "Access" ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "security": [ { "sessionCookie": [] }, { "localSessionCookie": [] } ] } }, "/auth/users": { "get": { "operationId": "get__auth_users", "summary": "List employee accounts", "description": "Owner or administrator personal session required. Service API keys do not grant employee administration.", "tags": [ "Access" ], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "security": [ { "sessionCookie": [] }, { "localSessionCookie": [] } ] } }, "/auth/invites": { "post": { "operationId": "post__auth_invites", "summary": "Create a single-use employee invitation link", "description": "Owner or administrator only. Returns a private link once. Does not send an email. Expires in48hours.", "tags": [ "Access" ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "role": { "type": "string", "enum": [ "admin", "operator", "viewer" ] } }, "required": [ "email", "role" ] } } } }, "responses": { "201": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "security": [ { "sessionCookie": [] }, { "localSessionCookie": [] } ] } }, "/auth/users/{id}": { "patch": { "operationId": "patch__auth_users_id_", "summary": "Change an employee role or access state", "description": "Owner or administrator only. The owner cannot be disabled or demoted. Revokes target sessions and pending invitations they issued.", "tags": [ "Access" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "admin", "operator", "viewer" ] }, "disabled": { "type": "boolean" } }, "required": [] } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "security": [ { "sessionCookie": [] }, { "localSessionCookie": [] } ] } }, "/v1/status": { "get": { "operationId": "get__v1_status", "summary": "Read session readiness, counts, sync status and automation mode", "description": "Read session readiness, counts, sync status and automation mode", "tags": [ "Connection" ], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/capabilities": { "get": { "operationId": "get__v1_capabilities", "summary": "Read supported runtime capabilities", "description": "Read supported runtime capabilities", "tags": [ "Connection" ], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/session/qr": { "get": { "operationId": "get__v1_session_qr", "summary": "Read the protected pairing QR", "description": "Read the protected pairing QR", "tags": [ "Connection" ], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/sync": { "post": { "operationId": "post__v1_sync", "summary": "Start background reconciliation", "description": "Start background reconciliation", "tags": [ "Sync" ], "parameters": [ { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "responses": { "202": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "get": { "operationId": "get__v1_sync", "summary": "Read latest reconciliation result", "description": "Read latest reconciliation result", "tags": [ "Sync" ], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/contacts": { "get": { "operationId": "get__v1_contacts", "summary": "List cached contacts", "description": "List cached contacts", "tags": [ "Data" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/chats": { "get": { "operationId": "get__v1_chats", "summary": "List cached chats", "description": "List cached chats", "tags": [ "Data" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/messages": { "get": { "operationId": "get__v1_messages", "summary": "List cached messages", "description": "List cached messages", "tags": [ "Data" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "chatId", "in": "query", "schema": { "$ref": "#/components/schemas/ChatId" } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/catalog": { "get": { "operationId": "get__v1_catalog", "summary": "List cached catalog", "description": "List cached catalog", "tags": [ "Data" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/profile": { "get": { "operationId": "get__v1_profile", "summary": "Read cached business profile", "description": "Read cached business profile", "tags": [ "Data" ], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/email/messages": { "get": { "operationId": "get__v1_email_messages", "summary": "List captured Hostinger incoming email metadata", "description": "New webhook metadata only for the configured mailbox. Does not fetch full bodies, attachments or historical messages.", "tags": [ "Email" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/integrations/email": { "get": { "operationId": "get__v1_integrations_email", "summary": "Read incoming email integration status", "description": "Reports configuration and accepted deliveries, including possible provider tests. No secrets or outbound mail capability.", "tags": [ "Email" ], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/webhooks/hostinger-mail/{mailboxResourceId}": { "post": { "operationId": "post__webhooks_hostinger_mail_mailboxResourceId_", "summary": "Receive Hostinger message metadata", "description": "Uses its own webhook Bearer secret, never the administrative API key. Bound to the exact mailbox resource in the route. Accepts metadata only; does not fetch bodyUrl or attachments. Maximum256KiB. Provider event ID deduplicates retries.", "tags": [ "Email" ], "parameters": [ { "name": "mailboxResourceId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "timestamp", "data" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "event": { "const": "message.received" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "from": { "type": "string", "maxLength": 2048 }, "subject": { "type": "string", "maxLength": 2048 }, "attachments": { "type": "array", "maxItems": 1000 } } } } } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "security": [ { "hostingerWebhookAuth": [] } ] } }, "/v1/contacts/{chatId}": { "patch": { "operationId": "patch__v1_contacts_chatId_", "summary": "Update local customer notes and consent", "description": "Local CRM metadata. Does not change the phone address book. Opt-in and per-contact automation must be set explicitly before automatic replies.", "tags": [ "Data" ], "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactPatch" } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/messages/send": { "post": { "operationId": "post__v1_messages_send", "summary": "Send one explicit text message", "description": "This action sends to the named chat. Reuse the same Idempotency-Key only for the exact same request. Unknown outcomes are never automatically retried.", "tags": [ "Replies" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "to": { "$ref": "#/components/schemas/ChatId" }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "to", "text" ] } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/drafts": { "get": { "operationId": "get__v1_drafts", "summary": "List reply drafts", "description": "List reply drafts", "tags": [ "Replies" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 500 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "unknown", "rejected" ] } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/drafts/{id}": { "patch": { "operationId": "patch__v1_drafts_id_", "summary": "Edit a pending reply", "description": "Edit a pending reply", "tags": [ "Replies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/drafts/{id}/approve-send": { "post": { "operationId": "post__v1_drafts_id_approve_send", "summary": "Approve and send this exact reply", "description": "Approve and send this exact reply", "tags": [ "Replies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/drafts/{id}/reject": { "post": { "operationId": "post__v1_drafts_id_reject", "summary": "Reject this reply", "description": "Reject this reply", "tags": [ "Replies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/knowledge": { "get": { "operationId": "get__v1_knowledge", "summary": "List business answers", "description": "List business answers", "tags": [ "Learning" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 500 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "proposed", "approved", "rejected" ] } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "post__v1_knowledge", "summary": "Save a proposed answer", "description": "Does not approve or send. Only explicitly approved answers are used for suggestions.", "tags": [ "Learning" ], "parameters": [ { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeInput" } } } }, "responses": { "201": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/knowledge/{id}": { "patch": { "operationId": "patch__v1_knowledge_id_", "summary": "Edit an answer and revoke its approval", "description": "Edit an answer and revoke its approval", "tags": [ "Learning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 2000 }, "answer": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [] } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/knowledge/{id}/approve": { "post": { "operationId": "post__v1_knowledge_id_approve", "summary": "Approve a reviewed business answer", "description": "Approve a reviewed business answer", "tags": [ "Learning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/knowledge/{id}/reject": { "post": { "operationId": "post__v1_knowledge_id_reject", "summary": "Reject or withdraw an answer", "description": "Reject or withdraw an answer", "tags": [ "Learning" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/learning/extract": { "post": { "operationId": "post__v1_learning_extract", "summary": "Extract proposed examples from one direct conversation", "description": "Examples remain proposed. Review customer-specific details before approval. No model is trained and no data is sent to an AI provider.", "tags": [ "Learning" ], "parameters": [ { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "chatId": { "$ref": "#/components/schemas/ChatId" } }, "required": [ "chatId" ] } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/replies/suggest": { "post": { "operationId": "post__v1_replies_suggest", "summary": "Retrieve a matching approved answer without sending", "description": "Retrieve a matching approved answer without sending", "tags": [ "Learning" ], "parameters": [ { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "chatId": { "$ref": "#/components/schemas/ChatId" }, "text": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "chatId", "text" ] } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/automation": { "get": { "operationId": "get__v1_automation", "summary": "Read active automation mode", "description": "Read active automation mode", "tags": [ "Automation" ], "parameters": [], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "put": { "operationId": "put__v1_automation", "summary": "Change automation mode", "description": "approved-replies requires approved knowledge, explicit per-contact opt-in and automation permission. An environment AUTOMATION_MODE=off cannot be overridden by this endpoint.", "tags": [ "Automation" ], "parameters": [ { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "off", "draft", "approved-replies" ] } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/tasks": { "get": { "operationId": "get__v1_tasks", "summary": "List follow-up tasks", "description": "List follow-up tasks", "tags": [ "Automation" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 500 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "done", "snoozed", "cancelled" ] } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/tasks/{id}": { "patch": { "operationId": "patch__v1_tasks_id_", "summary": "Change follow-up task status", "description": "Change follow-up task status", "tags": [ "Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "open", "done", "snoozed", "cancelled" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/catalog/drafts": { "get": { "operationId": "get__v1_catalog_drafts", "summary": "List local catalogue change drafts", "description": "List local catalogue change drafts", "tags": [ "Catalogue" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "post__v1_catalog_drafts", "summary": "Prepare a local catalogue change", "description": "Stores a draft only. Default OpenWA v5 cannot publish these changes.", "tags": [ "Catalogue" ], "parameters": [ { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "create" }, "product": { "$ref": "#/components/schemas/Product" } }, "required": [ "action", "product" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "update" }, "productId": { "$ref": "#/components/schemas/ProductId" }, "product": { "$ref": "#/components/schemas/ProductPatch" } }, "required": [ "action", "productId", "product" ] }, { "type": "object", "additionalProperties": false, "properties": { "action": { "const": "delete" }, "productId": { "$ref": "#/components/schemas/ProductId" } }, "required": [ "action", "productId" ] } ] } } } }, "responses": { "201": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/catalog/drafts/{id}/publish": { "post": { "operationId": "post__v1_catalog_drafts_id_publish", "summary": "Publish a prepared catalogue change if supported", "description": "Explicit remote mutation. v5 returns501 and retains the draft. Optional legacy create/edit require the appropriate OpenWA licence and compatible Business account. Unknown results must be checked on WhatsApp before repeating.", "tags": [ "Catalogue" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Exact PUBLIC_URL origin required for personal-session requests." }, { "name": "X-CSRF-Token", "in": "header", "schema": { "type": "string" }, "description": "Required for authenticated personal-session writes; obtain from /auth/status. Not required for backend service keys or initial login/setup/invite redemption." } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/events": { "get": { "operationId": "get__v1_events", "summary": "Read durable events after a numeric cursor", "description": "Read durable events after a numeric cursor", "tags": [ "Events" ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Operation result. Data reads use cached snapshots unless specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/v1/events/stream": { "get": { "operationId": "get__v1_events_stream", "summary": "Subscribe to gateway events with cursor replay", "description": "Authenticated text/event-stream. Gateway stored events can replay; upstream OpenWA events cannot. Resume with Last-Event-ID or after.", "tags": [ "Events" ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Last-Event-ID", "in": "header", "schema": { "type": "string", "pattern": "^[0-9]+$" } } ], "responses": { "200": { "description": "Server-sent event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request, including repeated or trailing slash paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Sign-in or backend authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Role, CSRF, origin or mailbox authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Account, approval, idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Request or send limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "501": { "description": "Unsupported runtime capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "502": { "description": "Upstream result unconfirmed; do not repeat mutations blindly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "WhatsApp runtime not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-nsmom_session", "description": "Secure HttpOnly personal session. Role and CSRF restrictions apply." }, "localSessionCookie": { "type": "apiKey", "in": "cookie", "name": "nsmom_session", "description": "Localhost HTTP development cookie only. HTTPS uses __Host-nsmom_session." }, "hostingerWebhookAuth": { "type": "http", "scheme": "bearer", "description": "Separate one-time secret for the configured Hostinger mailbox webhook. Does not grant desk API access." } }, "schemas": { "Response": { "type": "object", "properties": { "data": {}, "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } }, "ChatId": { "type": "string", "pattern": "^[a-zA-Z0-9:_-]+@(c\\.us|s\\.whatsapp\\.net|g\\.us|lid)$", "description": "Use exact IDs returned by WhatsApp. Preserve opaque@lid IDs." }, "ProductId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "ContactPatch": { "type": "object", "additionalProperties": false, "properties": { "notes": { "type": "string", "maxLength": 10000 }, "tags": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 80 } }, "optedIn": { "type": "boolean" }, "automationEnabled": { "type": "boolean" }, "blocked": { "type": "boolean" } }, "required": [] }, "KnowledgeInput": { "type": "object", "additionalProperties": false, "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 2000 }, "answer": { "type": "string", "minLength": 1, "maxLength": 10000 }, "sourceMessageIds": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 512 } } }, "required": [ "question", "answer" ] }, "Product": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "price": { "type": "number", "minimum": 0, "maximum": 100000000, "multipleOf": 0.01, "description": "Normal currency units. Example:3500 AED, not3500000." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "AED" }, "images": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "maxLength": 3145728, "pattern": "^data:image/(png|jpeg|webp);base64,[A-Za-z0-9+/]+=*$" }, "description": "Total JSON body must remain under12MiB." }, "description": { "type": "string", "maxLength": 5000 }, "url": { "type": "string", "maxLength": 2000, "description": "HTTPS product link, or empty string." }, "internalId": { "type": "string", "maxLength": 200 }, "isHidden": { "type": "boolean" } }, "required": [ "name", "price", "currency", "images", "description" ] }, "ProductPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "price": { "type": "number", "minimum": 0, "maximum": 100000000, "multipleOf": 0.01, "description": "Normal currency units. Example:3500 AED, not3500000." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "AED" }, "images": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "maxLength": 3145728, "pattern": "^data:image/(png|jpeg|webp);base64,[A-Za-z0-9+/]+=*$" }, "description": "Total JSON body must remain under12MiB." }, "description": { "type": "string", "maxLength": 5000 }, "url": { "type": "string", "maxLength": 2000, "description": "HTTPS product link, or empty string." }, "internalId": { "type": "string", "maxLength": 200 }, "isHidden": { "type": "boolean" } }, "required": [], "minProperties": 1 } } } }