{ "openapi": "3.1.0", "info": { "title": "Raseel WhatsApp messaging API", "version": "1.0.0", "summary": "One provider-independent HTTP API for sending and receiving WhatsApp messages.", "description": "A unified messaging API. The same request reaches a shared sandbox test\nnumber, a customer's own number linked by QR, or (once available) the\nMeta Cloud API — the provider is a property of the channel, not of the\ncall.\n\nAuthentication is a bearer credential and nothing else: there is no\n`x-api-key` header. See the Authentication page of the documentation.\n\nThis document is hand-authored from the API's controllers and zod\nschemas. It describes what exists; surfaces that are not built yet are\ndeliberately absent.", "contact": { "url": "https://whats.azzamkh.sa/en/docs" } }, "externalDocs": { "description": "Developer documentation", "url": "https://whats.azzamkh.sa/en/docs" }, "servers": [ { "url": "https://whats.azzamkh.sa/api", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Health", "description": "Unauthenticated liveness and readiness probes." }, { "name": "Authentication", "description": "Sessions for a human user." }, { "name": "API keys", "description": "Machine credentials for a workspace." }, { "name": "Messages", "description": "Sending, listing and inspecting messages." }, { "name": "Channels", "description": "The numbers a workspace can send from." }, { "name": "Sandbox", "description": "Shared test numbers and recipient verification." }, { "name": "QR", "description": "Pairing a customer's own number. Session credentials only." }, { "name": "Contacts", "description": "Contacts, groups, tags and bulk import." }, { "name": "Templates", "description": "Reusable, variable-driven message content." }, { "name": "Conversations", "description": "The inbox: threads, replies and notes." }, { "name": "Webhooks", "description": "Event subscriptions, deliveries and replay." }, { "name": "Usage", "description": "Metered totals and plan entitlements." } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "operationId": "getHealth", "summary": "Liveness probe", "description": "Always answers 200 and touches no dependency. Not versioned: it sits directly under the global prefix.", "security": [], "responses": { "200": { "description": "The service is running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Liveness" } } } } } } }, "/ready": { "get": { "tags": [ "Health" ], "operationId": "getReady", "summary": "Readiness probe", "description": "200 when every dependency is reachable, 503 otherwise. Not versioned.", "security": [], "responses": { "200": { "description": "Every dependency is up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } }, "503": { "description": "At least one dependency is down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } } } } }, "/v1/auth/login": { "post": { "tags": [ "Authentication" ], "operationId": "login", "summary": "Start a user session", "description": "Returns an access token plus a refresh token, and sets an httpOnly refresh cookie. Requires a verified email address.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "A new session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "401": { "description": "`INVALID_CREDENTIALS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`EMAIL_NOT_VERIFIED` or `ACCOUNT_SUSPENDED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — 20 attempts per 15 minutes per IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth/me": { "get": { "tags": [ "Authentication" ], "operationId": "getCurrentUser", "summary": "The signed-in user", "description": "Session credentials only; an API key is refused.", "responses": { "200": { "description": "The current user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys": { "get": { "tags": [ "API keys" ], "operationId": "listApiKeys", "summary": "List API keys", "description": "Secrets are never returned here — only `prefix` and `last4`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "A page of API keys.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "API keys" ], "operationId": "createApiKey", "summary": "Create an API key", "description": "Session credentials only: a key cannot mint another key. The `secret` is returned in this response and never again.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "The new key, including its secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`ENTITLEMENT_LIMIT_REACHED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — unknown scope, or an unrecognised field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys/{keyId}": { "delete": { "tags": [ "API keys" ], "operationId": "revokeApiKey", "summary": "Revoke an API key", "description": "Idempotent: revoking an already-revoked key returns its original `revoked_at` rather than an error.", "parameters": [ { "name": "keyId", "in": "path", "required": true, "description": "The key's public id, `key_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The key is revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedApiKey" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`API_KEY_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/messages": { "post": { "tags": [ "Messages" ], "operationId": "sendMessage", "summary": "Send a message", "description": "Accepts the message and returns immediately with `status: \"queued\"`;\ndelivery is asynchronous. Follow it with `GET /v1/messages/{messageId}`\nor subscribe to the `message.*` webhook events.\n\nSend `Idempotency-Key` to make a retry safe: an identical replay returns\nthe original response with `Idempotent-Replay: true`, and the same key\nwith a different body is a 409 `IDEMPOTENCY_CONFLICT`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "201": { "description": "The message was accepted and queued.", "headers": { "Idempotent-Replay": { "description": "`true` when this is the stored response of an earlier identical request.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CHANNEL_NOT_FOUND` or `TEMPLATE_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`CHANNEL_NOT_CONNECTED`, `CHANNEL_CAPABILITY_UNAVAILABLE`, `TEMPLATE_NOT_SENDABLE`, `ENTITLEMENT_LIMIT_REACHED` or `IDEMPOTENCY_CONFLICT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — a non-E.164 recipient, a missing `text.body`/`template.slug`, an unrecognised field, or `TEMPLATE_VARIABLE_MISSING`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — the dispatch queue is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Messages" ], "operationId": "listMessages", "summary": "List messages", "description": "Newest first. An unknown enum value is rejected, not ignored.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" }, { "name": "status", "in": "query", "description": "Filter by message state. `state` is accepted as an alias.", "schema": { "type": "string", "enum": [ "created", "queued", "dispatching", "provider_accepted", "sent", "delivered", "read", "failed_retryable", "failed_permanent", "cancelled", "expired" ] } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "outbound", "inbound" ] } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "authentication", "utility", "marketing" ] } }, { "name": "channel_id", "in": "query", "description": "A channel public id, `ch_…`. Unknown ids are a 404.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of messages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CHANNEL_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — an unknown filter value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/messages/{messageId}": { "get": { "tags": [ "Messages" ], "operationId": "getMessage", "summary": "Retrieve a message with its state timeline", "parameters": [ { "name": "messageId", "in": "path", "required": true, "description": "The message's public id, `msg_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The message and every state transition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageWithEvents" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`NOT_FOUND` with `details.resource = \"message\"`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/channels": { "get": { "tags": [ "Channels" ], "operationId": "listChannels", "summary": "List channels", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "connecting", "awaiting_scan", "connected", "degraded", "disconnected", "suspended", "archived" ] } } ], "responses": { "200": { "description": "A page of channels.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — an unknown status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Channels" ], "operationId": "createChannel", "summary": "Create a channel", "description": "Only `qr` can be created directly today. `sandbox` channels are created\nby allocating a sandbox session, and `meta` has no adapter in this\ndeployment — both are refused with 422 and an explanatory\n`details.issues[0].message`.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannelRequest" } } } }, "responses": { "201": { "description": "The new channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`CONFLICT` — the workspace already has a channel with that name; or `ENTITLEMENT_LIMIT_REACHED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the provider is not creatable here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/channels/{channelId}": { "get": { "tags": [ "Channels" ], "operationId": "getChannel", "summary": "Retrieve a channel", "parameters": [ { "name": "channelId", "in": "path", "required": true, "description": "The channel's public id, `ch_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CHANNEL_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Channels" ], "operationId": "updateChannel", "summary": "Rename a channel or set it as the default", "parameters": [ { "name": "channelId", "in": "path", "required": true, "description": "The channel's public id, `ch_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelRequest" } } } }, "responses": { "200": { "description": "The updated channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CHANNEL_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — at least one field is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Channels" ], "operationId": "archiveChannel", "summary": "Archive a channel", "description": "An archive, not a delete. Repeatable.", "parameters": [ { "name": "channelId", "in": "path", "required": true, "description": "The channel's public id, `ch_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The channel is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchivedChannel" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CHANNEL_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/channels/{channelId}/capabilities": { "get": { "tags": [ "Channels" ], "operationId": "getChannelCapabilities", "summary": "The provider's own capability snapshot", "parameters": [ { "name": "channelId", "in": "path", "required": true, "description": "The channel's public id, `ch_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The capability snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelCapabilities" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CHANNEL_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`CHANNEL_CAPABILITY_UNAVAILABLE` with `details.reason = \"capabilities_not_refreshed\"`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/channels/{channelId}/qr/start": { "post": { "tags": [ "QR" ], "operationId": "startQrPairing", "summary": "Begin or restart QR pairing", "description": "Session credentials only — the QR routes do not accept an API key. The API records intent; a worker produces the codes.", "parameters": [ { "name": "channelId", "in": "path", "required": true, "description": "The channel's public id, `ch_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The pairing status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrStatus" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`CHANNEL_CAPABILITY_UNAVAILABLE` with `details.reason = \"not_a_qr_channel\"`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/channels/{channelId}/qr/status": { "get": { "tags": [ "QR" ], "operationId": "getQrStatus", "summary": "Poll the pairing status", "description": "The QR code itself is never in this response — only `qr_available`. Read the code from the stream.", "parameters": [ { "name": "channelId", "in": "path", "required": true, "description": "The channel's public id, `ch_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The pairing status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrStatus" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`CHANNEL_CAPABILITY_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/channels/{channelId}/qr/stream": { "get": { "tags": [ "QR" ], "operationId": "streamQrEvents", "summary": "Server-sent events for the pairing screen", "description": "`text/event-stream`. The first frame is `snapshot`; then `qr.updated`, `qr.state` and `qr.expired`. The stream is bounded and closes cleanly.", "parameters": [ { "name": "channelId", "in": "path", "required": true, "description": "The channel's public id, `ch_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "An open event stream.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/channels/{channelId}/qr/logout": { "post": { "tags": [ "QR" ], "operationId": "logoutQrChannel", "summary": "Unlink the device", "parameters": [ { "name": "channelId", "in": "path", "required": true, "description": "The channel's public id, `ch_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The pairing status after logout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrStatus" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox/sessions": { "post": { "tags": [ "Sandbox" ], "operationId": "allocateSandboxSession", "summary": "Allocate a shared test number", "description": "Requires a **test-mode** API key. Returns the verification code in plaintext exactly once; only its hash is stored.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxSessionRequest" } } } }, "responses": { "201": { "description": "The allocation, with the verification instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedSandboxSession" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN`, or `SANDBOX_TEST_KEY_REQUIRED` when a live key was presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`ENTITLEMENT_LIMIT_REACHED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`SANDBOX_NO_NUMBER_AVAILABLE` — the pool is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox/sessions/{sessionId}": { "get": { "tags": [ "Sandbox" ], "operationId": "getSandboxSession", "summary": "Retrieve a sandbox session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session's public id, `sbx_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSession" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`SANDBOX_SESSION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Sandbox" ], "operationId": "releaseSandboxSession", "summary": "Release the allocation", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session's public id, `sbx_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The session is released.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasedSandboxSession" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`SANDBOX_SESSION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox/sessions/{sessionId}/verify": { "post": { "tags": [ "Sandbox" ], "operationId": "verifySandboxRecipient", "summary": "Complete recipient verification", "description": "Succeeds only after the code has been sent from the recipient's own handset to the allocated number: possession is proven by the sender address, not by the code alone.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session's public id, `sbx_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifySandboxRequest" } } } }, "responses": { "200": { "description": "The verified session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSession" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`SANDBOX_SESSION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`SANDBOX_VERIFICATION_PENDING` — the code is right but no inbound message has arrived yet; or `SANDBOX_SESSION_EXPIRED` / `SANDBOX_VERIFICATION_EXPIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`SANDBOX_VERIFICATION_INVALID` with `details.attempts_remaining`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts": { "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "summary": "List contacts", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" }, { "name": "q", "in": "query", "description": "Search name, email or phone.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "A tag public id or its slug.", "schema": { "type": "string" } }, { "name": "group_id", "in": "query", "schema": { "type": "string" } }, { "name": "opt_in_status", "in": "query", "schema": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "manual", "import", "api", "inbound", "campaign", "automation", "system" ] } } ], "responses": { "200": { "description": "A page of contacts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — an unknown filter value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Contacts" ], "operationId": "createContact", "summary": "Create a contact", "description": "The phone number is normalised to E.164 and is unique per workspace. A soft-deleted contact with the same number is restored.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" } } } }, "responses": { "201": { "description": "The new contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`CONTACT_ALREADY_EXISTS` with `details.contact_id`, or `ENTITLEMENT_LIMIT_REACHED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — the number could not be normalised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts/{contactId}": { "get": { "tags": [ "Contacts" ], "operationId": "getContact", "summary": "Retrieve a contact", "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "The contact's public id, `cnt_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONTACT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Contacts" ], "operationId": "updateContact", "summary": "Update a contact", "description": "`phone` is immutable. Sending an explicit `null` clears a nullable field; omitting it leaves the value alone.", "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "The contact's public id, `cnt_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } }, "responses": { "200": { "description": "The updated contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONTACT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Contacts" ], "operationId": "deleteContact", "summary": "Delete a contact", "description": "A soft delete: re-creating or re-importing the number restores it.", "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "The contact's public id, `cnt_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The contact is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResource" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONTACT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts/import": { "post": { "tags": [ "Contacts" ], "operationId": "importContacts", "summary": "Import contacts from CSV or XLSX", "description": "The file travels base64-encoded inside JSON; there is no multipart route.\nThe import runs in the background — poll `GET /v1/contacts/imports/{importId}`.\n\nSend `dry_run: true` first: it parses, validates and counts without\nwriting anything, which is the only safe way to see what a file will do.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportContactsRequest" } } } }, "responses": { "202": { "description": "The import was accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactImport" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`ENTITLEMENT_LIMIT_REACHED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`IMPORT_FILE_TOO_LARGE` with `details.size_bytes` and `details.max_bytes`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`IMPORT_FORMAT_UNSUPPORTED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — `content` is not valid base64.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — the import queue is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts/imports": { "get": { "tags": [ "Contacts" ], "operationId": "listContactImports", "summary": "List import runs", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "A page of imports.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactImport" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts/imports/{importId}": { "get": { "tags": [ "Contacts" ], "operationId": "getContactImport", "summary": "Poll one import run", "parameters": [ { "name": "importId", "in": "path", "required": true, "description": "The import's public id, `imp_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The import, with progress and results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactImport" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`IMPORT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contact-groups": { "get": { "tags": [ "Contacts" ], "operationId": "listContactGroups", "summary": "List contact groups", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "A page of groups.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactGroup" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Contacts" ], "operationId": "createContactGroup", "summary": "Create a contact group", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactGroupRequest" } } } }, "responses": { "201": { "description": "The new group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroup" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contact-groups/{groupId}/members": { "get": { "tags": [ "Contacts" ], "operationId": "listContactGroupMembers", "summary": "List the contacts in a group", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The group's public id, `grp_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "A page of contacts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONTACT_GROUP_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Contacts" ], "operationId": "addContactGroupMembers", "summary": "Add contacts to a group", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The group's public id, `grp_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroupMembersRequest" } } } }, "responses": { "201": { "description": "The membership change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroupMembership" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONTACT_GROUP_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Contacts" ], "operationId": "removeContactGroupMembers", "summary": "Remove contacts from a group", "description": "Takes a request body, unusually for a DELETE.", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The group's public id, `grp_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroupMembersRequest" } } } }, "responses": { "200": { "description": "The membership change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroupMembership" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONTACT_GROUP_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tags": { "get": { "tags": [ "Contacts" ], "operationId": "listTags", "summary": "List contact tags", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "A page of tags.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Contacts" ], "operationId": "createTag", "summary": "Create a contact tag", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagRequest" } } } }, "responses": { "201": { "description": "The new tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — `color` must be a hex colour.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/templates": { "get": { "tags": [ "Templates" ], "operationId": "listTemplates", "summary": "List templates", "description": "Unknown `status` or `category` values are ignored rather than rejected.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "authentication", "utility", "marketing" ] } }, { "name": "language", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of templates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Templates" ], "operationId": "createTemplate", "summary": "Create a template", "description": "`variables` is derived from the content and is never sent. Re-creating an archived slug + language pair revives it.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" } } } }, "responses": { "201": { "description": "The new template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`TEMPLATE_ALREADY_EXISTS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — a malformed `{{variable}}`, or content over the configured limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/templates/{templateId}": { "get": { "tags": [ "Templates" ], "operationId": "getTemplate", "summary": "Retrieve a template", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "The template's public id, `tpl_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`TEMPLATE_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Templates" ], "operationId": "updateTemplate", "summary": "Update a template", "description": "`slug` and `language` are immutable. A content change bumps `version`.", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "The template's public id, `tpl_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateRequest" } } } }, "responses": { "200": { "description": "The updated template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`TEMPLATE_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Templates" ], "operationId": "archiveTemplate", "summary": "Archive a template", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "The template's public id, `tpl_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The template is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchivedTemplate" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`TEMPLATE_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/templates/{templateId}/preview": { "post": { "tags": [ "Templates" ], "operationId": "previewTemplate", "summary": "Render a template without sending", "description": "Reports missing and unused variables rather than failing on them.", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "The template's public id, `tpl_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderTemplateRequest" } } } }, "responses": { "200": { "description": "The rendered text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePreview" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`TEMPLATE_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/templates/{templateId}/test-send": { "post": { "tags": [ "Templates" ], "operationId": "testSendTemplate", "summary": "Send a template through the real pipeline", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "The template's public id, `tpl_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSendTemplateRequest" } } } }, "responses": { "201": { "description": "The message was accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`TEMPLATE_NOT_FOUND` or `CHANNEL_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`TEMPLATE_NOT_SENDABLE` or `CHANNEL_NOT_CONNECTED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`TEMPLATE_VARIABLE_MISSING`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/conversations": { "get": { "tags": [ "Conversations" ], "operationId": "listConversations", "summary": "List conversations", "description": "Ordered by conversation id descending — stable for cursor paging, but not \"newest activity first\". Unknown filter values are ignored.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed" ] } }, { "name": "channel_id", "in": "query", "schema": { "type": "string" } }, { "name": "assigned", "in": "query", "description": "`me`, `unassigned`, `none`, `team`, `user:mem_…` or `team:tm_…`.", "schema": { "type": "string" } }, { "name": "unread", "in": "query", "schema": { "type": "string", "enum": [ "true" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of conversations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/conversations/{conversationId}": { "get": { "tags": [ "Conversations" ], "operationId": "getConversation", "summary": "Retrieve a conversation", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "The conversation's public id, `cnv_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN`, or `CONVERSATION_ACCESS_DENIED` when the caller's teams do not reach this channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONVERSATION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/conversations/{conversationId}/messages": { "get": { "tags": [ "Conversations" ], "operationId": "listConversationMessages", "summary": "List the messages in a thread", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "The conversation's public id, `cnv_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "A page of messages, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONVERSATION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Conversations" ], "operationId": "replyToConversation", "summary": "Reply in a thread", "description": "The recipient and the channel come from the conversation. Exactly one of `text` or `template` must be present. The reply is always `category: \"utility\"`.", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "The conversation's public id, `cnv_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationReplyRequest" } } } }, "responses": { "201": { "description": "The message was accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONVERSATION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`CHANNEL_NOT_CONNECTED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`VALIDATION_ERROR` — supply exactly one of `text` or `template`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/conversations/{conversationId}/close": { "post": { "tags": [ "Conversations" ], "operationId": "closeConversation", "summary": "Close a thread", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "The conversation's public id, `cnv_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseConversationRequest" } } } }, "responses": { "200": { "description": "The closed conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONVERSATION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/conversations/{conversationId}/reopen": { "post": { "tags": [ "Conversations" ], "operationId": "reopenConversation", "summary": "Reopen a thread", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "The conversation's public id, `cnv_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The reopened conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CONVERSATION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-event-types": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEventTypes", "summary": "The subscribable event catalogue", "description": "The wildcard `*` first, then every event type. Subscribing to `*` keeps receiving types added later.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The catalogue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string", "enum": [ "*", "message.received", "message.queued", "message.sent", "message.delivered", "message.read", "message.failed", "conversation.created", "conversation.assigned", "conversation.updated", "conversation.closed", "conversation.reopened", "conversation.note_added", "channel.created", "channel.connected", "channel.disconnected", "channel.requires_repair", "channel.archived", "contact.created", "contact.updated", "contact.deleted", "contact.import_completed", "template.created", "template.updated", "template.archived", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.cancelled", "campaign.failed", "automation.failed" ] } } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-endpoints": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "A page of endpoints.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Register a webhook endpoint", "description": "The signing `secret` is returned in this response and never again. Requires the `webhooks.manage` scope, which is NOT in an API key's default scope set.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } } }, "responses": { "201": { "description": "The new endpoint, including its secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`ENTITLEMENT_LIMIT_REACHED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`WEBHOOK_URL_NOT_ALLOWED` with `details.reason`, or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-endpoints/{endpointId}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookEndpoint", "summary": "Retrieve a webhook endpoint", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The endpoint's public id, `wh_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`WEBHOOK_ENDPOINT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Setting `status: \"active\"` also clears the consecutive-failure counter, which is how a disabled endpoint is brought back.", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The endpoint's public id, `wh_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "The updated endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`WEBHOOK_ENDPOINT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`WEBHOOK_URL_NOT_ALLOWED` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The endpoint's public id, `wh_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The endpoint is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResource" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`WEBHOOK_ENDPOINT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-endpoints/{endpointId}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "Rotate the signing secret", "description": "During the overlap window both secrets sign every delivery and `X-Webhook-Signature` carries two `v1=` entries, newest first.", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The endpoint's public id, `wh_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The endpoint with its new secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`WEBHOOK_ENDPOINT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-endpoints/{endpointId}/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhookEndpoint", "summary": "Send a test delivery", "description": "A real delivery through the real pipeline, marked `is_test: true`. No message is sent.", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The endpoint's public id, `wh_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "202": { "description": "The test delivery was queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`WEBHOOK_ENDPOINT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`WEBHOOK_ENDPOINT_DISABLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-endpoints/{endpointId}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listEndpointDeliveries", "summary": "List deliveries for one endpoint", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The endpoint's public id, `wh_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "delivering", "succeeded", "failed", "dead" ] } }, { "name": "event_type", "in": "query", "schema": { "type": "string", "enum": [ "message.received", "message.queued", "message.sent", "message.delivered", "message.read", "message.failed", "conversation.created", "conversation.assigned", "conversation.updated", "conversation.closed", "conversation.reopened", "conversation.note_added", "channel.created", "channel.connected", "channel.disconnected", "channel.requires_repair", "channel.archived", "contact.created", "contact.updated", "contact.deleted", "contact.import_completed", "template.created", "template.updated", "template.archived", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.cancelled", "campaign.failed", "automation.failed" ] } } ], "responses": { "200": { "description": "A page of deliveries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`WEBHOOK_ENDPOINT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "List deliveries across every endpoint", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/WorkspaceId" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "delivering", "succeeded", "failed", "dead" ] } }, { "name": "event_type", "in": "query", "schema": { "type": "string", "enum": [ "message.received", "message.queued", "message.sent", "message.delivered", "message.read", "message.failed", "conversation.created", "conversation.assigned", "conversation.updated", "conversation.closed", "conversation.reopened", "conversation.note_added", "channel.created", "channel.connected", "channel.disconnected", "channel.requires_repair", "channel.archived", "contact.created", "contact.updated", "contact.deleted", "contact.import_completed", "template.created", "template.updated", "template.archived", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.cancelled", "campaign.failed", "automation.failed" ] } } ], "responses": { "200": { "description": "A page of deliveries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-deliveries/{deliveryId}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookDelivery", "summary": "Retrieve one delivery", "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "description": "The delivery's public id, `whd_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`WEBHOOK_DELIVERY_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-deliveries/{deliveryId}/replay": { "post": { "tags": [ "Webhooks" ], "operationId": "replayWebhookDelivery", "summary": "Replay a delivery", "description": "Resends the stored envelope byte for byte and resets the same delivery row. No new event is created.", "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "description": "The delivery's public id, `whd_…`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "202": { "description": "The replay was queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`WEBHOOK_DELIVERY_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`WEBHOOK_ENDPOINT_DISABLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "operationId": "getUsage", "summary": "Metered totals for the current period", "description": "Takes no parameters. The period is always the current UTC calendar month; `messages.*` are period sums and `current.*` are live counts.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The usage summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/plan": { "get": { "tags": [ "Usage" ], "operationId": "getPlan", "summary": "The workspace's plan and entitlements", "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "responses": { "200": { "description": "The plan and its entitlements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "401": { "description": "`UNAUTHORIZED` — missing or invalid bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks the permission or scope, or a workspace/account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`PLAN_NOT_FOUND` — the workspace has no subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`RATE_LIMITED` — see the `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer ` and nothing else — there is no\n`x-api-key` header.\n\nThe credential is either a workspace API key (`wa_test_…` or\n`wa_live_…`) or a user access token from `POST /v1/auth/login`. The\nserver discriminates on the prefix.\n\nA user token additionally needs `X-Workspace-Id`; an API key already\nnames its workspace." } }, "parameters": { "WorkspaceId": { "name": "X-Workspace-Id", "in": "header", "required": false, "description": "The workspace public id, `ws_…`. **Required** with a user access token; optional with an API key, and a 403 `FORBIDDEN` if it disagrees with the key's own workspace.", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A client-chosen key, at most 255 characters, remembered for 24 hours per workspace. An identical replay returns the stored response; a different body under the same key is a 409.", "schema": { "type": "string", "maxLength": 255 } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Page size. Clamped to 1–100 rather than rejected.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "After": { "name": "after", "in": "query", "required": false, "description": "An opaque cursor from the previous page's `page.next_cursor`. Send it back verbatim.", "schema": { "type": "string" } } }, "schemas": { "Error": { "type": "object", "description": "The SPEC §14.3 error envelope. Branch on `code`, never on `message`.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable identifier, e.g. `CHANNEL_NOT_CONNECTED`." }, "message": { "type": "string", "description": "Human-readable English text. Not stable." }, "request_id": { "type": "string", "description": "Also returned as the `X-Request-Id` response header. Quote it in support requests." }, "details": { "type": "object", "additionalProperties": true, "description": "Present only for some codes. `VALIDATION_ERROR` carries `issues: [{ path, message }]`." } } } }, "examples": [ { "error": { "code": "CHANNEL_NOT_CONNECTED", "message": "The selected channel is not connected.", "request_id": "req_01JQ8Z0K5N2Y7M3B" } } ] }, "PageInfo": { "type": "object", "required": [ "next_cursor", "has_more" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `after` to fetch the next page. `null` at the end." }, "has_more": { "type": "boolean" } } }, "DeletedResource": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } }, "Liveness": { "type": "object", "required": [ "status", "service", "environment", "uptime_s" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string" }, "environment": { "type": "string" }, "uptime_s": { "type": "number" } } }, "Readiness": { "type": "object", "required": [ "status", "service", "environment", "uptime_s", "dependencies" ], "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "service": { "type": "string" }, "environment": { "type": "string" }, "uptime_s": { "type": "number" }, "dependencies": { "type": "object", "required": [ "database", "redis" ], "properties": { "database": { "$ref": "#/components/schemas/DependencyHealth" }, "redis": { "$ref": "#/components/schemas/DependencyHealth" } } } } }, "DependencyHealth": { "type": "object", "required": [ "status", "latency_ms" ], "properties": { "status": { "type": "string", "enum": [ "up", "down" ] }, "latency_ms": { "type": "number" }, "reason": { "type": "string" } } }, "LoginRequest": { "type": "object", "required": [ "email", "password" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "password": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "LoginResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "refresh_token", "user" ], "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Seconds until the access token expires." }, "refresh_token": { "type": "string" }, "refresh_expires_at": { "type": "string", "format": "date-time" }, "user": { "$ref": "#/components/schemas/User" } } }, "User": { "type": "object", "required": [ "id", "email", "email_verified", "created_at" ], "properties": { "id": { "type": "string", "description": "`usr_…`" }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" }, "locale": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "platform_role": { "type": "string", "enum": [ "none", "support", "super_admin" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "ApiKey": { "type": "object", "required": [ "id", "name", "mode", "prefix", "last4", "scopes", "created_at" ], "properties": { "id": { "type": "string", "description": "`key_…`" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "prefix": { "type": "string", "description": "The non-secret display prefix, e.g. `wa_test`." }, "last4": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "workspace.read", "channels.read", "channels.manage", "messages.read", "messages.send", "contacts.read", "contacts.manage", "templates.manage", "campaigns.read", "campaigns.manage", "automations.manage", "webhooks.manage" ] } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Written at most once a minute per key." }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "CreatedApiKey": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "The full credential. Returned once, at creation, and never again." } } } ] }, "RevokedApiKey": { "type": "object", "required": [ "id", "revoked_at" ], "properties": { "id": { "type": "string" }, "revoked_at": { "type": "string", "format": "date-time" } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name", "mode" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "workspace.read", "channels.read", "channels.manage", "messages.read", "messages.send", "contacts.read", "contacts.manage", "templates.manage", "campaigns.read", "campaigns.manage", "automations.manage", "webhooks.manage" ] }, "description": "Omit for every scope except `webhooks.manage`. An empty array means the same." }, "expires_at": { "type": "string", "format": "date-time" } } }, "SendMessageRequest": { "type": "object", "required": [ "to" ], "additionalProperties": false, "description": "Strict: an unrecognised property is a 422 rather than being ignored. `text` is required when `type` is `text`; `template.slug` when it is `template`.", "properties": { "to": { "type": "string", "minLength": 4, "maxLength": 20, "description": "Strict E.164, e.g. `+9665XXXXXXXX`." }, "type": { "type": "string", "enum": [ "text", "template" ], "default": "text", "description": "Media types are not accepted by this endpoint yet." }, "channel_id": { "type": "string", "description": "Omit to use the workspace's default channel." }, "category": { "type": "string", "enum": [ "authentication", "utility", "marketing" ], "default": "utility", "description": "Drives queue priority. A template's own category takes precedence over this." }, "text": { "type": "object", "additionalProperties": false, "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4096 } } }, "template": { "type": "object", "additionalProperties": false, "required": [ "slug", "language" ], "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "language": { "type": "string", "minLength": 2, "maxLength": 16 }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "examples": [ { "channel_id": "ch_01JQ8Z0K5N2Y7M3B", "to": "+9665XXXXXXXX", "type": "text", "text": { "body": "Your code is 481902" } } ] }, "SendMessageResponse": { "type": "object", "required": [ "id", "status", "channel_id", "to", "type", "category", "created_at" ], "properties": { "id": { "type": "string", "description": "`msg_…`" }, "status": { "type": "string", "enum": [ "queued" ], "description": "Always `queued` on acceptance. Delivery is asynchronous." }, "channel_id": { "type": "string" }, "to": { "type": "string", "description": "The normalised E.164 recipient." }, "type": { "type": "string", "enum": [ "text", "template" ] }, "category": { "type": "string", "enum": [ "authentication", "utility", "marketing" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Message": { "type": "object", "required": [ "id", "status", "direction", "type", "category", "channel_id", "to", "created_at" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "queued", "dispatching", "provider_accepted", "sent", "delivered", "read", "failed_retryable", "failed_permanent", "cancelled", "expired" ] }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "type": { "type": "string", "enum": [ "text", "template", "image", "document", "audio", "video" ] }, "category": { "type": "string", "enum": [ "authentication", "utility", "marketing" ] }, "source": { "type": "string", "enum": [ "api", "agent", "automation", "campaign", "inbound", "system" ] }, "channel_id": { "type": "string" }, "conversation_id": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "to": { "type": "string" }, "from": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "template": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "language": { "type": "string" }, "variables": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } } } }, "provider_message_id": { "type": [ "string", "null" ] }, "error": { "type": [ "object", "null" ], "description": "The platform's own failure classification. No provider text is ever exposed.", "properties": { "code": { "type": "string" }, "failure_class": { "type": "string" }, "message": { "type": [ "string", "null" ] } } }, "attempts": { "type": "integer" }, "queued_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "read_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "MessageEvent": { "type": "object", "required": [ "id", "status", "source", "attempt", "occurred_at" ], "properties": { "id": { "type": "string", "description": "`mev_…`" }, "from_status": { "type": [ "string", "null" ], "enum": [ "created", "queued", "dispatching", "provider_accepted", "sent", "delivered", "read", "failed_retryable", "failed_permanent", "cancelled", "expired", null ], "description": "`null` for the first event." }, "status": { "type": "string", "enum": [ "created", "queued", "dispatching", "provider_accepted", "sent", "delivered", "read", "failed_retryable", "failed_permanent", "cancelled", "expired" ] }, "source": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "failure_class": { "type": [ "string", "null" ] }, "attempt": { "type": "integer" }, "occurred_at": { "type": "string", "format": "date-time" } } }, "MessageWithEvents": { "allOf": [ { "$ref": "#/components/schemas/Message" }, { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEvent" }, "description": "Oldest first." } } } ] }, "Channel": { "type": "object", "required": [ "id", "name", "provider", "status", "is_default", "created_at" ], "properties": { "id": { "type": "string", "description": "`ch_…`" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "sandbox", "qr", "meta", "mock" ] }, "status": { "type": "string", "enum": [ "pending", "connecting", "awaiting_scan", "connected", "degraded", "disconnected", "suspended", "archived" ] }, "phone_number": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" }, "status_reason": { "type": [ "string", "null" ] }, "capabilities": { "oneOf": [ { "$ref": "#/components/schemas/Capabilities" }, { "type": "null" } ] }, "capabilities_refreshed_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_connected_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Capabilities": { "type": "object", "description": "What the provider says this channel can do. Read it, do not assume it.", "properties": { "send_text": { "type": "boolean" }, "send_media": { "type": "boolean" }, "send_local_template": { "type": "boolean" }, "send_meta_template": { "type": "boolean" }, "campaigns": { "type": "boolean" }, "official_meta": { "type": "boolean" }, "business_initiated_templates": { "type": "boolean" }, "message_status": { "type": "boolean" }, "read_receipts": { "type": "boolean" }, "coexistence": { "type": "boolean" }, "max_throughput_mps": { "type": "number" } } }, "ChannelCapabilities": { "type": "object", "required": [ "channel_id", "provider", "capabilities" ], "properties": { "channel_id": { "type": "string" }, "provider": { "type": "string" }, "capabilities": { "$ref": "#/components/schemas/Capabilities" }, "messaging_limit_tier": { "type": [ "string", "null" ] }, "quality_rating": { "type": [ "string", "null" ] }, "refreshed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ArchivedChannel": { "type": "object", "required": [ "id", "status", "archived_at" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "archived" ] }, "archived_at": { "type": "string", "format": "date-time" } } }, "CreateChannelRequest": { "type": "object", "required": [ "name", "provider" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "provider": { "type": "string", "enum": [ "qr" ], "description": "Only `qr` is creatable. `sandbox` comes from a sandbox session and `meta` has no adapter yet; both are refused with 422." }, "phone_number": { "type": "string" }, "display_name": { "type": "string" }, "is_default": { "type": "boolean" } } }, "UpdateChannelRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "display_name": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" } } }, "QrStatus": { "type": "object", "required": [ "channel_id", "status", "pairing", "qr_available", "safety" ], "properties": { "channel_id": { "type": "string" }, "session_id": { "type": [ "string", "null" ], "description": "`qrs_…`" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "phone_number": { "type": [ "string", "null" ] }, "pairing": { "type": "boolean" }, "qr_available": { "type": "boolean", "description": "The code itself is delivered only over the SSE stream." }, "qr_generated_count": { "type": "integer" }, "pairing_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "paired_at": { "type": [ "string", "null" ], "format": "date-time" }, "connected_since": { "type": [ "string", "null" ], "format": "date-time" }, "last_disconnect_reason": { "type": [ "string", "null" ] }, "health": { "type": "object", "properties": { "score": { "type": [ "number", "null" ] }, "computed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "safety": { "type": "object", "description": "The SPEC §25.3 platform safety policy. Not a WhatsApp guarantee of any kind.", "properties": { "limit": { "type": "integer" }, "window_seconds": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" } } }, "hosted": { "type": "boolean", "description": "Whether a worker currently holds the lease for this session." } } }, "CreateSandboxSessionRequest": { "type": "object", "required": [ "recipient" ], "additionalProperties": false, "properties": { "recipient": { "type": "string", "minLength": 4, "maxLength": 20, "description": "The number you will send test messages to. There is no way to pick the test number." } } }, "VerifySandboxRequest": { "type": "object", "required": [ "code" ], "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 4, "maxLength": 12, "pattern": "^[0-9]+$" } } }, "SandboxSession": { "type": "object", "required": [ "id", "status", "sandbox_number", "channel_id", "recipient", "created_at" ], "properties": { "id": { "type": "string", "description": "`sbx_…`" }, "status": { "type": "string", "enum": [ "allocated", "waiting_for_verification", "verified", "expired", "revoked" ] }, "sandbox_number": { "type": "string" }, "channel_id": { "type": "string" }, "recipient": { "type": [ "string", "null" ] }, "verified_recipient": { "type": [ "string", "null" ] }, "verification_method": { "type": "string", "enum": [ "inbound_code", "outbound_otp" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "CreatedSandboxSession": { "allOf": [ { "$ref": "#/components/schemas/SandboxSession" }, { "type": "object", "required": [ "verification" ], "properties": { "verification": { "type": "object", "required": [ "code", "send_from", "send_to", "attempts_remaining", "expires_at" ], "properties": { "code": { "type": "string", "description": "Plaintext, returned once. Only its hash is stored." }, "send_from": { "type": "string", "description": "The recipient's own number." }, "send_to": { "type": "string", "description": "The allocated shared test number." }, "attempts_remaining": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" } } } } } ] }, "ReleasedSandboxSession": { "type": "object", "required": [ "id", "status", "released_at" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "released_at": { "type": "string", "format": "date-time" } } }, "Contact": { "type": "object", "required": [ "id", "phone", "source", "opt_in_status", "created_at" ], "properties": { "id": { "type": "string", "description": "`cnt_…`" }, "phone": { "type": "string", "description": "Normalised E.164." }, "name": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "opt_in_status": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] }, "opted_in_at": { "type": [ "string", "null" ], "format": "date-time" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] } } } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "last_interaction_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateContactRequest": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "minLength": 4, "maxLength": 40 }, "name": { "type": "string", "maxLength": 200 }, "first_name": { "type": "string", "maxLength": 200 }, "last_name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "locale": { "type": "string" }, "notes": { "type": "string", "maxLength": 10000 }, "opt_in_status": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "Tag NAMES, not ids." }, "group_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "default_calling_code": { "type": "string", "pattern": "^[1-9][0-9]{0,3}$", "description": "Used to normalise a national-format number, e.g. `966`." } } }, "UpdateContactRequest": { "type": "object", "description": "Every field optional. `name`, `first_name`, `last_name`, `email`, `locale` and `notes` accept an explicit `null` to clear them. `phone` cannot be changed.", "properties": { "name": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "opt_in_status": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "group_ids": { "type": "array", "items": { "type": "string" } } } }, "ImportContactsRequest": { "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "format": { "type": "string", "enum": [ "csv", "xlsx" ], "description": "Optional: the format is detected from the file's magic bytes." }, "content": { "type": "string", "description": "The file, base64-encoded. 5 MiB of decoded bytes." }, "mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "phone", "name", "first_name", "last_name", "email", "locale", "notes", "tags", "skip" ] }, "description": "Header → field. Headers are otherwise inferred from English and Arabic aliases; unmapped columns become custom attributes." }, "default_calling_code": { "type": "string", "pattern": "^[1-9][0-9]{0,3}$" }, "group_id": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "dry_run": { "type": "boolean", "default": false, "description": "Parse, validate and count without writing anything." } } }, "ContactImport": { "type": "object", "required": [ "id", "filename", "status", "dry_run", "progress", "result", "created_at" ], "properties": { "id": { "type": "string", "description": "`imp_…`" }, "filename": { "type": "string" }, "format": { "type": "string", "enum": [ "csv", "xlsx" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ] }, "dry_run": { "type": "boolean" }, "progress": { "type": "object", "properties": { "total_rows": { "type": "integer" }, "processed_rows": { "type": "integer" }, "fraction": { "type": "number" } } }, "result": { "type": "object", "description": "`total_rows = created + duplicates + invalid`. `updated` is a SUB-count of `duplicates`, not a fourth partition — do not sum all four.", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "duplicates": { "type": "integer" }, "invalid": { "type": "integer" } } }, "errors": { "type": "array", "description": "A bounded sample, not the full list.", "items": { "type": "object", "properties": { "row": { "type": "integer", "description": "1-based, counting the header row." }, "column": { "type": "string" }, "reason": { "type": "string", "enum": [ "missing_phone", "invalid_phone", "duplicate_in_file", "row_too_wide", "unmapped_header" ] }, "value": { "type": "string" } } } }, "failure_reason": { "type": [ "string", "null" ] }, "group_id": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "ContactGroup": { "type": "object", "required": [ "id", "name", "created_at" ], "properties": { "id": { "type": "string", "description": "`grp_…`" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "member_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateContactGroupRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 1000 } } }, "ContactGroupMembersRequest": { "type": "object", "required": [ "contact_ids" ], "properties": { "contact_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000 } } }, "ContactGroupMembership": { "type": "object", "required": [ "group_id", "member_count" ], "properties": { "group_id": { "type": "string" }, "added": { "type": "integer" }, "removed": { "type": "integer" }, "member_count": { "type": "integer" } } }, "Tag": { "type": "object", "required": [ "id", "name", "slug", "created_at" ], "properties": { "id": { "type": "string", "description": "`tag_…`" }, "name": { "type": "string" }, "slug": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "contact_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateTagRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } } }, "Template": { "type": "object", "required": [ "id", "slug", "language", "category", "status", "body", "version", "created_at" ], "properties": { "id": { "type": "string", "description": "`tpl_…`" }, "slug": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "name": { "type": "string" }, "language": { "type": "string" }, "category": { "type": "string", "enum": [ "authentication", "utility", "marketing" ] }, "status": { "type": "string", "enum": [ "draft", "local_active", "submitted", "pending", "approved", "rejected", "paused", "disabled", "outdated" ] }, "header": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "none", "text", "image", "document", "video" ] }, "text": { "type": [ "string", "null" ] }, "media_ref": { "type": [ "string", "null" ] } } }, "body": { "type": "string" }, "footer": { "type": [ "string", "null" ] }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "quick_reply", "url", "phone_number" ] }, "text": { "type": "string" }, "url": { "type": "string" }, "phone_number": { "type": "string" } } } }, "variables": { "type": "array", "description": "Derived from the content on every write. Never sent by the client.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "example": { "type": [ "string", "null" ] } } } }, "version": { "type": "integer" }, "delivery": { "type": "object", "properties": { "local": { "type": "boolean" }, "meta": { "type": "boolean", "description": "Always false today: Meta template submission is not built." } } }, "bindings": { "type": "array", "description": "Meta template bindings. Always empty in this deployment.", "items": { "type": "object", "additionalProperties": true } }, "use_count": { "type": "integer" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateTemplateRequest": { "type": "object", "required": [ "slug", "language", "body" ], "additionalProperties": false, "properties": { "slug": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 80, "description": "lower_snake_case, e.g. `order_confirmation`. Immutable after creation." }, "language": { "type": "string", "description": "A BCP-47-ish tag, e.g. `ar` or `en-GB`. Immutable." }, "name": { "type": "string", "maxLength": 200 }, "category": { "type": "string", "enum": [ "authentication", "utility", "marketing" ], "default": "utility" }, "header": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "none", "text", "image", "document", "video" ] }, "text": { "type": "string" }, "media_ref": { "type": "string" } } }, "body": { "type": "string", "minLength": 1, "description": "Placeholders are `{{lower_snake_case}}`. Substitution only — no filters, no conditionals." }, "footer": { "type": "string" }, "buttons": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "quick_reply", "url", "phone_number" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 60 }, "url": { "type": "string" }, "phone_number": { "type": "string" } } } }, "examples": { "type": "object", "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "draft", "local_active" ], "default": "draft" } } }, "UpdateTemplateRequest": { "type": "object", "additionalProperties": false, "description": "`slug` and `language` are immutable and are not accepted here.", "properties": { "name": { "type": "string" }, "category": { "type": "string", "enum": [ "authentication", "utility", "marketing" ] }, "header": { "type": "object", "additionalProperties": true }, "body": { "type": "string" }, "footer": { "type": "string" }, "buttons": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "examples": { "type": "object", "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "draft", "local_active", "paused", "disabled" ] } } }, "RenderTemplateRequest": { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } } } }, "TemplatePreview": { "type": "object", "required": [ "id", "slug", "language", "text", "variables", "missing", "unused" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "language": { "type": "string" }, "text": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } }, "unused": { "type": "array", "items": { "type": "string" } } } }, "TestSendTemplateRequest": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string", "minLength": 4, "maxLength": 40 }, "channel_id": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } }, "ArchivedTemplate": { "type": "object", "required": [ "id", "archived" ], "properties": { "id": { "type": "string" }, "archived": { "type": "boolean" } } }, "Conversation": { "type": "object", "required": [ "id", "status", "channel_id", "contact", "unread_count", "created_at" ], "properties": { "id": { "type": "string", "description": "`cnv_…`" }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "channel_id": { "type": "string" }, "contact": { "type": "object", "properties": { "id": { "type": "string" }, "phone": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names." } } }, "assignee": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "enum": [ "user", "team", null ] }, "user_id": { "type": [ "string", "null" ], "description": "A workspace MEMBER id, `mem_…`." }, "team_id": { "type": [ "string", "null" ] }, "assigned_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "unread_count": { "type": "integer" }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_inbound_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_outbound_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ConversationReplyRequest": { "type": "object", "description": "Exactly one of `text` or `template`. There is no `to` and no `channel_id`.", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4096 }, "template": { "type": "object", "required": [ "slug", "language" ], "properties": { "slug": { "type": "string" }, "language": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "CloseConversationRequest": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 200 } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "url", "event_types", "status", "created_at" ], "properties": { "id": { "type": "string", "description": "`wh_…`" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "secret_last4": { "type": [ "string", "null" ] }, "secret_rotated_at": { "type": [ "string", "null" ], "format": "date-time" }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "While set, deliveries are signed with both secrets." }, "consecutive_failures": { "type": "integer" }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_reason": { "type": [ "string", "null" ] }, "last_response_status": { "type": [ "integer", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "disabled_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreatedWebhookEndpoint": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "The HMAC-SHA256 signing secret. Returned once, here and at rotation." } } } ] }, "CreateWebhookEndpointRequest": { "type": "object", "required": [ "url", "event_types" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Absolute, https in production, ports 80 and 443 only, no credentials, no private address." }, "event_types": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "*", "message.received", "message.queued", "message.sent", "message.delivered", "message.read", "message.failed", "conversation.created", "conversation.assigned", "conversation.updated", "conversation.closed", "conversation.reopened", "conversation.note_added", "channel.created", "channel.connected", "channel.disconnected", "channel.requires_repair", "channel.archived", "contact.created", "contact.updated", "contact.deleted", "contact.import_completed", "template.created", "template.updated", "template.archived", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.cancelled", "campaign.failed", "automation.failed" ] }, "description": "`*` subscribes to everything, including types added later." }, "description": { "type": [ "string", "null" ], "maxLength": 500 } }, "examples": [ { "url": "https://example.com/hooks/whatsapp", "event_types": [ "message.received", "message.delivered", "message.failed" ], "description": "Order service" } ] }, "UpdateWebhookEndpointRequest": { "type": "object", "additionalProperties": false, "description": "`disabled` is not accepted: an endpoint is disabled by the platform, and setting `active` is how it comes back.", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "event_types": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "paused" ] } } }, "WebhookDelivery": { "type": "object", "required": [ "id", "endpoint_id", "event_type", "status", "attempt_count", "created_at" ], "properties": { "id": { "type": "string", "description": "`whd_…`" }, "endpoint_id": { "type": "string" }, "event_id": { "type": [ "string", "null" ], "description": "`evt_…`, stable across retries and replays." }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivering", "succeeded", "failed", "dead" ] }, "attempt_count": { "type": "integer" }, "max_attempts": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "response_body": { "type": [ "string", "null" ], "description": "A bounded snippet, and empty in production by configuration." }, "latency_ms": { "type": [ "integer", "null" ] }, "failure_reason": { "type": [ "string", "null" ], "description": "One of `ok`, `server_error`, `rate_limited`, `redirect`, `client_error`, `network_error`, `timeout`, `blocked_target`, `not_deliverable`." }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "replay_count": { "type": "integer" }, "is_test": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookEnvelope": { "type": "object", "description": "The body POSTed to your endpoint. Signed as `HMAC_SHA256(secret, \"{timestamp}.{rawBody}\")` and presented as `X-Webhook-Signature: v1=`; verify against the RAW bytes.", "required": [ "id", "type", "created_at", "workspace_id", "data" ], "properties": { "id": { "type": "string", "description": "The event id, `evt_…`. Use it to deduplicate." }, "type": { "type": "string", "enum": [ "message.received", "message.queued", "message.sent", "message.delivered", "message.read", "message.failed", "conversation.created", "conversation.assigned", "conversation.updated", "conversation.closed", "conversation.reopened", "conversation.note_added", "channel.created", "channel.connected", "channel.disconnected", "channel.requires_repair", "channel.archived", "contact.created", "contact.updated", "contact.deleted", "contact.import_completed", "template.created", "template.updated", "template.archived", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.cancelled", "campaign.failed", "automation.failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "required": [ "object", "object_id" ], "properties": { "object": { "type": "string", "description": "The aggregate type, e.g. `message`." }, "object_id": { "type": "string", "description": "Its public id." } } } }, "examples": [ { "id": "evt_01JQ8Z0K5N2Y7M3B", "type": "message.received", "created_at": "2026-08-13T10:00:00.000Z", "workspace_id": "ws_01JQ8Z0K5N2Y7M3B", "data": { "object": "message", "object_id": "msg_01JQ8Z0K5N2Y7M3B", "message_id": "msg_01JQ8Z0K5N2Y7M3B", "conversation_id": "cnv_01JQ8Z0K5N2Y7M3B", "contact_id": "cnt_01JQ8Z0K5N2Y7M3B", "channel_id": "ch_01JQ8Z0K5N2Y7M3B", "direction": "inbound", "type": "text" } } ] }, "Usage": { "type": "object", "required": [ "period", "plan", "messages", "current", "limits" ], "properties": { "period": { "type": "object", "description": "The current UTC calendar month. `end` is exclusive.", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "label": { "type": "string", "description": "`YYYY-MM`." } } }, "plan": { "$ref": "#/components/schemas/PlanSummary" }, "messages": { "type": "object", "properties": { "outbound": { "$ref": "#/components/schemas/UsageTotals" }, "inbound": { "$ref": "#/components/schemas/UsageTotals" } } }, "current": { "type": "object", "description": "Live counts, not period sums.", "properties": { "contacts": { "type": "integer" }, "channels_connected": { "type": "integer" }, "channels_total": { "type": "integer" }, "webhook_endpoints": { "type": "integer" }, "api_keys": { "type": "integer" }, "team_seats": { "type": "integer" } } }, "limits": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": [ "integer", "null" ] }, "unlimited": { "type": "boolean" }, "current": { "type": "integer" }, "remaining": { "type": [ "integer", "null" ] } } } } } }, "UsageTotals": { "type": "object", "properties": { "total": { "type": "integer" }, "by_category": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_provider": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "PlanSummary": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "version": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" } } }, "Plan": { "type": "object", "required": [ "plan", "entitlements" ], "properties": { "plan": { "$ref": "#/components/schemas/PlanSummary" }, "entitlements": { "type": "array", "items": { "type": "object", "required": [ "key", "type", "unlimited", "source" ], "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "number", "boolean", "string" ] }, "unlimited": { "type": "boolean" }, "value": { "description": "`null` whenever `unlimited` is true.", "type": [ "number", "boolean", "string", "null" ] }, "source": { "type": "string", "enum": [ "plan", "override" ] } } } } } } } } }