{ "openapi": "3.1.0", "info": { "title": "OmniMessage API", "version": "1.0.0", "summary": "One REST API to send WhatsApp Business, SMS, Telegram, Messenger, Instagram and TikTok messages.", "description": "The OmniMessage API is JSON over HTTPS. Requests and responses use UTF-8, snake_case field names and ISO-8601 UTC timestamps. Money is an integer number of micro-USD in fields ending `_micros` (1 USD = 1,000,000), accompanied by `currency: \"USD\"`.\n\nAuthenticate with an API key as a bearer token. Keys prefixed `om_live_` deliver and bill; keys prefixed `om_test_` run against a sandbox where nothing is delivered or billed.", "contact": { "name": "OmniMessage", "url": "https://omnimessage.co/docs" } }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://api.omnimessage.co/v1", "description": "Production (live and test mode, selected by the API key)" } ], "security": [ { "bearerAuth": [] } ], "externalDocs": { "url": "https://omnimessage.co/docs", "description": "Guides" }, "tags": [ { "name": "Messages", "x-slug": "messages", "description": "Send messages on any connected channel, alone or in batches, and read back their status and history." }, { "name": "Channels", "x-slug": "channels", "description": "Connect and manage your own senders: WhatsApp Business numbers, Telegram bots, SMS numbers and more." }, { "name": "Webhook endpoints", "x-slug": "webhook-endpoints", "description": "Register the URLs that receive delivery receipts, inbound messages and account events." }, { "name": "Contacts", "x-slug": "contacts", "description": "Keep the people you message, with their consent, tags and custom attributes, and group them in lists and segments." }, { "name": "Campaigns", "x-slug": "campaigns", "description": "Send one message to many recipients, on a schedule and at a controlled rate, and follow the progress." }, { "name": "Integration sources", "x-slug": "integration-sources", "description": "Register the stores and sites that report events, and let a plugin read which events to send." }, { "name": "Automation events", "x-slug": "automation-events", "description": "Report what happened in a store or site; the account decides in the console what message follows." }, { "name": "Event feed", "x-slug": "event-feed", "description": "Read the events webhooks deliver, for polling and for catching up after an outage." }, { "name": "Billing", "x-slug": "billing", "description": "Read the prepaid balance, the per-message prices and usage." }, { "name": "Account", "x-slug": "account", "description": "Inspect the account and API key behind a request." } ], "paths": { "/messages": { "post": { "operationId": "createMessage", "summary": "Send a message", "description": "Queues one message for delivery on a channel and charges for it.\n\nProvide `type` and the content object under the key named by `type`. The types a channel accepts are listed in its `capabilities`.\n\nBilling happens at acceptance: one package credit if an applicable package has credits (earliest expiry first), otherwise the per-message price of the channel type is debited from the wallet. If neither is possible the request fails with `402 insufficient_balance` and no message is created. A message that later fails is refunded automatically. Test-mode messages are never billed.\n\nThe response is `202 Accepted` with `status: \"queued\"`. Delivery is asynchronous: follow the outcome through webhooks or by retrieving the message.", "tags": [ "Messages" ], "x-scopes": [ "messages:write" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreateParams" }, "examples": { "text": { "summary": "Text", "value": { "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "to": "+971501234567", "type": "text", "text": { "body": "Your code is 482910" }, "reference": "order-1042", "metadata": { "user_id": "u_17" } } }, "template": { "summary": "WhatsApp template", "value": { "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "to": "+971501234567", "type": "template", "template": { "name": "order_shipped", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Layla" }, { "type": "text", "text": "#1042" } ] } ] } } }, "attachment": { "summary": "Attachment", "value": { "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "to": "+971501234567", "type": "attachments", "attachments": [ { "type": "document", "url": "https://example.com/invoices/1042.pdf", "filename": "invoice-1042.pdf", "caption": "Invoice for order #1042" } ] } }, "button": { "summary": "Reply buttons", "value": { "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "to": "+971501234567", "type": "button", "button": { "body": { "text": "Your delivery is scheduled for tomorrow, 10:00-12:00. Does that work?" }, "footer": { "text": "Order #1042" }, "action": { "buttons": [ { "reply": { "id": "confirm", "title": "Confirm" } }, { "reply": { "id": "reschedule", "title": "Reschedule" } } ] } } } }, "list": { "summary": "List", "value": { "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "to": "+971501234567", "type": "list", "list": { "body": { "text": "Pick a delivery window for order #1042." }, "action": { "button": "Choose a slot", "sections": [ { "title": "Tomorrow", "rows": [ { "id": "slot_am", "title": "10:00-12:00", "description": "Morning" }, { "id": "slot_pm", "title": "16:00-18:00", "description": "Afternoon" } ] } ] } } } }, "cta_url": { "summary": "CTA URL", "value": { "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "to": "+971501234567", "type": "cta_url", "cta_url": { "body": { "text": "Your order is on its way." }, "action": { "parameters": { "display_text": "Track order", "url": "https://example.com/track/1042" } } } } }, "location": { "summary": "Location", "value": { "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "to": "+971501234567", "type": "location", "location": { "latitude": 25.197197, "longitude": 55.274376, "name": "Pickup point", "address": "Sheikh Mohammed bin Rashid Blvd, Dubai" } } }, "test": { "summary": "Test mode", "value": { "channel": "ch_test_whatsapp", "to": "+15550100002", "type": "text", "text": { "body": "Hello from test mode" } } } } } } }, "responses": { "202": { "description": "Accepted. The message is queued and has been charged.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "queued", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": null, "delivered_at": null, "read_at": null, "failed_at": null } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `unsupported_message_type`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "unsupported_message_type": { "summary": "unsupported_message_type", "value": { "error": { "type": "invalid_request_error", "code": "unsupported_message_type", "message": "Channel type sms does not support message type button.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#unsupported_message_type" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "No package credits remain and the wallet cannot cover the message price. Nothing was created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_balance": { "summary": "insufficient_balance", "value": { "error": { "type": "billing_error", "code": "insufficient_balance", "message": "No package credits remain and the wallet balance is below the message price.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The channel (or the `reply_to` message) does not exist in this account and mode.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "resource_missing", "value": { "error": { "type": "not_found_error", "code": "resource_missing", "message": "No such message: msg_2b1Xw9aQ3rT8yU0pL4kZ", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#resource_missing" } } } } } } }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "422": { "description": "The channel cannot take the message. The charge was reversed and no message was created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "channel_not_connected": { "summary": "channel_not_connected", "value": { "error": { "type": "channel_error", "code": "channel_not_connected", "message": "Channel ch_7Hq2mN5vB8cX1zL0pK3j is not connected (connection_status: disconnected).", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#channel_not_connected" } } }, "recipient_blocked": { "summary": "recipient_blocked", "value": { "error": { "type": "channel_error", "code": "recipient_blocked", "message": "The recipient cannot be messaged on this channel.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#recipient_blocked" } } }, "policy_violation": { "summary": "policy_violation", "value": { "error": { "type": "channel_error", "code": "policy_violation", "message": "The message violates the channel policy.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#policy_violation" } } }, "upstream_rejected": { "summary": "upstream_rejected", "value": { "error": { "type": "channel_error", "code": "upstream_rejected", "message": "The channel rejected the request.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#upstream_rejected" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "listMessages", "summary": "List messages", "description": "Returns messages of the key mode, newest first. Combine filters to narrow the result; all filters are exact matches.", "tags": [ "Messages" ], "x-scopes": [ "messages:read" ], "parameters": [ { "name": "channel", "in": "query", "description": "Only messages on this channel ID.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Only outbound or only inbound messages.", "schema": { "type": "string", "enum": [ "outbound", "inbound" ] } }, { "name": "status", "in": "query", "description": "Only messages currently in this status.", "schema": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "read", "failed", "received" ] } }, { "name": "to", "in": "query", "description": "Only messages to this recipient identifier.", "schema": { "type": "string" }, "example": "+971501234567" }, { "name": "reference", "in": "query", "description": "Only messages with this `reference`.", "schema": { "type": "string" }, "example": "order-1042" }, { "name": "created_after", "in": "query", "description": "Only messages created after this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-05T00:00:00Z" }, { "name": "created_before", "in": "query", "description": "Only messages created before this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Only messages that changed after this ISO-8601 timestamp (`updated_at`): new messages and status changes alike. The order stays newest created first. For polling.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of messages.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" }, "example": { "object": "list", "data": [ { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "delivered", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": "2026-10-05T09:30:02.871Z", "read_at": null, "failed_at": null } ], "has_more": true, "next_cursor": "msg_2b1Xw9aQ3rT8yU0pL4kZ" } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/messages/batch": { "post": { "operationId": "createMessageBatch", "summary": "Send a batch of messages", "description": "Sends up to 100 messages in one request. Each item has the same shape as the body of `POST /v1/messages`, is validated, billed and accepted independently, and may target a different channel.\n\nThe response is `207 Multi-Status` whenever the batch itself was well-formed, even if every item was rejected. Inspect `data[].status` per item: accepted items carry `message`, rejected items carry `error`. `Idempotency-Key` applies to the batch as a whole.", "tags": [ "Messages" ], "x-scopes": [ "messages:write" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageBatchParams" }, "example": { "messages": [ { "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "to": "+971501234567", "type": "text", "text": { "body": "Your order has shipped." }, "reference": "order-1042" }, { "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "to": "+971509876543", "type": "text", "text": { "body": "Your order has shipped." }, "reference": "order-1043" } ] } } } }, "responses": { "207": { "description": "Per-item results, in request order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageBatch" }, "example": { "object": "batch", "data": [ { "index": 0, "status": 202, "message": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "queued", "error": null, "reference": "order-1042", "metadata": {}, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": null, "delivered_at": null, "read_at": null, "failed_at": null } }, { "index": 1, "status": 402, "error": { "type": "billing_error", "code": "insufficient_balance", "message": "No package credits remain and the wallet balance is below the message price.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance" } } ], "accepted": 1, "rejected": 1 } } } }, "400": { "description": "The batch envelope is malformed: `messages` is missing, empty or longer than 100 items.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/messages/{id}": { "get": { "operationId": "getMessage", "summary": "Retrieve a message", "description": "Returns one message with its current status, billing outcome and timestamps.", "tags": [ "Messages" ], "x-scopes": [ "messages:read" ], "parameters": [ { "$ref": "#/components/parameters/MessageId" } ], "responses": { "200": { "description": "The message.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "delivered", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": "2026-10-05T09:30:02.871Z", "read_at": null, "failed_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/messages/{id}/events": { "get": { "operationId": "listMessageEvents", "summary": "List message status events", "description": "Returns the full status history of a message, oldest first. Useful for debugging delivery timing. The list is not paginated.", "tags": [ "Messages" ], "x-scopes": [ "messages:read" ], "parameters": [ { "$ref": "#/components/parameters/MessageId" } ], "responses": { "200": { "description": "Status history.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageStatusEventList" }, "example": { "object": "list", "data": [ { "status": "queued", "description": "Accepted and charged.", "occurred_at": "2026-10-05T09:30:00.000Z" }, { "status": "sending", "description": "Handed to the channel.", "occurred_at": "2026-10-05T09:30:00.412Z" }, { "status": "sent", "description": "Accepted by the provider.", "occurred_at": "2026-10-05T09:30:01.210Z" }, { "status": "delivered", "description": "Delivered to the recipient device.", "occurred_at": "2026-10-05T09:30:02.871Z" } ], "has_more": false, "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/channels": { "get": { "operationId": "listChannels", "summary": "List channels", "description": "Returns the channels of the key mode. A live key returns the channels you connected, newest first; a test key returns the built-in sandbox channels (`ch_test_`), followed by any simulated channels created for test mode in the console.", "tags": [ "Channels" ], "x-scopes": [ "channels:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of channels.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelList" }, "example": { "object": "list", "data": [ { "id": "ch_7Hq2mN5vB8cX1zL0pK3j", "object": "channel", "mode": "live", "type": "whatsapp", "name": "Support line", "identifier": "+971800123456", "status": "active", "connection_status": "connected", "capabilities": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "flow", "product", "product_list", "catalog", "carousel", "location_request" ], "created_at": "2026-10-01T08:00:00.000Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createChannel", "summary": "Connect a channel", "description": "Connects one of your own senders. The credentials are passed to the delivery layer and are never returned by the API.\n\nThe channel is returned with `connection_status: \"pending\"` and moves to `connected` once the provider confirms the link; subscribe to `channel.connected` to be notified. Requires a live API key: a test key is answered with `403 live_mode_required`, because test mode uses the built-in sandbox channels instead.\n\nFor `telegram` the bot token is verified with Telegram while the request is handled and the bot username becomes the channel `identifier`; a token Telegram does not accept is `422 upstream_rejected`.\n\nMessenger, Instagram and TikTok channels are authorized by signing in with Facebook or TikTok in the console (and WhatsApp can also be connected there with Meta Embedded Signup); creating them with an API key is not available, and other values of `type` fail with `400 parameter_invalid`.", "tags": [ "Channels" ], "x-scopes": [ "channels:write" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelCreateParams" }, "examples": { "whatsapp": { "summary": "WhatsApp", "value": { "type": "whatsapp", "name": "Support line", "identifier": "+971800123456", "credentials": { "wab_account_id": "104857600123456", "phone_number_id": "209715200654321", "access_token": "EAAG..." } } }, "telegram": { "summary": "Telegram", "value": { "type": "telegram", "name": "Order bot", "credentials": { "access_token": "7312045981:AAH..." } } }, "sms": { "summary": "SMS", "value": { "type": "sms", "name": "Transactional SMS", "identifier": "+14155550123", "credentials": { "account_sid": "AC...", "phone_number_sid": "PN...", "auth_token": "..." } } }, "sms_otp": { "summary": "SMS OTP", "value": { "type": "sms_otp", "name": "Login codes", "identifier": "ACME", "credentials": { "api_key": "..." } } } } } } }, "responses": { "201": { "description": "The channel was created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" }, "example": { "id": "ch_7Hq2mN5vB8cX1zL0pK3j", "object": "channel", "mode": "live", "type": "whatsapp", "name": "Support line", "identifier": "+971800123456", "status": "active", "connection_status": "pending", "capabilities": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "flow", "product", "product_list", "catalog", "carousel", "location_request" ], "created_at": "2026-10-01T08:00:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key is not allowed to make this request, or it is a test key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "scope_missing": { "summary": "scope_missing", "value": { "error": { "type": "permission_error", "code": "scope_missing", "message": "This API key does not have the messages:write scope.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#scope_missing" } } }, "ip_not_allowed": { "summary": "ip_not_allowed", "value": { "error": { "type": "permission_error", "code": "ip_not_allowed", "message": "Requests from 203.0.113.7 are not allowed for this API key.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#ip_not_allowed" } } }, "account_suspended": { "summary": "account_suspended", "value": { "error": { "type": "permission_error", "code": "account_suspended", "message": "This account is suspended.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#account_suspended" } } }, "live_mode_required": { "summary": "live_mode_required", "value": { "error": { "type": "permission_error", "code": "live_mode_required", "message": "Channels can only be connected with a live API key.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#live_mode_required" } } } } } } }, "409": { "description": "Conflict. Codes: `channel_identifier_taken`, `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "channel_identifier_taken": { "summary": "channel_identifier_taken", "value": { "error": { "type": "conflict_error", "code": "channel_identifier_taken", "message": "A whatsapp channel with identifier +971800123456 is already connected.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#channel_identifier_taken" } } }, "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "422": { "description": "The provider rejected the credentials or the identifier.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_rejected": { "summary": "upstream_rejected", "value": { "error": { "type": "channel_error", "code": "upstream_rejected", "message": "The channel rejected the request.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#upstream_rejected" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/channels/{id}": { "get": { "operationId": "getChannel", "summary": "Retrieve a channel", "description": "Returns one channel, including its `connection_status` and `capabilities`.", "tags": [ "Channels" ], "x-scopes": [ "channels:read" ], "parameters": [ { "$ref": "#/components/parameters/ChannelId" } ], "responses": { "200": { "description": "The channel.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" }, "example": { "id": "ch_7Hq2mN5vB8cX1zL0pK3j", "object": "channel", "mode": "live", "type": "whatsapp", "name": "Support line", "identifier": "+971800123456", "status": "active", "connection_status": "connected", "capabilities": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "flow", "product", "product_list", "catalog", "carousel", "location_request" ], "created_at": "2026-10-01T08:00:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateChannel", "summary": "Update a channel", "description": "Renames a channel. To change credentials or the identifier, delete the channel and connect it again. Sandbox channels cannot be updated.", "tags": [ "Channels" ], "x-scopes": [ "channels:write" ], "parameters": [ { "$ref": "#/components/parameters/ChannelId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelUpdateParams" }, "example": { "name": "Support line (UAE)" } } } }, "responses": { "200": { "description": "The updated channel.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" }, "example": { "id": "ch_7Hq2mN5vB8cX1zL0pK3j", "object": "channel", "mode": "live", "type": "whatsapp", "name": "Support line (UAE)", "identifier": "+971800123456", "status": "active", "connection_status": "connected", "capabilities": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "flow", "product", "product_list", "catalog", "carousel", "location_request" ], "created_at": "2026-10-01T08:00:00.000Z" } } } }, "400": { "description": "Invalid body, or the channel is a built-in sandbox channel (`parameter_invalid`, `param: \"id\"`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteChannel", "summary": "Delete a channel", "description": "Disconnects and removes a channel. Messages already sent remain retrievable. Messages still queued on the channel may fail. Sandbox channels cannot be deleted.", "tags": [ "Channels" ], "x-scopes": [ "channels:write" ], "parameters": [ { "$ref": "#/components/parameters/ChannelId" } ], "responses": { "200": { "description": "The channel was deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ch_7Hq2mN5vB8cX1zL0pK3j", "object": "channel", "deleted": true } } } }, "400": { "description": "The channel is a built-in sandbox channel (`param: \"id\"`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/channels/{id}/templates": { "get": { "operationId": "listChannelTemplates", "summary": "List WhatsApp templates", "description": "Returns the message templates registered on the WhatsApp Business Account of a channel, as reported by WhatsApp. Only templates with status `APPROVED` can be sent. Available for `whatsapp` channels only.", "tags": [ "Channels" ], "x-scopes": [ "channels:read" ], "parameters": [ { "$ref": "#/components/parameters/ChannelId" } ], "responses": { "200": { "description": "Templates of the channel.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" }, "example": { "object": "list", "data": [ { "id": "1203948571029384", "name": "order_shipped", "language": "en", "category": "UTILITY", "status": "APPROVED", "components": [ { "type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped." }, { "type": "BUTTONS", "buttons": [ { "type": "URL", "text": "Track order", "url": "https://example.com/track/{{1}}" } ] } ], "variables": { "header": [], "body": [ { "key": "1", "example": null }, { "key": "2", "example": null } ], "buttons": [ { "index": 0, "type": "url", "variables": [ { "key": "1", "example": null } ] } ], "count": 3 } } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The channel is not a WhatsApp channel.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Unprocessable. Codes: `channel_not_connected`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "channel_not_connected": { "summary": "channel_not_connected", "value": { "error": { "type": "channel_error", "code": "channel_not_connected", "message": "Channel ch_7Hq2mN5vB8cX1zL0pK3j is not connected (connection_status: disconnected).", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#channel_not_connected" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhook_endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "Returns the webhook endpoints of the key mode, newest first. The signing secret is not included.", "tags": [ "Webhook endpoints" ], "x-scopes": [ "webhooks:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of webhook endpoints.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" }, "example": { "object": "list", "data": [ { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "mode": "live", "url": "https://example.com/hooks/omni", "description": "Production delivery receipts", "events": [ "message.delivered", "message.failed", "message.received" ], "status": "active", "filters": {}, "metadata": {}, "source": null, "created_by": { "type": "api_key", "id": "key_1qW4eR7tY0uI3oP6aS9d" }, "has_verification_token": false, "created_at": "2026-10-02T11:15:00.000Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "Registers a URL to receive events. The endpoint belongs to the mode of the API key: an endpoint created with a test key receives test-mode events only.\n\nThe response contains the signing `secret`. Store it; it is not returned again except when you roll it.\n\nAn account can have up to 500 endpoints per mode, so that every Zap, workflow or scenario can own one. An integration that creates endpoints for its users sets `source` (and may keep its own IDs in `metadata`); such an endpoint is removed automatically after 30 days of uninterrupted failures. `filters` narrows the deliveries on our side. `verification_token` adds a static header for receivers that cannot verify the signature.\n\nThe URL must be public HTTPS: `localhost`, private and link-local addresses are refused with `webhook_url_not_public`.", "tags": [ "Webhook endpoints" ], "x-scopes": [ "webhooks:write" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreateParams" }, "examples": { "selected": { "summary": "Selected events", "value": { "url": "https://example.com/hooks/omni", "events": [ "message.delivered", "message.failed", "message.received" ], "description": "Production delivery receipts" } }, "all": { "summary": "All events", "value": { "url": "https://example.com/hooks/omni", "events": [ "*" ] } }, "integration": { "summary": "Created by an automation tool, filtered", "value": { "url": "https://hooks.example.com/catch/42", "events": [ "message.received" ], "filters": { "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "direction": "inbound" }, "source": "zapier", "metadata": { "zap_id": "184467" }, "verification_token": "vt_4fD8sA1gH6jK9lZ3xC5v" } } } } } }, "responses": { "201": { "description": "The endpoint was created. `secret` is included.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "mode": "live", "url": "https://example.com/hooks/omni", "description": "Production delivery receipts", "events": [ "message.delivered", "message.failed", "message.received" ], "status": "active", "filters": {}, "metadata": {}, "source": null, "created_by": { "type": "api_key", "id": "key_1qW4eR7tY0uI3oP6aS9d" }, "has_verification_token": false, "created_at": "2026-10-02T11:15:00.000Z", "secret": "whsec_Zk8vQ2mX5cB7nL0pR3tY6wA9dF1gH4jK" } } } }, "400": { "description": "Invalid body, an unknown event type, a URL that is not reachable from the internet (`webhook_url_not_public`), or the limit of endpoints per mode is reached (`webhook_endpoint_limit_reached`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } }, "webhook_url_not_public": { "summary": "webhook_url_not_public", "value": { "error": { "type": "invalid_request_error", "code": "webhook_url_not_public", "message": "The URL must be reachable from the internet.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#webhook_url_not_public" } } }, "webhook_endpoint_limit_reached": { "summary": "webhook_endpoint_limit_reached", "value": { "error": { "type": "invalid_request_error", "code": "webhook_endpoint_limit_reached", "message": "At most 500 webhook endpoints are allowed per mode.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#webhook_endpoint_limit_reached" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The channel named in `filters.channel_id` does not exist in this account and mode.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "resource_missing", "value": { "error": { "type": "not_found_error", "code": "resource_missing", "message": "No such message: msg_2b1Xw9aQ3rT8yU0pL4kZ", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#resource_missing" } } } } } } }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhook_endpoints/{id}": { "get": { "operationId": "getWebhookEndpoint", "summary": "Retrieve a webhook endpoint", "description": "Returns one webhook endpoint. The signing secret is not included.", "tags": [ "Webhook endpoints" ], "x-scopes": [ "webhooks:read" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "responses": { "200": { "description": "The endpoint.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "mode": "live", "url": "https://example.com/hooks/omni", "description": "Production delivery receipts", "events": [ "message.delivered", "message.failed", "message.received" ], "status": "active", "filters": {}, "metadata": {}, "source": null, "created_by": { "type": "api_key", "id": "key_1qW4eR7tY0uI3oP6aS9d" }, "has_verification_token": false, "created_at": "2026-10-02T11:15:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Changes the URL, the note, the subscribed events or the status. Only the fields you send are changed. Setting `status` to `active` re-enables an endpoint that was disabled automatically and resets its failure count.", "tags": [ "Webhook endpoints" ], "x-scopes": [ "webhooks:write" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdateParams" }, "examples": { "events": { "summary": "Change events", "value": { "events": [ "message.failed", "channel.disconnected" ] } }, "enable": { "summary": "Re-enable", "value": { "status": "active" } }, "filter": { "summary": "Only inbound messages", "value": { "filters": { "direction": "inbound" }, "metadata": { "workflow": "support-inbox" } } } } } } }, "responses": { "200": { "description": "The updated endpoint.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "mode": "live", "url": "https://example.com/hooks/omni", "description": "Production delivery receipts", "events": [ "message.failed", "channel.disconnected" ], "status": "active", "filters": {}, "metadata": {}, "source": null, "created_by": { "type": "api_key", "id": "key_1qW4eR7tY0uI3oP6aS9d" }, "has_verification_token": false, "created_at": "2026-10-02T11:15:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`, `webhook_url_not_public`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } }, "webhook_url_not_public": { "summary": "webhook_url_not_public", "value": { "error": { "type": "invalid_request_error", "code": "webhook_url_not_public", "message": "The URL must be reachable from the internet.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#webhook_url_not_public" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Removes the endpoint. Pending retries for it are discarded.", "tags": [ "Webhook endpoints" ], "x-scopes": [ "webhooks:write" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "responses": { "200": { "description": "The endpoint was deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhook_endpoints/{id}/roll_secret": { "post": { "operationId": "rollWebhookEndpointSecret", "summary": "Roll the signing secret", "description": "Generates a new signing secret and returns it. The previous secret stops being used immediately, so deploy the new one right away; deliveries your server rejects in between are retried.", "tags": [ "Webhook endpoints" ], "x-scopes": [ "webhooks:write" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The endpoint with its new `secret`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "mode": "live", "url": "https://example.com/hooks/omni", "description": "Production delivery receipts", "events": [ "message.delivered", "message.failed", "message.received" ], "status": "active", "filters": {}, "metadata": {}, "source": null, "created_by": { "type": "api_key", "id": "key_1qW4eR7tY0uI3oP6aS9d" }, "has_verification_token": false, "created_at": "2026-10-02T11:15:00.000Z", "secret": "whsec_N7bT4xK1mQ8wE5rY2uI9oP3aS6dF0gHj" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhook_endpoints/{id}/test": { "post": { "operationId": "testWebhookEndpoint", "summary": "Send a test event", "description": "Queues a `webhook.test` event for the endpoint, signed like any other delivery, whatever its event subscriptions. Returns the event that will be delivered. Use it to check connectivity and your signature verification.", "tags": [ "Webhook endpoints" ], "x-scopes": [ "webhooks:write" ], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The queued test event.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "webhook.test", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "mode": "live", "url": "https://example.com/hooks/omni", "description": "Production delivery receipts", "events": [ "message.delivered", "message.failed", "message.received" ], "status": "active", "filters": {}, "metadata": {}, "source": null, "created_by": { "type": "api_key", "id": "key_1qW4eR7tY0uI3oP6aS9d" }, "has_verification_token": false, "created_at": "2026-10-02T11:15:00.000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts": { "get": { "operationId": "listContacts", "summary": "List contacts", "description": "Returns the contacts of the account, newest first. Filters can be combined. Contacts belong to the account, so live and test keys return the same contacts.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:read" ], "x-account-scoped": true, "parameters": [ { "name": "q", "in": "query", "description": "Search in names and email addresses; a value made of digits searches phone numbers.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "phone", "in": "query", "description": "Only the contact with this phone number.", "schema": { "type": "string" }, "example": "+971501234567" }, { "name": "email", "in": "query", "description": "Only contacts with this email address.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "Only contacts carrying this tag.", "schema": { "type": "string" } }, { "name": "list_id", "in": "query", "description": "Only contacts on this list.", "schema": { "type": "string" } }, { "name": "segment_id", "in": "query", "description": "Only contacts matching this segment.", "schema": { "type": "string" } }, { "name": "consent", "in": "query", "description": "Only contacts with this consent state on a channel type, written `:`.", "schema": { "type": "string" }, "example": "whatsapp:opted_in" }, { "name": "blocked", "in": "query", "description": "Only blocked (`true`) or only unblocked (`false`) contacts.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of contacts.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" }, "example": { "object": "list", "data": [ { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "channel_identifiers": { "telegram": "482910375" }, "locale": "ar", "timezone": "Asia/Dubai", "attributes": { "city": "Dubai", "orders": 12 }, "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": { "state": "opted_in", "source": "api", "updated_at": "2026-10-01T08:00:00.000Z" } }, "blocked": false, "blocked_reason": null, "last_messaged_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-05T09:30:00.000Z" } ], "has_more": true, "next_cursor": "ct_8Jk3mP6qR9sT2vW5xY1z" } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The segment named by `segment_id` does not exist.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "resource_missing", "value": { "error": { "type": "not_found_error", "code": "resource_missing", "message": "No such message: msg_2b1Xw9aQ3rT8yU0pL4kZ", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#resource_missing" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createContact", "summary": "Create a contact", "description": "Creates a contact. At least one of `phone`, `email` or a channel identifier is required. The phone number is validated and stored in E.164; a number without a country prefix is read as a national number of the account country.\n\nA phone number can belong to one contact only: creating a second contact with it fails with `409 contact_exists`. Use the upsert endpoint when you do not know whether the contact exists.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreateParams" }, "example": { "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "locale": "ar", "timezone": "Asia/Dubai", "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": "opted_in" } } } } }, "responses": { "201": { "description": "The contact was created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" }, "example": { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "channel_identifiers": { "telegram": "482910375" }, "locale": "ar", "timezone": "Asia/Dubai", "attributes": { "city": "Dubai", "orders": 12 }, "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": { "state": "opted_in", "source": "api", "updated_at": "2026-10-01T08:00:00.000Z" } }, "blocked": false, "blocked_reason": null, "last_messaged_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-05T09:30:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`, `contact_limit_reached`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } }, "contact_limit_reached": { "summary": "contact_limit_reached", "value": { "error": { "type": "invalid_request_error", "code": "contact_limit_reached", "message": "This account already holds the maximum of 1000000 contacts.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#contact_limit_reached" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict. Codes: `contact_exists`, `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contact_exists": { "summary": "contact_exists", "value": { "error": { "type": "conflict_error", "code": "contact_exists", "message": "A contact with this phone number already exists.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#contact_exists" } } }, "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts/upsert": { "post": { "operationId": "upsertContact", "summary": "Create or update a contact by phone number", "description": "Creates the contact, or updates the one that already has this phone number. On update only the fields you send change and `tags` are added to the existing tags. An existing `opted_out` consent is only changed when you send `consent` for that channel type explicitly.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpsertParams" }, "example": { "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "locale": "ar", "timezone": "Asia/Dubai", "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": "opted_in" } } } } }, "responses": { "200": { "description": "The contact as it is after the request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" }, "example": { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "channel_identifiers": { "telegram": "482910375" }, "locale": "ar", "timezone": "Asia/Dubai", "attributes": { "city": "Dubai", "orders": 12 }, "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": { "state": "opted_in", "source": "api", "updated_at": "2026-10-01T08:00:00.000Z" } }, "blocked": false, "blocked_reason": null, "last_messaged_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-05T09:30:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`, `contact_limit_reached`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } }, "contact_limit_reached": { "summary": "contact_limit_reached", "value": { "error": { "type": "invalid_request_error", "code": "contact_limit_reached", "message": "This account already holds the maximum of 1000000 contacts.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#contact_limit_reached" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts/tags": { "post": { "operationId": "tagContacts", "summary": "Add and remove tags in bulk", "description": "Adds and removes tags on up to 1,000 contacts with one request. A contact that would end up with more than 50 tags is left unchanged.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTagsParams" }, "example": { "contact_ids": [ "ct_8Jk3mP6qR9sT2vW5xY1z" ], "add": [ "october-launch" ], "remove": [ "prospect" ] } } } }, "responses": { "200": { "description": "How many contacts were changed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" }, "example": { "object": "bulk_result", "affected": 2 } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts/{id}": { "get": { "operationId": "getContact", "summary": "Retrieve a contact", "description": "Returns one contact.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:read" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/ContactId" } ], "responses": { "200": { "description": "The contact.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" }, "example": { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "channel_identifiers": { "telegram": "482910375" }, "locale": "ar", "timezone": "Asia/Dubai", "attributes": { "city": "Dubai", "orders": 12 }, "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": { "state": "opted_in", "source": "api", "updated_at": "2026-10-01T08:00:00.000Z" } }, "blocked": false, "blocked_reason": null, "last_messaged_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-05T09:30:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateContact", "summary": "Update a contact", "description": "Changes the fields you send. `tags` replaces the current tags; attributes and channel identifiers are merged key by key, and `null` removes a key. Setting `consent` for a channel type to `opted_out` unsubscribes the contact there.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/ContactId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateParams" }, "example": { "tags": [ "vip" ], "consent": { "whatsapp": "opted_out" } } } } }, "responses": { "200": { "description": "The updated contact.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" }, "example": { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "channel_identifiers": { "telegram": "482910375" }, "locale": "ar", "timezone": "Asia/Dubai", "attributes": { "city": "Dubai", "orders": 12 }, "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": { "state": "opted_in", "source": "api", "updated_at": "2026-10-01T08:00:00.000Z" } }, "blocked": false, "blocked_reason": null, "last_messaged_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-05T09:30:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Another contact already has the new phone number.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contact_exists": { "summary": "contact_exists", "value": { "error": { "type": "conflict_error", "code": "contact_exists", "message": "A contact with this phone number already exists.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#contact_exists" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteContact", "summary": "Delete a contact", "description": "Removes the contact and its list memberships. Messages and campaign results that mention the contact are kept. The phone number becomes free for a new contact.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/ContactId" } ], "responses": { "200": { "description": "The contact was deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contact_tags": { "get": { "operationId": "listContactTags", "summary": "List tags", "description": "Returns every tag in use with the number of contacts carrying it, most used first. The list is not paginated.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:read" ], "x-account-scoped": true, "responses": { "200": { "description": "Tags in use.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactTagList" }, "example": { "object": "list", "data": [ { "object": "contact_tag", "name": "vip", "contact_count": 412 } ], "has_more": false, "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contact_lists": { "get": { "operationId": "listContactLists", "summary": "List contact lists", "description": "Returns the static contact lists of the account, newest first.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:read" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of contact lists.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroupList" }, "example": { "object": "list", "data": [ { "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c", "object": "contact_list", "name": "October launch", "description": "Customers invited to the launch", "contact_count": 1280, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-04T16:20:00.000Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createContactList", "summary": "Create a contact list", "description": "Creates an empty list. Add contacts with the members endpoint.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroupCreateParams" }, "example": { "name": "October launch", "description": "Customers invited to the launch" } } } }, "responses": { "201": { "description": "The list was created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroup" }, "example": { "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c", "object": "contact_list", "name": "October launch", "description": "Customers invited to the launch", "contact_count": 0, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-04T16:20:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contact_lists/{id}": { "get": { "operationId": "getContactList", "summary": "Retrieve a contact list", "description": "Returns one list with its current number of contacts.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:read" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/ContactListId" } ], "responses": { "200": { "description": "The list.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroup" }, "example": { "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c", "object": "contact_list", "name": "October launch", "description": "Customers invited to the launch", "contact_count": 1280, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-04T16:20:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateContactList", "summary": "Update a contact list", "description": "Renames a list or changes its note.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/ContactListId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroupUpdateParams" }, "example": { "name": "October launch (wave 2)" } } } }, "responses": { "200": { "description": "The updated list.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroup" }, "example": { "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c", "object": "contact_list", "name": "October launch (wave 2)", "description": "Customers invited to the launch", "contact_count": 1280, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-04T16:20:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteContactList", "summary": "Delete a contact list", "description": "Removes the list. The contacts on it are kept.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/ContactListId" } ], "responses": { "200": { "description": "The list was deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c", "object": "contact_list", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contact_lists/{id}/members": { "post": { "operationId": "addContactListMembers", "summary": "Add contacts to a list", "description": "Adds up to 1,000 contacts to the list. Contacts that are already on it, and IDs that do not exist, are ignored. Answers with the list and its new count.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/ContactListId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroupMembersParams" }, "example": { "contact_ids": [ "ct_8Jk3mP6qR9sT2vW5xY1z" ] } } } }, "responses": { "200": { "description": "The list after the change.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroup" }, "example": { "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c", "object": "contact_list", "name": "October launch", "description": "Customers invited to the launch", "contact_count": 1280, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-04T16:20:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contact_lists/{id}/members/remove": { "post": { "operationId": "removeContactListMembers", "summary": "Remove contacts from a list", "description": "Takes up to 1,000 contacts off the list. The contacts themselves are kept. Answers with the list and its new count.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:write" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/ContactListId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroupMembersParams" }, "example": { "contact_ids": [ "ct_8Jk3mP6qR9sT2vW5xY1z" ] } } } }, "responses": { "200": { "description": "The list after the change.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGroup" }, "example": { "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c", "object": "contact_list", "name": "October launch", "description": "Customers invited to the launch", "contact_count": 1279, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-04T16:20:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/segments": { "get": { "operationId": "listSegments", "summary": "List segments", "description": "Returns the saved segments of the account, newest first. Segments are created and edited in the console.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:read" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of segments.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentList" }, "example": { "object": "list", "data": [ { "id": "seg_1Ae4gI7kM0oR3tV6xB9d", "object": "segment", "name": "VIP customers not messaged this month", "description": null, "rules": { "op": "and", "rules": [ { "field": "tags", "operator": "has_any", "value": [ "vip" ] }, { "field": "consent.whatsapp", "operator": "is", "value": "opted_in" }, { "field": "last_messaged_at", "operator": "not_in_last_days", "value": 30 } ] }, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-01T08:00:00.000Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/segments/{id}": { "get": { "operationId": "getSegment", "summary": "Retrieve a segment", "description": "Returns one segment with its rules.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:read" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/SegmentId" } ], "responses": { "200": { "description": "The segment.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" }, "example": { "id": "seg_1Ae4gI7kM0oR3tV6xB9d", "object": "segment", "name": "VIP customers not messaged this month", "description": null, "rules": { "op": "and", "rules": [ { "field": "tags", "operator": "has_any", "value": [ "vip" ] }, { "field": "consent.whatsapp", "operator": "is", "value": "opted_in" }, { "field": "last_messaged_at", "operator": "not_in_last_days", "value": 30 } ] }, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-01T08:00:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/segments/{id}/preview": { "get": { "operationId": "previewSegment", "summary": "Count the contacts of a segment", "description": "Evaluates the segment now and returns how many contacts match, with up to five of them as a sample.", "tags": [ "Contacts" ], "x-scopes": [ "contacts:read" ], "x-account-scoped": true, "parameters": [ { "$ref": "#/components/parameters/SegmentId" } ], "responses": { "200": { "description": "Current size of the segment.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentPreview" }, "example": { "object": "segment_preview", "segment_id": "seg_1Ae4gI7kM0oR3tV6xB9d", "count": 412, "sample": [ { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "channel_identifiers": { "telegram": "482910375" }, "locale": "ar", "timezone": "Asia/Dubai", "attributes": { "city": "Dubai", "orders": 12 }, "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": { "state": "opted_in", "source": "api", "updated_at": "2026-10-01T08:00:00.000Z" } }, "blocked": false, "blocked_reason": null, "last_messaged_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-05T09:30:00.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/campaigns": { "post": { "operationId": "createCampaign", "summary": "Create a campaign", "description": "Creates a campaign as a `draft`. Nothing is sent until you launch it, unless the request carries `launch: true`: the campaign is then created and launched in one call, with the checks and errors of `POST /v1/campaigns/{id}/launch`, and nothing is kept when the launch is refused. A template plus the recipients in `audience.recipients` is all an automation needs.\n\nThe message has the same shape as the body of `POST /v1/messages` without `channel` and `to`: `type` plus the content object under the key named by `type`. Strings in it may contain merge tags such as `{{first_name}}`; tags that name no contact field or defined attribute are rejected here, not at send time. `merge_fallbacks` gives the value used when a recipient has none.\n\nA live WhatsApp campaign must use an approved template: the template is looked up on the channel, and a missing or unapproved one fails with `422 template_not_approved`. With a test key the campaign runs against a sandbox channel (`ch_test_`), delivers nothing and is free.", "tags": [ "Campaigns" ], "x-scopes": [ "campaigns:write" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignCreateParams" }, "examples": { "list": { "summary": "A list, with a send window", "value": { "name": "October delivery update", "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20 } }, "segment": { "summary": "A segment", "value": { "name": "Win-back", "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "audience": { "type": "segment", "segment_id": "seg_1Ae4gI7kM0oR3tV6xB9d" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "waiting for you" } ] } ] } }, "merge_fallbacks": { "first_name": "there" } } }, "adhoc": { "summary": "Recipients in the request", "value": { "name": "Pasted recipients", "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "audience": { "type": "adhoc", "recipients": [ { "to": "+971501234567", "first_name": "Layla" }, { "to": "+971502345678", "variables": { "first_name": "Omar" } } ], "save_as_contacts": false }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "ready for pickup" } ] } ] } } } }, "launch": { "summary": "Template and recipients, launched in the same request", "value": { "name": "Back in stock", "channel": "ch_7Hq2mN5vB8cX1zL0pK3j", "audience": { "type": "adhoc", "recipients": [ { "to": "+971503456789", "first_name": "Noor" } ] }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "back in stock" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "consent_declared": true, "launch": true } } } } } }, "responses": { "201": { "description": "The draft campaign, or the launched campaign when `launch` was `true`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" }, "example": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "draft", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 0, "queued": 0, "sent": 0, "delivered": 0, "read": 0, "failed": 0, "skipped": 0, "cancelled": 0, "skip_reasons": {} }, "cost": { "currency": "USD", "estimated_wallet_micros": null, "estimated_credits": null, "wallet_micros": 0, "package_credits": 0 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": null, "started_at": null, "paused_at": null, "completed_at": null, "cancelled_at": null } } } }, "400": { "description": "Invalid body. With `launch`: no consent declaration, no reachable recipient, or a size limit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "unsupported_message_type": { "summary": "unsupported_message_type", "value": { "error": { "type": "invalid_request_error", "code": "unsupported_message_type", "message": "Channel type sms does not support message type button.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#unsupported_message_type" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } }, "consent_required": { "summary": "consent_required", "value": { "error": { "type": "invalid_request_error", "code": "consent_required", "message": "Confirm that the recipients agreed to receive messages from you on this channel (consent_declared).", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#consent_required" } } }, "campaign_limit_exceeded": { "summary": "campaign_limit_exceeded", "value": { "error": { "type": "invalid_request_error", "code": "campaign_limit_exceeded", "message": "A campaign may reach at most 1000000 recipients; this audience has 1204377.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#campaign_limit_exceeded" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "With `launch`: credits and wallet do not cover every recipient and `allow_insufficient_funds` was not set. Nothing was created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_balance": { "summary": "insufficient_balance", "value": { "error": { "type": "billing_error", "code": "insufficient_balance", "message": "No package credits remain and the wallet balance is below the message price.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The channel, segment or list does not exist in this account and mode.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "resource_missing", "value": { "error": { "type": "not_found_error", "code": "resource_missing", "message": "No such message: msg_2b1Xw9aQ3rT8yU0pL4kZ", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#resource_missing" } } } } } } }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "422": { "description": "The WhatsApp template is missing or not approved, or the channel is not connected and its templates cannot be read.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "template_not_approved": { "summary": "template_not_approved", "value": { "error": { "type": "channel_error", "code": "template_not_approved", "message": "Live WhatsApp campaigns must use an approved message template.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#template_not_approved" } } }, "channel_not_connected": { "summary": "channel_not_connected", "value": { "error": { "type": "channel_error", "code": "channel_not_connected", "message": "Channel ch_7Hq2mN5vB8cX1zL0pK3j is not connected (connection_status: disconnected).", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#channel_not_connected" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "listCampaigns", "summary": "List campaigns", "description": "Returns the campaigns of the key mode, newest first.", "tags": [ "Campaigns" ], "x-scopes": [ "campaigns:read" ], "parameters": [ { "name": "status", "in": "query", "description": "Only campaigns in this status.", "schema": { "type": "string", "enum": [ "draft", "scheduled", "queued", "sending", "paused", "completed", "cancelled", "failed" ] }, "example": "draft" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of campaigns.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignList" }, "example": { "object": "list", "data": [ { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "sending", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 1280, "queued": 640, "sent": 598, "delivered": 571, "read": 302, "failed": 9, "skipped": 33, "cancelled": 0, "skip_reasons": { "unsubscribed": 21, "no_identifier": 12 } }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 598 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": "2026-10-05T09:05:02.000Z", "paused_at": null, "completed_at": null, "cancelled_at": null } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/campaigns/{id}": { "get": { "operationId": "getCampaign", "summary": "Retrieve a campaign", "description": "Returns one campaign with its counters and cost. Poll it, or subscribe to the `campaign.*` events, to follow progress.", "tags": [ "Campaigns" ], "x-scopes": [ "campaigns:read" ], "parameters": [ { "$ref": "#/components/parameters/CampaignId" } ], "responses": { "200": { "description": "The campaign.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" }, "example": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "sending", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 1280, "queued": 640, "sent": 598, "delivered": 571, "read": 302, "failed": 9, "skipped": 33, "cancelled": 0, "skip_reasons": { "unsubscribed": 21, "no_identifier": 12 } }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 598 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": "2026-10-05T09:05:02.000Z", "paused_at": null, "completed_at": null, "cancelled_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/campaigns/{id}/recipients": { "get": { "operationId": "listCampaignRecipients", "summary": "List the recipients of a campaign", "description": "Returns the recipients in the order of the audience snapshot, with the outcome of each. The list is empty until the campaign has been launched and its snapshot taken.", "tags": [ "Campaigns" ], "x-scopes": [ "campaigns:read" ], "parameters": [ { "$ref": "#/components/parameters/CampaignId" }, { "name": "status", "in": "query", "description": "Only recipients in this status.", "schema": { "type": "string", "enum": [ "pending", "sent", "delivered", "read", "failed", "skipped", "cancelled" ] }, "example": "failed" }, { "name": "to", "in": "query", "description": "Only the recipient with this identifier.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of recipients.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRecipientList" }, "example": { "object": "list", "data": [ { "id": "184467", "object": "campaign_recipient", "contact_id": "ct_8Jk3mP6qR9sT2vW5xY1z", "to": "+971501234567", "name": "Layla Haddad", "status": "delivered", "skip_reason": null, "message_id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "error": null, "variables": { "first_name": "Layla" }, "sent_at": "2026-10-05T09:05:03.120Z", "delivered_at": "2026-10-05T09:05:04.871Z", "read_at": null, "failed_at": null } ], "has_more": true, "next_cursor": "184467" } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/campaigns/{id}/launch": { "post": { "operationId": "launchCampaign", "summary": "Launch a campaign", "description": "Starts a draft. The campaign becomes `scheduled` when `schedule.send_at` is in the future, otherwise `queued` while the audience snapshot is taken in the background, then `sending`.\n\nBefore anything is sent the request checks the consent declaration (`400 consent_required`), that the channel is connected, the WhatsApp template, the size limits (`400 campaign_limit_exceeded`) and the funds: when credits and wallet do not cover every recipient the request fails with `402 insufficient_balance` unless `allow_insufficient_funds` is `true`, in which case the campaign pauses when the funds run out.\n\nEach message is charged when it is sent, exactly like `POST /v1/messages`. Provider fees, such as Meta conversation fees, are billed by the provider and are separate.", "tags": [ "Campaigns" ], "x-scopes": [ "campaigns:write" ], "parameters": [ { "$ref": "#/components/parameters/CampaignId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLaunchParams" }, "example": { "consent_declared": true } } } }, "responses": { "200": { "description": "The launched campaign.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" }, "example": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "queued", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 0, "queued": 0, "sent": 0, "delivered": 0, "read": 0, "failed": 0, "skipped": 0, "cancelled": 0, "skip_reasons": {} }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 0 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": null, "paused_at": null, "completed_at": null, "cancelled_at": null } } } }, "400": { "description": "Invalid body, no consent declaration, an audience without any reachable recipient (`parameter_invalid`, `param: \"audience\"`), or a size limit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } }, "consent_required": { "summary": "consent_required", "value": { "error": { "type": "invalid_request_error", "code": "consent_required", "message": "Confirm that the recipients agreed to receive messages from you on this channel (consent_declared).", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#consent_required" } } }, "campaign_limit_exceeded": { "summary": "campaign_limit_exceeded", "value": { "error": { "type": "invalid_request_error", "code": "campaign_limit_exceeded", "message": "A campaign may reach at most 1000000 recipients; this audience has 1204377.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#campaign_limit_exceeded" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Credits and wallet do not cover every recipient and `allow_insufficient_funds` was not set.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_balance": { "summary": "insufficient_balance", "value": { "error": { "type": "billing_error", "code": "insufficient_balance", "message": "No package credits remain and the wallet balance is below the message price.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. Codes: `campaign_state_invalid`, `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "campaign_state_invalid": { "summary": "campaign_state_invalid", "value": { "error": { "type": "conflict_error", "code": "campaign_state_invalid", "message": "The campaign is completed and cannot be paused.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#campaign_state_invalid" } } }, "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "422": { "description": "Unprocessable. Codes: `channel_not_connected`, `template_not_approved`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "channel_not_connected": { "summary": "channel_not_connected", "value": { "error": { "type": "channel_error", "code": "channel_not_connected", "message": "Channel ch_7Hq2mN5vB8cX1zL0pK3j is not connected (connection_status: disconnected).", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#channel_not_connected" } } }, "template_not_approved": { "summary": "template_not_approved", "value": { "error": { "type": "channel_error", "code": "template_not_approved", "message": "Live WhatsApp campaigns must use an approved message template.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#template_not_approved" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/campaigns/{id}/pause": { "post": { "operationId": "pauseCampaign", "summary": "Pause a campaign", "description": "Stops a scheduled, queued or sending campaign. Messages already handed to the channel still go out; nothing new is sent, usually within a second or two.", "tags": [ "Campaigns" ], "x-scopes": [ "campaigns:write" ], "parameters": [ { "$ref": "#/components/parameters/CampaignId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The paused campaign.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" }, "example": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "paused", "pause_reason": "user", "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 1280, "queued": 640, "sent": 598, "delivered": 571, "read": 302, "failed": 9, "skipped": 33, "cancelled": 0, "skip_reasons": { "unsubscribed": 21, "no_identifier": 12 } }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 598 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": "2026-10-05T09:05:02.000Z", "paused_at": "2026-10-05T09:12:30.000Z", "completed_at": null, "cancelled_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. Codes: `campaign_state_invalid`, `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "campaign_state_invalid": { "summary": "campaign_state_invalid", "value": { "error": { "type": "conflict_error", "code": "campaign_state_invalid", "message": "The campaign is completed and cannot be paused.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#campaign_state_invalid" } } }, "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/campaigns/{id}/resume": { "post": { "operationId": "resumeCampaign", "summary": "Resume a campaign", "description": "Continues a paused campaign where it stopped. A live campaign needs funds for at least one message, otherwise the request fails with `402 insufficient_balance`.", "tags": [ "Campaigns" ], "x-scopes": [ "campaigns:write" ], "parameters": [ { "$ref": "#/components/parameters/CampaignId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The resumed campaign.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" }, "example": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "sending", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 1280, "queued": 640, "sent": 598, "delivered": 571, "read": 302, "failed": 9, "skipped": 33, "cancelled": 0, "skip_reasons": { "unsubscribed": 21, "no_identifier": 12 } }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 598 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": "2026-10-05T09:05:02.000Z", "paused_at": null, "completed_at": null, "cancelled_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "No package credits remain and the wallet cannot cover one message.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_balance": { "summary": "insufficient_balance", "value": { "error": { "type": "billing_error", "code": "insufficient_balance", "message": "No package credits remain and the wallet balance is below the message price.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. Codes: `campaign_state_invalid`, `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "campaign_state_invalid": { "summary": "campaign_state_invalid", "value": { "error": { "type": "conflict_error", "code": "campaign_state_invalid", "message": "The campaign is completed and cannot be paused.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#campaign_state_invalid" } } }, "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/campaigns/{id}/cancel": { "post": { "operationId": "cancelCampaign", "summary": "Cancel a campaign", "description": "Ends a campaign for good. Recipients that were not sent to yet become `cancelled`; messages already sent are not recalled and stay charged.", "tags": [ "Campaigns" ], "x-scopes": [ "campaigns:write" ], "parameters": [ { "$ref": "#/components/parameters/CampaignId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The cancelled campaign.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" }, "example": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "cancelled", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 0, "queued": 0, "sent": 0, "delivered": 0, "read": 0, "failed": 0, "skipped": 0, "cancelled": 0, "skip_reasons": {} }, "cost": { "currency": "USD", "estimated_wallet_micros": null, "estimated_credits": null, "wallet_micros": 0, "package_credits": 0 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": null, "started_at": null, "paused_at": null, "completed_at": null, "cancelled_at": "2026-10-05T09:12:30.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. Codes: `campaign_state_invalid`, `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "campaign_state_invalid": { "summary": "campaign_state_invalid", "value": { "error": { "type": "conflict_error", "code": "campaign_state_invalid", "message": "The campaign is completed and cannot be paused.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#campaign_state_invalid" } } }, "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/balance": { "get": { "operationId": "getBalance", "summary": "Retrieve the balance", "description": "Returns the wallet balance and the active message packages. The balance belongs to the account, so live and test keys return the same values.", "tags": [ "Billing" ], "x-scopes": [ "billing:read" ], "responses": { "200": { "description": "The balance.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "object": "balance", "currency": "USD", "wallet_micros": 48250000, "packages": [ { "id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "name": "100K messages", "quota": 100000, "remaining": 81234, "channel_types": null, "expires_at": "2027-10-05T00:00:00.000Z" } ], "credits_remaining": 81234 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/pricing": { "get": { "operationId": "getPricing", "summary": "Retrieve pricing", "description": "Returns the effective price of one outbound message per channel type for this account, in micro-USD. This is the amount debited from the wallet when no package credit applies.", "tags": [ "Billing" ], "x-scopes": [ "billing:read" ], "responses": { "200": { "description": "Per-message prices.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pricing" }, "example": { "object": "pricing", "currency": "USD", "data": [ { "channel_type": "whatsapp", "unit_price_micros": 1000 }, { "channel_type": "telegram", "unit_price_micros": 300 }, { "channel_type": "sms", "unit_price_micros": 500 }, { "channel_type": "sms_otp", "unit_price_micros": 500 }, { "channel_type": "messenger", "unit_price_micros": 500 }, { "channel_type": "instagram", "unit_price_micros": 500 }, { "channel_type": "tiktok", "unit_price_micros": 500 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/usage": { "get": { "operationId": "getUsage", "summary": "Retrieve usage", "description": "Returns outbound message counts and spend for a date range, for the key mode. With `group_by=day` there is one row per UTC day and channel type; with `group_by=channel_type` there is one row per channel type for the whole range (`period` is `null`). Days and channel types without usage have no row. `totals` holds the sums over the whole range. The range may span at most 366 days.", "tags": [ "Billing" ], "x-scopes": [ "billing:read" ], "parameters": [ { "name": "from", "in": "query", "description": "First day of the range, `YYYY-MM-DD` (UTC, inclusive). Defaults to 29 days before `to`, so that the default range is the last 30 days.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "description": "Last day of the range, `YYYY-MM-DD` (UTC, inclusive). Defaults to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-05" }, { "name": "group_by", "in": "query", "description": "How rows are grouped.", "schema": { "type": "string", "enum": [ "day", "channel_type" ], "default": "day" }, "example": "day" } ], "responses": { "200": { "description": "Usage for the range.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "example": { "object": "usage", "from": "2026-10-01", "to": "2026-10-05", "group_by": "day", "data": [ { "period": "2026-10-01", "channel_type": "whatsapp", "messages": 1200, "package_credits": 1000, "wallet_micros": 200000, "failed": 12, "refunded_micros": 2000 }, { "period": "2026-10-01", "channel_type": "telegram", "messages": 310, "package_credits": 310, "wallet_micros": 0, "failed": 0, "refunded_micros": 0 }, { "period": "2026-10-02", "channel_type": "whatsapp", "messages": 980, "package_credits": 980, "wallet_micros": 0, "failed": 4, "refunded_micros": 0 } ], "totals": { "messages": 2490, "package_credits": 2290, "wallet_micros": 200000, "failed": 16, "refunded_micros": 2000 } } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/integration_sources": { "post": { "operationId": "createIntegrationSource", "summary": "Register an integration source", "description": "Registers a connected store or site, or refreshes the one that already has this `platform` and `external_id` in the mode of the key (an upsert). A plugin calls it once when the user clicks \"connect\", stores `id` and `source_key`, and uses only the source key from then on. Calling it again is safe and is how a plugin reports a new version or new `emits`.\n\n`201` with `source_key` and `signing_secret` when the source was created; `200` without secrets when it existed. An account can have at most 50 sources per mode.", "tags": [ "Integration sources" ], "x-scopes": [ "integrations:write" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSourceCreateParams" }, "example": { "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ] } } } }, "responses": { "200": { "description": "The source existed and was refreshed. No secrets.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSource" }, "example": { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [ "order.paid", "order.shipped" ], "event_settings": { "cart.abandoned": { "delay_seconds": 3600 } }, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 12, "last_event_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z" } } } }, "201": { "description": "The source was created. `source_key` and `signing_secret` are included, this once.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSource" }, "example": { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [], "event_settings": {}, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 1, "last_event_at": null, "created_at": "2026-10-01T08:00:00.000Z", "source_key": "om_src_Zk8vQ2mX5cB7nL0pR3tY6wA9dF1gH4jK", "signing_secret": "isec_N7bT4xK1mQ8wE5rY2uI9oP3aS6dF0gHjZk8vQ2mX" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`, `integration_source_limit_reached`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } }, "integration_source_limit_reached": { "summary": "integration_source_limit_reached", "value": { "error": { "type": "invalid_request_error", "code": "integration_source_limit_reached", "message": "At most 50 integration sources are allowed per mode.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#integration_source_limit_reached" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "listIntegrationSources", "summary": "List integration sources", "description": "Returns the integration sources of the key mode, newest first. Secrets are not included.", "tags": [ "Integration sources" ], "x-scopes": [ "integrations:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of sources.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSourceList" }, "example": { "object": "list", "data": [ { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [ "order.paid", "order.shipped" ], "event_settings": { "cart.abandoned": { "delay_seconds": 3600 } }, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 12, "last_event_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/integration_sources/current": { "get": { "operationId": "getCurrentIntegrationSource", "summary": "Retrieve the source of a source key", "description": "Returns the source the key belongs to: which events to send (`enabled_events`), how to behave (`event_settings`) and where the editor is (`console_url`, `automation_url_template`). The response carries `ETag: \"\"`; poll at most once per five minutes with `If-None-Match`.\n\nAuthenticate with the **source key** (`Authorization: Bearer om_src_…`) that was returned when the source was created. An API key is answered with `403 scope_missing`.", "tags": [ "Integration sources" ], "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "description": "The `ETag` of the copy you hold. When it is still current the answer is `304` without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The source.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSource" }, "example": { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [ "order.paid", "order.shipped" ], "event_settings": { "cart.abandoned": { "delay_seconds": 3600 } }, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 12, "last_event_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z" } } } }, "304": { "description": "Not modified: the `If-None-Match` value is the current `ETag`. No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Called with an API key instead of a source key, or the source is disabled.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "scope_missing": { "summary": "scope_missing", "value": { "error": { "type": "permission_error", "code": "scope_missing", "message": "This API key does not have the messages:write scope.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#scope_missing" } } }, "ip_not_allowed": { "summary": "ip_not_allowed", "value": { "error": { "type": "permission_error", "code": "ip_not_allowed", "message": "Requests from 203.0.113.7 are not allowed for this API key.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#ip_not_allowed" } } }, "account_suspended": { "summary": "account_suspended", "value": { "error": { "type": "permission_error", "code": "account_suspended", "message": "This account is suspended.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#account_suspended" } } }, "source_disabled": { "summary": "source_disabled", "value": { "error": { "type": "permission_error", "code": "source_disabled", "message": "This integration source is disabled.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#source_disabled" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateCurrentIntegrationSource", "summary": "Describe the source of a source key", "description": "Lets a plugin report its name, address, versions and the events it can send. Only the fields you send are changed. The status and the secrets cannot be changed with a source key.\n\nAuthenticate with the **source key** (`Authorization: Bearer om_src_…`) that was returned when the source was created. An API key is answered with `403 scope_missing`.", "tags": [ "Integration sources" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSourceCurrentUpdateParams" }, "example": { "plugin_version": "0.2.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned", "form.submitted" ] } } } }, "responses": { "200": { "description": "The updated source.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSource" }, "example": { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.2.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [ "order.paid", "order.shipped" ], "event_settings": { "cart.abandoned": { "delay_seconds": 3600 } }, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 12, "last_event_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Called with an API key instead of a source key, or the source is disabled.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "scope_missing": { "summary": "scope_missing", "value": { "error": { "type": "permission_error", "code": "scope_missing", "message": "This API key does not have the messages:write scope.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#scope_missing" } } }, "ip_not_allowed": { "summary": "ip_not_allowed", "value": { "error": { "type": "permission_error", "code": "ip_not_allowed", "message": "Requests from 203.0.113.7 are not allowed for this API key.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#ip_not_allowed" } } }, "account_suspended": { "summary": "account_suspended", "value": { "error": { "type": "permission_error", "code": "account_suspended", "message": "This account is suspended.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#account_suspended" } } }, "source_disabled": { "summary": "source_disabled", "value": { "error": { "type": "permission_error", "code": "source_disabled", "message": "This integration source is disabled.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#source_disabled" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/integration_sources/{id}": { "get": { "operationId": "getIntegrationSource", "summary": "Retrieve an integration source", "description": "Returns one integration source, with the same `ETag` as the source key sees. Secrets are not included.", "tags": [ "Integration sources" ], "x-scopes": [ "integrations:read" ], "parameters": [ { "$ref": "#/components/parameters/IntegrationSourceId" }, { "name": "If-None-Match", "in": "header", "required": false, "description": "The `ETag` of the copy you hold. When it is still current the answer is `304` without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The source.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSource" }, "example": { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [ "order.paid", "order.shipped" ], "event_settings": { "cart.abandoned": { "delay_seconds": 3600 } }, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 12, "last_event_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z" } } } }, "304": { "description": "Not modified: the `If-None-Match` value is the current `ETag`. No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateIntegrationSource", "summary": "Update an integration source", "description": "Changes the description of a source, disables or enables it, replaces the secret native webhooks are verified with, or changes how its events are treated. Only the fields you send are changed.", "tags": [ "Integration sources" ], "x-scopes": [ "integrations:write" ], "parameters": [ { "$ref": "#/components/parameters/IntegrationSourceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSourceUpdateParams" }, "examples": { "rename": { "summary": "Rename", "value": { "name": "Acme Shop (main store)" } }, "settings": { "summary": "Require explicit consent", "value": { "settings": { "consent_mode": "explicit" } } } } } } }, "responses": { "200": { "description": "The updated source.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSource" }, "example": { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop (main store)", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [ "order.paid", "order.shipped" ], "event_settings": { "cart.abandoned": { "delay_seconds": 3600 } }, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 12, "last_event_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteIntegrationSource", "summary": "Delete an integration source", "description": "Deletes the source with its automations and receipts, and cancels its scheduled runs. The source key stops working at once. Messages that were already sent stay.", "tags": [ "Integration sources" ], "x-scopes": [ "integrations:write" ], "parameters": [ { "$ref": "#/components/parameters/IntegrationSourceId" } ], "responses": { "200": { "description": "The source was deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/integration_sources/{id}/roll_key": { "post": { "operationId": "rollIntegrationSourceKey", "summary": "Roll the key of an integration source", "description": "Issues a new `source_key` and `signing_secret`. The old ones stop working at once: update the plugin and the platform webhook right away.", "tags": [ "Integration sources" ], "x-scopes": [ "integrations:write" ], "parameters": [ { "$ref": "#/components/parameters/IntegrationSourceId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The source with its new secrets.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationSource" }, "example": { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [ "order.paid", "order.shipped" ], "event_settings": { "cart.abandoned": { "delay_seconds": 3600 } }, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 12, "last_event_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "source_key": "om_src_N7bT4xK1mQ8wE5rY2uI9oP3aS6dF0gHj", "signing_secret": "isec_Zk8vQ2mX5cB7nL0pR3tY6wA9dF1gH4jKN7bT4xK1" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/automation_events": { "post": { "operationId": "createAutomationEvent", "summary": "Push an event", "description": "Reports that something happened in a store or site. The account decides in the console what follows from it: the enabled automations of the source for this event type are matched, the recipient and consent are checked, and the messages are scheduled (`occurred_at` plus the delay of each automation, outside its quiet hours).\n\nAuthenticate with the source key, or with an API key that has `events:write` and name the source in `source`.\n\nThe event `id` is the idempotency key: a second request with the same `id` for the same source within 30 days returns the first receipt with `status: \"duplicate\"`, HTTP `200` and `Idempotent-Replayed: true`, whatever its body. An `Idempotency-Key` header is accepted and ignored.\n\n`202` does not depend on the balance. Billing happens when a message is sent, as for `POST /v1/messages`; a run that cannot be paid for fails with `insufficient_balance`. Retry only transport errors, `429` and `5xx`.", "tags": [ "Automation events" ], "x-scopes": [ "events:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEventParams" }, "examples": { "order_paid": { "summary": "Order paid", "value": { "id": "woocommerce:order:5012:order.paid:1", "type": "order.paid", "occurred_at": "2026-10-05T09:30:00Z", "site": { "name": "Acme Shop", "url": "https://shop.example.com/" }, "customer": { "id": "17", "name": "Layla Hassan", "first_name": "Layla", "last_name": "Hassan", "phone": "+971501234567", "email": "layla@example.com", "locale": "en", "country": "AE", "consent": { "transactional": true, "marketing": true, "source": "checkout_checkbox", "collected_at": "2026-10-05T09:29:40Z" } }, "order": { "id": "5012", "number": "1042", "status": "processing", "previous_status": "pending", "currency": "AED", "total": { "amount_minor": 12550, "currency": "AED", "formatted": "AED 125.50" }, "subtotal": { "amount_minor": 8000, "currency": "AED", "formatted": "AED 80.00" }, "shipping_total": { "amount_minor": 1500, "currency": "AED", "formatted": "AED 15.00" }, "discount_total": { "amount_minor": 0, "currency": "AED", "formatted": "AED 0.00" }, "items": [ { "id": "11", "name": "Mug", "sku": "MUG-1", "quantity": 2, "unit_price": { "amount_minor": 4000, "currency": "AED", "formatted": "AED 40.00" }, "url": "https://shop.example.com/mug" } ], "items_count": 2, "items_summary": "2 × Mug", "payment_method": "cod", "payment_method_title": "Cash on delivery", "shipping_method": "Flat rate", "tracking": { "number": "", "url": "", "carrier": "" }, "status_url": "https://shop.example.com/my-account/view-order/5012/", "note": "", "created_at": "2026-10-05T09:29:41Z" }, "data": {}, "source": "src_9Kd2mQ5vB8cX1zL0pK3j" } }, "order_shipped": { "summary": "Order shipped, with tracking", "value": { "id": "woocommerce:order:5012:order.shipped:1", "type": "order.shipped", "occurred_at": "2026-10-05T09:30:00Z", "site": { "name": "Acme Shop", "url": "https://shop.example.com/" }, "customer": { "id": "17", "name": "Layla Hassan", "first_name": "Layla", "last_name": "Hassan", "phone": "+971501234567", "email": "layla@example.com", "locale": "en", "country": "AE", "consent": { "transactional": true, "marketing": true, "source": "checkout_checkbox", "collected_at": "2026-10-05T09:29:40Z" } }, "order": { "id": "5012", "number": "1042", "status": "completed", "previous_status": "processing", "currency": "AED", "total": { "amount_minor": 12550, "currency": "AED", "formatted": "AED 125.50" }, "subtotal": { "amount_minor": 8000, "currency": "AED", "formatted": "AED 80.00" }, "shipping_total": { "amount_minor": 1500, "currency": "AED", "formatted": "AED 15.00" }, "discount_total": { "amount_minor": 0, "currency": "AED", "formatted": "AED 0.00" }, "items": [ { "id": "11", "name": "Mug", "sku": "MUG-1", "quantity": 2, "unit_price": { "amount_minor": 4000, "currency": "AED", "formatted": "AED 40.00" }, "url": "https://shop.example.com/mug" } ], "items_count": 2, "items_summary": "2 × Mug", "payment_method": "cod", "payment_method_title": "Cash on delivery", "shipping_method": "Flat rate", "tracking": { "number": "AX204981557", "url": "https://track.example.com/AX204981557", "carrier": "Aramex" }, "status_url": "https://shop.example.com/my-account/view-order/5012/", "note": "", "created_at": "2026-10-05T09:29:41Z" }, "data": {}, "source": "src_9Kd2mQ5vB8cX1zL0pK3j" } }, "cart_abandoned": { "summary": "Abandoned cart", "value": { "id": "woocommerce:cart:cart_88f1:cart.abandoned:1", "type": "cart.abandoned", "occurred_at": "2026-10-05T09:30:00Z", "site": { "name": "Acme Shop", "url": "https://shop.example.com/" }, "customer": { "id": "17", "name": "Layla Hassan", "first_name": "Layla", "last_name": "Hassan", "phone": "+971501234567", "email": "layla@example.com", "locale": "en", "country": "AE", "consent": { "transactional": true, "marketing": true, "source": "checkout_checkbox", "collected_at": "2026-10-05T09:29:40Z" } }, "cart": { "id": "cart_88f1", "currency": "AED", "total": { "amount_minor": 8000, "currency": "AED", "formatted": "AED 80.00" }, "items": [ { "id": "11", "name": "Mug", "sku": "MUG-1", "quantity": 2, "unit_price": { "amount_minor": 4000, "currency": "AED", "formatted": "AED 40.00" }, "url": "https://shop.example.com/mug" } ], "items_count": 2, "items_summary": "2 × Mug", "recovery_url": "https://shop.example.com/cart/?recover=88f1", "updated_at": "2026-10-05T09:30:00Z" }, "data": {}, "source": "src_9Kd2mQ5vB8cX1zL0pK3j" } }, "otp": { "summary": "One-time password", "value": { "id": "app:otp:7f3a91", "type": "otp.requested", "occurred_at": "2026-10-05T09:30:00Z", "site": { "name": "Acme Shop", "url": "https://shop.example.com/" }, "customer": { "id": "17", "name": "Layla Hassan", "first_name": "Layla", "last_name": "Hassan", "phone": "+971501234567", "email": "layla@example.com", "locale": "en", "country": "AE", "consent": { "transactional": true, "marketing": true, "source": "checkout_checkbox", "collected_at": "2026-10-05T09:29:40Z" } }, "otp": { "code": "482910", "expires_in_seconds": 300, "purpose": "login" }, "data": {}, "source": "src_9Kd2mQ5vB8cX1zL0pK3j" } }, "custom": { "summary": "Custom event", "value": { "id": "erp:stock:MUG-1:2026-10-05", "type": "custom.stock_low", "occurred_at": "2026-10-05T09:30:00Z", "source": "src_9Kd2mQ5vB8cX1zL0pK3j", "data": { "sku": "MUG-1", "left": 3, "admin_recipients": [ "+971501112233" ] } } } } } } }, "responses": { "200": { "description": "The `id` was seen before. The first receipt, with `status: \"duplicate\"`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEvent" }, "example": { "id": "aev_3kL9pQ2wE5rT8yU1iO4a", "object": "automation_event", "mode": "live", "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j", "event_id": "woocommerce:order:5012:order.paid:1", "type": "order.paid", "status": "duplicate", "reason": null, "automations_matched": 1, "received_at": "2026-10-05T09:30:00.120Z" } } } }, "202": { "description": "Received. `status` is `accepted` or `ignored`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEvent" }, "example": { "id": "aev_3kL9pQ2wE5rT8yU1iO4a", "object": "automation_event", "mode": "live", "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j", "event_id": "woocommerce:order:5012:order.paid:1", "type": "order.paid", "status": "accepted", "reason": null, "automations_matched": 1, "received_at": "2026-10-05T09:30:00.120Z" } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key may not push events, or the source is disabled.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "scope_missing": { "summary": "scope_missing", "value": { "error": { "type": "permission_error", "code": "scope_missing", "message": "This API key does not have the messages:write scope.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#scope_missing" } } }, "ip_not_allowed": { "summary": "ip_not_allowed", "value": { "error": { "type": "permission_error", "code": "ip_not_allowed", "message": "Requests from 203.0.113.7 are not allowed for this API key.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#ip_not_allowed" } } }, "account_suspended": { "summary": "account_suspended", "value": { "error": { "type": "permission_error", "code": "account_suspended", "message": "This account is suspended.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#account_suspended" } } }, "source_disabled": { "summary": "source_disabled", "value": { "error": { "type": "permission_error", "code": "source_disabled", "message": "This integration source is disabled.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#source_disabled" } } } } } } }, "404": { "description": "The `source` does not exist in this account and mode.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "resource_missing", "value": { "error": { "type": "not_found_error", "code": "resource_missing", "message": "No such message: msg_2b1Xw9aQ3rT8yU0pL4kZ", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#resource_missing" } } } } } } }, "413": { "description": "The body exceeds 256 KB.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#payload_too_large" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "listAutomationEvents", "summary": "List event receipts", "description": "Returns the receipts of the key mode, newest first. For debugging and support; receipts are kept for 30 days.", "tags": [ "Automation events" ], "x-scopes": [ "events:read" ], "parameters": [ { "name": "source", "in": "query", "description": "Only events of this integration source.", "schema": { "type": "string" }, "example": "src_9Kd2mQ5vB8cX1zL0pK3j" }, { "name": "type", "in": "query", "description": "Only events of this type.", "schema": { "type": "string" }, "example": "order.paid" }, { "name": "status", "in": "query", "description": "Only `accepted` or only `ignored` events.", "schema": { "type": "string", "enum": [ "accepted", "ignored" ] } }, { "name": "created_after", "in": "query", "description": "Only events received after this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of receipts.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEventList" }, "example": { "object": "list", "data": [ { "id": "aev_3kL9pQ2wE5rT8yU1iO4a", "object": "automation_event", "mode": "live", "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j", "event_id": "woocommerce:order:5012:order.paid:1", "type": "order.paid", "status": "accepted", "reason": null, "automations_matched": 1, "received_at": "2026-10-05T09:30:00.120Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/automation_events/batch": { "post": { "operationId": "createAutomationEventBatch", "summary": "Push a batch of events", "description": "Pushes up to 100 events in one request, processed in order (a later event may cancel what an earlier one scheduled). Each item is validated and deduplicated on its own.\n\nThe response is `207 Multi-Status` whenever the batch itself was well-formed. A batch counts as one request for rate limiting.", "tags": [ "Automation events" ], "x-scopes": [ "events:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEventBatchParams" }, "example": { "events": [ { "id": "woocommerce:order:5012:order.paid:1", "type": "order.paid", "occurred_at": "2026-10-05T09:30:00Z", "site": { "name": "Acme Shop", "url": "https://shop.example.com/" }, "customer": { "id": "17", "name": "Layla Hassan", "first_name": "Layla", "last_name": "Hassan", "phone": "+971501234567", "email": "layla@example.com", "locale": "en", "country": "AE", "consent": { "transactional": true, "marketing": true, "source": "checkout_checkbox", "collected_at": "2026-10-05T09:29:40Z" } }, "order": { "id": "5012", "number": "1042", "status": "processing", "previous_status": "pending", "currency": "AED", "total": { "amount_minor": 12550, "currency": "AED", "formatted": "AED 125.50" }, "subtotal": { "amount_minor": 8000, "currency": "AED", "formatted": "AED 80.00" }, "shipping_total": { "amount_minor": 1500, "currency": "AED", "formatted": "AED 15.00" }, "discount_total": { "amount_minor": 0, "currency": "AED", "formatted": "AED 0.00" }, "items": [ { "id": "11", "name": "Mug", "sku": "MUG-1", "quantity": 2, "unit_price": { "amount_minor": 4000, "currency": "AED", "formatted": "AED 40.00" }, "url": "https://shop.example.com/mug" } ], "items_count": 2, "items_summary": "2 × Mug", "payment_method": "cod", "payment_method_title": "Cash on delivery", "shipping_method": "Flat rate", "tracking": { "number": "", "url": "", "carrier": "" }, "status_url": "https://shop.example.com/my-account/view-order/5012/", "note": "", "created_at": "2026-10-05T09:29:41Z" }, "data": {}, "source": "src_9Kd2mQ5vB8cX1zL0pK3j" }, { "id": "woocommerce:order:5012:order.shipped:1", "type": "order.shipped", "occurred_at": "2026-10-05T09:30:00Z", "site": { "name": "Acme Shop", "url": "https://shop.example.com/" }, "customer": { "id": "17", "name": "Layla Hassan", "first_name": "Layla", "last_name": "Hassan", "phone": "+971501234567", "email": "layla@example.com", "locale": "en", "country": "AE", "consent": { "transactional": true, "marketing": true, "source": "checkout_checkbox", "collected_at": "2026-10-05T09:29:40Z" } }, "order": { "id": "5012", "number": "1042", "status": "completed", "previous_status": "processing", "currency": "AED", "total": { "amount_minor": 12550, "currency": "AED", "formatted": "AED 125.50" }, "subtotal": { "amount_minor": 8000, "currency": "AED", "formatted": "AED 80.00" }, "shipping_total": { "amount_minor": 1500, "currency": "AED", "formatted": "AED 15.00" }, "discount_total": { "amount_minor": 0, "currency": "AED", "formatted": "AED 0.00" }, "items": [ { "id": "11", "name": "Mug", "sku": "MUG-1", "quantity": 2, "unit_price": { "amount_minor": 4000, "currency": "AED", "formatted": "AED 40.00" }, "url": "https://shop.example.com/mug" } ], "items_count": 2, "items_summary": "2 × Mug", "payment_method": "cod", "payment_method_title": "Cash on delivery", "shipping_method": "Flat rate", "tracking": { "number": "AX204981557", "url": "https://track.example.com/AX204981557", "carrier": "Aramex" }, "status_url": "https://shop.example.com/my-account/view-order/5012/", "note": "", "created_at": "2026-10-05T09:29:41Z" }, "data": {}, "source": "src_9Kd2mQ5vB8cX1zL0pK3j" } ] } } } }, "responses": { "207": { "description": "Per-item results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEventBatch" }, "example": { "object": "batch", "data": [ { "index": 0, "status": 202, "event": { "id": "aev_3kL9pQ2wE5rT8yU1iO4a", "object": "automation_event", "mode": "live", "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j", "event_id": "woocommerce:order:5012:order.paid:1", "type": "order.paid", "status": "accepted", "reason": null, "automations_matched": 1, "received_at": "2026-10-05T09:30:00.120Z" } }, { "index": 1, "status": 202, "event": { "id": "aev_8Jk3mP6qR9sT2vW5xY1z", "object": "automation_event", "mode": "live", "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j", "event_id": "woocommerce:order:5012:order.shipped:1", "type": "order.shipped", "status": "accepted", "reason": null, "automations_matched": 1, "received_at": "2026-10-05T09:30:00.120Z" } } ], "accepted": 2, "rejected": 0 } } } }, "400": { "description": "The envelope is malformed: `events` is missing, not an array, empty or longer than 100.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key may not push events, or the source is disabled.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "scope_missing": { "summary": "scope_missing", "value": { "error": { "type": "permission_error", "code": "scope_missing", "message": "This API key does not have the messages:write scope.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#scope_missing" } } }, "ip_not_allowed": { "summary": "ip_not_allowed", "value": { "error": { "type": "permission_error", "code": "ip_not_allowed", "message": "Requests from 203.0.113.7 are not allowed for this API key.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#ip_not_allowed" } } }, "account_suspended": { "summary": "account_suspended", "value": { "error": { "type": "permission_error", "code": "account_suspended", "message": "This account is suspended.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#account_suspended" } } }, "source_disabled": { "summary": "source_disabled", "value": { "error": { "type": "permission_error", "code": "source_disabled", "message": "This integration source is disabled.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#source_disabled" } } } } } } }, "413": { "description": "The body exceeds 256 KB.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#payload_too_large" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/automation_events/{id}": { "get": { "operationId": "getAutomationEvent", "summary": "Retrieve an event receipt", "description": "Returns one receipt with its `runs`: what each matched automation did.", "tags": [ "Automation events" ], "x-scopes": [ "events:read" ], "parameters": [ { "$ref": "#/components/parameters/AutomationEventId" } ], "responses": { "200": { "description": "The receipt.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEvent" }, "example": { "id": "aev_3kL9pQ2wE5rT8yU1iO4a", "object": "automation_event", "mode": "live", "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j", "event_id": "woocommerce:order:5012:order.paid:1", "type": "order.paid", "status": "accepted", "reason": null, "automations_matched": 1, "received_at": "2026-10-05T09:30:00.120Z", "runs": [ { "automation_id": "aut_5Cf8hK1mP4rT7vY0aD3g", "status": "sent", "scheduled_for": "2026-10-05T09:30:00.120Z", "message_id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "skip_reason": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ingest/{platform}/{source_id}": { "post": { "operationId": "ingestPlatformWebhook", "summary": "Receive a native platform webhook", "description": "Where a platform can deliver signed webhooks by itself, point them here and no plugin is needed. There is no bearer token: the platform signs the **raw body** with the signing secret of the source, `base64(HMAC-SHA256(raw body, secret))`, in `X-WC-Webhook-Signature` (WooCommerce) or `X-Shopify-Hmac-Sha256` (Shopify).\n\nThe delivery is stored and acknowledged at once; it is normalised into automation events afterwards. A delivery ID that was received before (`X-WC-Webhook-Delivery-ID`, `X-Shopify-Webhook-Id`) is acknowledged and not processed again. Topics that are not mapped are acknowledged and ignored, so that the platform never disables the webhook. The unsigned, form-encoded ping WooCommerce sends when a webhook is saved is answered with `200`.", "tags": [ "Automation events" ], "security": [], "parameters": [ { "name": "platform", "in": "path", "required": true, "description": "The platform that sends the webhook.", "schema": { "type": "string", "enum": [ "woocommerce", "shopify" ] }, "example": "woocommerce" }, { "name": "source_id", "in": "path", "required": true, "description": "Integration source ID.", "schema": { "type": "string" }, "example": "src_9Kd2mQ5vB8cX1zL0pK3j" } ], "requestBody": { "required": true, "description": "The platform's own payload, unchanged.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": 5012, "number": "1042", "status": "processing", "currency": "AED", "total": "125.50", "billing": { "first_name": "Layla", "last_name": "Hassan", "phone": "050 123 4567", "country": "AE", "email": "layla@example.com" }, "line_items": [ { "product_id": 11, "name": "Mug", "quantity": 2, "price": "40.00" } ], "date_modified_gmt": "2026-10-05T09:30:00" } } } }, "responses": { "200": { "description": "The signature is valid and the delivery is queued (or was received before).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestAck" }, "example": { "received": true } } } }, "400": { "description": "Unknown platform, or a signed body that is not a JSON object.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "description": "The signature header is missing or does not match the body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "webhook_signature_invalid": { "summary": "webhook_signature_invalid", "value": { "error": { "type": "authentication_error", "code": "webhook_signature_invalid", "message": "The webhook signature does not match.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#webhook_signature_invalid" } } } } } } }, "403": { "description": "The source is disabled.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_disabled": { "summary": "source_disabled", "value": { "error": { "type": "permission_error", "code": "source_disabled", "message": "This integration source is disabled.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#source_disabled" } } } } } } }, "404": { "description": "No such integration source.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "resource_missing", "value": { "error": { "type": "not_found_error", "code": "resource_missing", "message": "No such message: msg_2b1Xw9aQ3rT8yU0pL4kZ", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#resource_missing" } } } } } } }, "413": { "description": "The body exceeds 256 KB.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "summary": "payload_too_large", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#payload_too_large" } } } } } } }, "429": { "description": "More than 50 deliveries per second for this source.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Retry after 1 second.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#rate_limit_exceeded" } } } } } } }, "500": { "description": "Server error. Codes: `internal_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected error occurred.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#internal_error" } } } } } } } } } }, "/events": { "get": { "operationId": "listEvents", "summary": "List events", "description": "Returns the events of the key mode, newest first: the same objects webhooks deliver, whether or not an endpoint was subscribed. Use it as a polling fallback and to catch up after your endpoint was down. Events are kept for 30 days.", "tags": [ "Event feed" ], "x-scopes": [ "webhooks:read" ], "parameters": [ { "name": "type", "in": "query", "description": "Only events of this type.", "schema": { "type": "string" }, "example": "message.delivered" }, { "name": "created_after", "in": "query", "description": "Only events created after this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "A page of events.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "example": { "object": "list", "data": [ { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "message.delivered", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "delivered", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": "2026-10-05T09:30:02.871Z", "read_at": null, "failed_at": null } } } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Bad request. Codes: `parameter_invalid`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/events/{id}": { "get": { "operationId": "getEvent", "summary": "Retrieve an event", "description": "Returns one event by the ID webhooks carry in `OmniMessage-Event-Id`.", "tags": [ "Event feed" ], "x-scopes": [ "webhooks:read" ], "parameters": [ { "$ref": "#/components/parameters/FeedEventId" } ], "responses": { "200": { "description": "The event.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "message.delivered", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "delivered", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": "2026-10-05T09:30:02.871Z", "read_at": null, "failed_at": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/test/inbound_messages": { "post": { "operationId": "createTestInboundMessage", "summary": "Simulate an inbound message", "description": "Test mode only. Stores an inbound message as if a customer had written to a sandbox channel and emits `message.received`, so that \"message received\" triggers can be built and demonstrated without a live channel. Nothing is billed, and stop keywords are not applied.", "tags": [ "Messages" ], "x-scopes": [ "messages:write" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestInboundMessageParams" }, "example": { "channel": "ch_test_whatsapp", "from": "+971501234567", "type": "text", "text": { "body": "Where is my order?" }, "sender": { "name": "Layla Hassan" } } } } }, "responses": { "201": { "description": "The inbound message.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "id": "msg_4fD8sA1gH6jK9lZ3xC5v", "object": "message", "mode": "test", "channel_id": "ch_test_whatsapp", "channel_type": "whatsapp", "direction": "inbound", "to": "sandbox", "from": "+971501234567", "type": "text", "content": { "text": { "body": "Where is my order?" } }, "status": "received", "error": null, "reference": null, "metadata": {}, "billing": { "source": "none", "amount_micros": 0, "package_grant_id": null, "refunded": false }, "sender": { "name": "Layla Hassan", "username": null }, "contact_id": null, "created_at": "2026-10-05T09:42:10.000Z", "updated_at": "2026-10-05T09:42:10.000Z", "sent_at": null, "delivered_at": null, "read_at": null, "failed_at": null } } } }, "400": { "description": "Bad request. Codes: `parameter_missing`, `parameter_invalid`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } }, "parameter_invalid": { "summary": "parameter_invalid", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "to must be a phone number in E.164 format.", "param": "to", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_invalid" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "Request body is not valid JSON.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#invalid_json" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The key may not call the operation, or it is a live key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "scope_missing": { "summary": "scope_missing", "value": { "error": { "type": "permission_error", "code": "scope_missing", "message": "This API key does not have the messages:write scope.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#scope_missing" } } }, "ip_not_allowed": { "summary": "ip_not_allowed", "value": { "error": { "type": "permission_error", "code": "ip_not_allowed", "message": "Requests from 203.0.113.7 are not allowed for this API key.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#ip_not_allowed" } } }, "account_suspended": { "summary": "account_suspended", "value": { "error": { "type": "permission_error", "code": "account_suspended", "message": "This account is suspended.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#account_suspended" } } }, "test_mode_required": { "summary": "test_mode_required", "value": { "error": { "type": "permission_error", "code": "test_mode_required", "message": "Inbound messages can only be simulated with a test API key.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#test_mode_required" } } } } } } }, "404": { "description": "The channel is not a sandbox or test-mode channel of this account.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "resource_missing", "value": { "error": { "type": "not_found_error", "code": "resource_missing", "message": "No such message: msg_2b1Xw9aQ3rT8yU0pL4kZ", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#resource_missing" } } } } } } }, "409": { "description": "Conflict. Codes: `idempotency_key_in_use`, `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_in_use": { "summary": "idempotency_key_in_use", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_in_use", "message": "A request with this Idempotency-Key is still being processed.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_in_use" } } }, "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "conflict_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#idempotency_key_reused" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/me": { "get": { "operationId": "getAccount", "summary": "Retrieve the current account", "description": "Returns the account, mode and API key behind the request, and the `capabilities` of the API for this account. Any valid key can call it, whatever its scopes, which makes it the simplest way to check that a key works. Integrations check `capabilities` instead of probing endpoints.", "tags": [ "Account" ], "responses": { "200": { "description": "The account and key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "id": "acc_8nM3bV6cX9zL2kJ5hG1f", "name": "Acme Logistics", "mode": "live", "api_key": { "id": "key_1qW4eR7tY0uI3oP6aS9d", "name": "Production backend", "scopes": [ "messages:write", "messages:read", "channels:read" ] }, "capabilities": [ "automation_events", "webhook_filters", "test_inbound", "events_feed" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "webhooks": { "message.sent": { "post": { "operationId": "onMessageSent", "summary": "Message sent", "description": "The provider accepted an outbound message. `data.object` is the message with `status: \"sent\"`.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "message.sent", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "sent", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": null, "read_at": null, "failed_at": null } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "message.delivered": { "post": { "operationId": "onMessageDelivered", "summary": "Message delivered", "description": "An outbound message reached the recipient device. Not every channel reports delivery; SMS routes may stop at `sent`.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "message.delivered", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "delivered", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": "2026-10-05T09:30:02.871Z", "read_at": null, "failed_at": null } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "message.read": { "post": { "operationId": "onMessageRead", "summary": "Message read", "description": "The recipient opened an outbound message. Sent only on channels that report read receipts and when the recipient has them enabled.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "message.read", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "read", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": "2026-10-05T09:30:02.871Z", "read_at": "2026-10-05T09:31:15.402Z", "failed_at": null } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "message.failed": { "post": { "operationId": "onMessageFailed", "summary": "Message failed", "description": "An outbound message could not be delivered. `data.object.error` explains why. The charge has already been refunded: `billing.refunded` is `true`.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "message.failed", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "msg_9cV4nH7jK2mP5qR8sT1w", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "failed", "error": { "code": "provider_error", "message": "Message undeliverable.", "provider_code": "131026" }, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "wallet", "amount_micros": 1000, "package_grant_id": null, "refunded": true }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": null, "delivered_at": null, "read_at": null, "failed_at": "2026-10-05T09:30:03.118Z" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "message.received": { "post": { "operationId": "onMessageReceived", "summary": "Message received", "description": "A message arrived on one of your channels. `data.object` is a message with `direction: \"inbound\"` and `status: \"received\"`. Inbound messages are free.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "message.received", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "msg_4fD8sA1gH6jK9lZ3xC5v", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "inbound", "to": "+971800123456", "from": "+971501234567", "type": "text", "content": { "text": { "body": "Where is my order?" } }, "status": "received", "error": null, "reference": null, "metadata": {}, "billing": { "source": "none", "amount_micros": 0, "package_grant_id": null, "refunded": false }, "sender": { "name": "Layla Hassan", "username": null }, "contact_id": "ct_8Jk3mP6qR9sT2vW5xY1z", "created_at": "2026-10-05T09:42:10.000Z", "updated_at": "2026-10-05T09:42:10.000Z", "sent_at": null, "delivered_at": null, "read_at": null, "failed_at": null } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "channel.connected": { "post": { "operationId": "onChannelConnected", "summary": "Channel connected", "description": "A channel reached `connection_status: \"connected\"`, after being created or after a reconnect.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "channel.connected", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "ch_7Hq2mN5vB8cX1zL0pK3j", "object": "channel", "mode": "live", "type": "whatsapp", "name": "Support line", "identifier": "+971800123456", "status": "active", "connection_status": "connected", "capabilities": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "flow", "product", "product_list", "catalog", "carousel", "location_request" ], "created_at": "2026-10-01T08:00:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "channel.disconnected": { "post": { "operationId": "onChannelDisconnected", "summary": "Channel disconnected", "description": "A channel lost its link to the provider, for example because a token was revoked. Sending on it fails with `channel_not_connected` until it is reconnected.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "channel.disconnected", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "ch_7Hq2mN5vB8cX1zL0pK3j", "object": "channel", "mode": "live", "type": "whatsapp", "name": "Support line", "identifier": "+971800123456", "status": "active", "connection_status": "disconnected", "capabilities": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "flow", "product", "product_list", "catalog", "carousel", "location_request" ], "created_at": "2026-10-01T08:00:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "balance.low": { "post": { "operationId": "onBalanceLow", "summary": "Balance low", "description": "The wallet dropped below the low-balance threshold set in the console and no package credits remain. Sent at most once every 24 hours. `data.object` is the balance.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "balance.low", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "object": "balance", "currency": "USD", "wallet_micros": 1870000, "packages": [], "credits_remaining": 0 } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "package.exhausted": { "post": { "operationId": "onPackageExhausted", "summary": "Package exhausted", "description": "The last credit of a package was consumed. Further messages draw on the next package or the wallet. `data.object` is the package.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "package.exhausted", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "name": "100K messages", "quota": 100000, "remaining": 0, "channel_types": null, "expires_at": "2027-10-05T00:00:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "package.expiring": { "post": { "operationId": "onPackageExpiring", "summary": "Package expiring", "description": "A package with unused credits expires within 7 days. Sent once per package. `data.object` is the package.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "package.expiring", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "name": "100K messages", "quota": 100000, "remaining": 81234, "channel_types": null, "expires_at": "2026-10-12T00:00:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "campaign.started": { "post": { "operationId": "onCampaignStarted", "summary": "Campaign started", "description": "A campaign began sending: its audience snapshot is complete, or it was resumed after a pause. `data.object` is the campaign with `status: \"sending\"`.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "campaign.started", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "sending", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 1280, "queued": 640, "sent": 598, "delivered": 571, "read": 302, "failed": 9, "skipped": 33, "cancelled": 0, "skip_reasons": { "unsubscribed": 21, "no_identifier": 12 } }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 598 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": "2026-10-05T09:05:02.000Z", "paused_at": null, "completed_at": null, "cancelled_at": null } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "campaign.paused": { "post": { "operationId": "onCampaignPaused", "summary": "Campaign paused", "description": "A campaign stopped sending. `data.object.pause_reason` says why: `user`, `admin`, `channel_unavailable`, or `insufficient_balance` when the funds ran out (top up, then resume).", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "campaign.paused", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "paused", "pause_reason": "user", "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 1280, "queued": 640, "sent": 598, "delivered": 571, "read": 302, "failed": 9, "skipped": 33, "cancelled": 0, "skip_reasons": { "unsubscribed": 21, "no_identifier": 12 } }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 598 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": "2026-10-05T09:05:02.000Z", "paused_at": "2026-10-05T09:12:30.000Z", "completed_at": null, "cancelled_at": null } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "campaign.completed": { "post": { "operationId": "onCampaignCompleted", "summary": "Campaign completed", "description": "Every recipient of a campaign was processed. Delivery and read counters can still rise afterwards, as receipts arrive.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "campaign.completed", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "completed", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 1280, "queued": 0, "sent": 1229, "delivered": 1190, "read": 742, "failed": 18, "skipped": 33, "cancelled": 0, "skip_reasons": { "unsubscribed": 21, "no_identifier": 12 } }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 229000, "package_credits": 1000 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": "2026-10-05T09:05:02.000Z", "paused_at": null, "completed_at": "2026-10-05T09:07:10.000Z", "cancelled_at": null } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "campaign.failed": { "post": { "operationId": "onCampaignFailed", "summary": "Campaign failed", "description": "A campaign could not continue, for example because its channel was deleted. `data.object.failure_reason` explains why. Recipients not sent to yet are closed as `cancelled`.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "campaign.failed", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "failed", "pause_reason": null, "failure_reason": "The channel of this campaign was deleted.", "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 0, "queued": 0, "sent": 0, "delivered": 0, "read": 0, "failed": 0, "skipped": 0, "cancelled": 0, "skip_reasons": {} }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 0 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": null, "paused_at": null, "completed_at": null, "cancelled_at": null } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } }, "webhook.test": { "post": { "operationId": "onWebhookTest", "summary": "Test event", "description": "Sent only when you call `POST /v1/webhook_endpoints/{id}/test` or press \"Send test event\" in the console. It is delivered whatever the endpoint subscriptions are. `data.object` is the webhook endpoint.", "tags": [ "Webhook events" ], "security": [], "parameters": [ { "name": "OmniMessage-Signature", "in": "header", "required": true, "description": "`t=,v1=.\" keyed with the endpoint secret>`.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Id", "in": "header", "required": true, "description": "Same as `id` in the body.", "schema": { "type": "string" } }, { "name": "OmniMessage-Event-Type", "in": "header", "required": true, "description": "Same as `type` in the body.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Always `OmniMessage-Webhooks/1.0`.", "schema": { "type": "string", "const": "OmniMessage-Webhooks/1.0" } }, { "name": "OmniMessage-Verification-Token", "in": "header", "required": false, "description": "The `verification_token` of the endpoint, when it has one. For receivers that cannot verify the signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "webhook.test", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "mode": "live", "url": "https://example.com/hooks/omni", "description": "Production delivery receipts", "events": [ "message.delivered", "message.failed", "message.received" ], "status": "active", "filters": {}, "metadata": {}, "source": null, "created_by": { "type": "api_key", "id": "key_1qW4eR7tY0uI3oP6aS9d" }, "has_verification_token": false, "created_at": "2026-10-02T11:15:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within 10 seconds acknowledges the delivery." }, "default": { "description": "Any other status, or no response within 10 seconds, schedules a retry." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "om_live_... or om_test_...", "description": "API key created in the console, sent as `Authorization: Bearer `. The required scope of each operation is listed in `x-scopes`. An integration source key (`om_src_…`) is sent the same way and may only call the automation event endpoints and `/integration_sources/current`." } }, "schemas": { "Contact": { "type": "object", "title": "Contact", "description": "A person you can message. Contacts belong to the account: live and test keys see the same contacts.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `ct_`.", "examples": [ "ct_8Jk3mP6qR9sT2vW5xY1z" ] }, "object": { "type": "string", "const": "contact", "description": "Always `contact`." }, "first_name": { "type": [ "string", "null" ], "description": "Given name." }, "last_name": { "type": [ "string", "null" ], "description": "Family name." }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164. Unique within the account. The recipient identifier on WhatsApp and SMS channels." }, "email": { "type": [ "string", "null" ], "description": "Email address." }, "channel_identifiers": { "type": "object", "description": "Recipient identifiers for the channel types that do not use a phone number: the Telegram chat ID, the page-scoped ID on Messenger and Instagram, the TikTok user ID.", "properties": { "telegram": { "type": "string", "maxLength": 255, "description": "Identifier on telegram." }, "messenger": { "type": "string", "maxLength": 255, "description": "Identifier on messenger." }, "instagram": { "type": "string", "maxLength": 255, "description": "Identifier on instagram." }, "tiktok": { "type": "string", "maxLength": 255, "description": "Identifier on tiktok." } }, "additionalProperties": false }, "locale": { "type": [ "string", "null" ], "description": "Language tag." }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone." }, "attributes": { "type": "object", "description": "Custom attributes by key.", "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags of the contact." }, "consent": { "type": "object", "description": "Consent per channel type. A channel type without an entry has the state `unknown`.", "propertyNames": { "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ] }, "additionalProperties": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "opted_in", "opted_out" ], "description": "`opted_out` is an unsubscribe." }, "source": { "type": [ "string", "null" ], "description": "Where the state came from: `console`, `api`, `import:`, `campaign:` or `keyword:` for a STOP-style reply." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the state was set." } }, "required": [ "state", "source", "updated_at" ], "additionalProperties": false } }, "blocked": { "type": "boolean", "description": "Blocked contacts are never messaged by a campaign." }, "blocked_reason": { "type": [ "string", "null" ], "description": "Why the contact is blocked." }, "last_messaged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the contact was last sent a message." }, "created_at": { "type": "string", "format": "date-time", "description": "When the contact was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the contact was last changed." } }, "required": [ "id", "object", "first_name", "last_name", "phone", "email", "channel_identifiers", "locale", "timezone", "attributes", "tags", "consent", "blocked", "blocked_reason", "last_messaged_at", "created_at", "updated_at" ], "additionalProperties": false, "examples": [ { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "channel_identifiers": { "telegram": "482910375" }, "locale": "ar", "timezone": "Asia/Dubai", "attributes": { "city": "Dubai", "orders": 12 }, "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": { "state": "opted_in", "source": "api", "updated_at": "2026-10-01T08:00:00.000Z" } }, "blocked": false, "blocked_reason": null, "last_messaged_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-05T09:30:00.000Z" } ] }, "ContactList": { "type": "object", "description": "A page of contacts, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "description": "Page of results." }, "has_more": { "type": "boolean", "description": "Whether more results exist after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `starting_after` to fetch the next page. `null` when `has_more` is `false`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "ContactCreateParams": { "type": "object", "title": "Create contact request", "description": "At least one of `phone`, `email` or a channel identifier is required.", "properties": { "first_name": { "type": [ "string", "null" ], "description": "Given name, up to 100 characters.", "maxLength": 100 }, "last_name": { "type": [ "string", "null" ], "description": "Family name, up to 100 characters.", "maxLength": 100 }, "phone": { "type": [ "string", "null" ], "description": "Phone number. International format (`+971501234567`) or a national number of the account country; it is stored in E.164.", "maxLength": 40 }, "email": { "type": [ "string", "null" ], "description": "Email address.", "maxLength": 254 }, "channel_identifiers": { "type": "object", "description": "Identifiers for Telegram, Messenger, Instagram and TikTok. `null` removes one.", "properties": { "telegram": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on telegram." }, "messenger": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on messenger." }, "instagram": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on instagram." }, "tiktok": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on tiktok." } }, "additionalProperties": false }, "locale": { "type": [ "string", "null" ], "description": "Language tag such as `en` or `pt-BR`." }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone such as `Asia/Dubai`. Campaigns can apply their send window in it." }, "attributes": { "type": "object", "description": "Custom attributes by key. Keys must be defined in the console first; a value is checked against the type of its definition. `null` removes an attribute.", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "tags": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "Up to 50 tags. Replaces the current tags on update." }, "consent": { "type": "object", "description": "Consent per channel type. `opted_out` is an unsubscribe: campaigns skip the contact on that channel type. `unknown` clears the entry.", "propertyNames": { "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ] }, "additionalProperties": { "type": "string", "enum": [ "opted_in", "opted_out", "unknown" ] } }, "blocked": { "type": "boolean", "description": "A blocked contact is never messaged by a campaign, on any channel." }, "blocked_reason": { "type": [ "string", "null" ], "description": "Why the contact is blocked.", "maxLength": 255 } }, "additionalProperties": false }, "ContactUpsertParams": { "type": "object", "title": "Upsert contact request", "description": "Creates the contact, or updates the contact that already has this phone number. On update only the fields you send change, and `tags` are added to the existing ones.", "properties": { "first_name": { "type": [ "string", "null" ], "description": "Given name, up to 100 characters.", "maxLength": 100 }, "last_name": { "type": [ "string", "null" ], "description": "Family name, up to 100 characters.", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40, "description": "Phone number that identifies the contact." }, "email": { "type": [ "string", "null" ], "description": "Email address.", "maxLength": 254 }, "channel_identifiers": { "type": "object", "description": "Identifiers for Telegram, Messenger, Instagram and TikTok. `null` removes one.", "properties": { "telegram": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on telegram." }, "messenger": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on messenger." }, "instagram": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on instagram." }, "tiktok": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on tiktok." } }, "additionalProperties": false }, "locale": { "type": [ "string", "null" ], "description": "Language tag such as `en` or `pt-BR`." }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone such as `Asia/Dubai`. Campaigns can apply their send window in it." }, "attributes": { "type": "object", "description": "Custom attributes by key. Keys must be defined in the console first; a value is checked against the type of its definition. `null` removes an attribute.", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "tags": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "Up to 50 tags. Replaces the current tags on update." }, "consent": { "type": "object", "description": "Consent per channel type. `opted_out` is an unsubscribe: campaigns skip the contact on that channel type. `unknown` clears the entry.", "propertyNames": { "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ] }, "additionalProperties": { "type": "string", "enum": [ "opted_in", "opted_out", "unknown" ] } }, "blocked": { "type": "boolean", "description": "A blocked contact is never messaged by a campaign, on any channel." }, "blocked_reason": { "type": [ "string", "null" ], "description": "Why the contact is blocked.", "maxLength": 255 } }, "required": [ "phone" ], "additionalProperties": false }, "ContactUpdateParams": { "type": "object", "title": "Update contact request", "description": "Only the fields you send change.", "properties": { "first_name": { "type": [ "string", "null" ], "description": "Given name, up to 100 characters.", "maxLength": 100 }, "last_name": { "type": [ "string", "null" ], "description": "Family name, up to 100 characters.", "maxLength": 100 }, "phone": { "type": [ "string", "null" ], "description": "Phone number. International format (`+971501234567`) or a national number of the account country; it is stored in E.164.", "maxLength": 40 }, "email": { "type": [ "string", "null" ], "description": "Email address.", "maxLength": 254 }, "channel_identifiers": { "type": "object", "description": "Identifiers for Telegram, Messenger, Instagram and TikTok. `null` removes one.", "properties": { "telegram": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on telegram." }, "messenger": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on messenger." }, "instagram": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on instagram." }, "tiktok": { "type": [ "string", "null" ], "maxLength": 255, "description": "Identifier on tiktok." } }, "additionalProperties": false }, "locale": { "type": [ "string", "null" ], "description": "Language tag such as `en` or `pt-BR`." }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone such as `Asia/Dubai`. Campaigns can apply their send window in it." }, "attributes": { "type": "object", "description": "Custom attributes by key. Keys must be defined in the console first; a value is checked against the type of its definition. `null` removes an attribute.", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "tags": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "Up to 50 tags. Replaces the current tags on update." }, "consent": { "type": "object", "description": "Consent per channel type. `opted_out` is an unsubscribe: campaigns skip the contact on that channel type. `unknown` clears the entry.", "propertyNames": { "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ] }, "additionalProperties": { "type": "string", "enum": [ "opted_in", "opted_out", "unknown" ] } }, "blocked": { "type": "boolean", "description": "A blocked contact is never messaged by a campaign, on any channel." }, "blocked_reason": { "type": [ "string", "null" ], "description": "Why the contact is blocked.", "maxLength": 255 } }, "additionalProperties": false }, "ContactTagsParams": { "type": "object", "title": "Tag contacts request", "properties": { "contact_ids": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string" }, "description": "Contacts to change, up to 1,000. Unknown IDs are ignored." }, "add": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "Tags to add." }, "remove": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "Tags to remove." } }, "required": [ "contact_ids" ], "additionalProperties": false }, "BulkResult": { "type": "object", "title": "Bulk result", "properties": { "object": { "type": "string", "const": "bulk_result", "description": "Always `bulk_result`." }, "affected": { "type": "integer", "minimum": 0, "description": "Contacts that were changed." } }, "required": [ "object", "affected" ], "additionalProperties": false, "examples": [ { "object": "bulk_result", "affected": 2 } ] }, "ContactTag": { "type": "object", "title": "Contact tag", "properties": { "object": { "type": "string", "const": "contact_tag", "description": "Always `contact_tag`." }, "name": { "type": "string", "description": "The tag." }, "contact_count": { "type": "integer", "minimum": 0, "description": "Contacts carrying the tag." } }, "required": [ "object", "name", "contact_count" ], "additionalProperties": false, "examples": [ { "object": "contact_tag", "name": "vip", "contact_count": 412 } ] }, "ContactTagList": { "type": "object", "description": "Every tag in use, most used first. Not paginated: `has_more` is always `false`.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactTag" }, "description": "All results." }, "has_more": { "type": "boolean", "const": false, "description": "Always `false`: the list is returned whole." }, "next_cursor": { "type": "null", "description": "Always `null`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "ContactGroup": { "type": "object", "title": "Contact list", "description": "A static list of contacts. A contact can be on any number of lists.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `lst_`.", "examples": [ "lst_4Bd7fH0jL3nQ6sU9wZ2c" ] }, "object": { "type": "string", "const": "contact_list", "description": "Always `contact_list`." }, "name": { "type": "string", "description": "Name of the list." }, "description": { "type": [ "string", "null" ], "description": "Note about the list." }, "contact_count": { "type": "integer", "minimum": 0, "description": "Contacts on the list." }, "created_at": { "type": "string", "format": "date-time", "description": "When the list was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the list was last renamed or described." } }, "required": [ "id", "object", "name", "description", "contact_count", "created_at", "updated_at" ], "additionalProperties": false, "examples": [ { "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c", "object": "contact_list", "name": "October launch", "description": "Customers invited to the launch", "contact_count": 1280, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-04T16:20:00.000Z" } ] }, "ContactGroupList": { "type": "object", "description": "A page of contact lists, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactGroup" }, "description": "Page of results." }, "has_more": { "type": "boolean", "description": "Whether more results exist after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `starting_after` to fetch the next page. `null` when `has_more` is `false`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "ContactGroupCreateParams": { "type": "object", "title": "Create contact list request", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the list." }, "description": { "type": [ "string", "null" ], "description": "Optional note, up to 500 characters.", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, "ContactGroupUpdateParams": { "type": "object", "title": "Update contact list request", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "New name." }, "description": { "type": [ "string", "null" ], "description": "New note; `null` clears it.", "maxLength": 500 } }, "additionalProperties": false }, "ContactGroupMembersParams": { "type": "object", "title": "List members request", "properties": { "contact_ids": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string" }, "description": "Contact IDs, up to 1,000 per request. Unknown IDs are ignored." } }, "required": [ "contact_ids" ], "additionalProperties": false }, "SegmentCondition": { "type": "object", "title": "Condition", "description": "One test on a contact field. Fields: `first_name`, `last_name`, `phone`, `email`, `locale`, `timezone` (text: `eq`, `neq`, `contains`, `starts_with`, `is_set`, `is_not_set`); `created_at`, `last_messaged_at` (date: `before`, `after`, `in_last_days`, `not_in_last_days`, `is_set`, `is_not_set`); `tags` (`has_any`, `has_all`, `has_none`); `list` (`in`, `not_in`); `consent.` (`is` with `opted_in`, `opted_out` or `unknown`); `blocked` (`is`); `attributes.` with the operators of the attribute type (number: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`).", "properties": { "field": { "type": "string", "description": "Field the condition tests." }, "operator": { "type": "string", "description": "Comparison." }, "value": { "description": "Value to compare with. Not used by `is_set` and `is_not_set`.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "field", "operator" ], "additionalProperties": false }, "SegmentGroup": { "type": "object", "title": "Group", "description": "Conditions and nested groups combined with `and` or `or`. Groups nest up to three levels deep.", "properties": { "op": { "type": "string", "enum": [ "and", "or" ], "description": "How the rules are combined." }, "rules": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/SegmentCondition" }, { "$ref": "#/components/schemas/SegmentGroup" } ] }, "description": "Conditions and groups." } }, "required": [ "op", "rules" ], "additionalProperties": false }, "Segment": { "type": "object", "title": "Segment", "description": "A saved filter over contacts. Segments are built in the console; membership is evaluated whenever the segment is used.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `seg_`.", "examples": [ "seg_1Ae4gI7kM0oR3tV6xB9d" ] }, "object": { "type": "string", "const": "segment", "description": "Always `segment`." }, "name": { "type": "string", "description": "Name of the segment." }, "description": { "type": [ "string", "null" ], "description": "Note about the segment." }, "rules": { "$ref": "#/components/schemas/SegmentGroup" }, "created_at": { "type": "string", "format": "date-time", "description": "When the segment was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the segment was last changed." } }, "required": [ "id", "object", "name", "description", "rules", "created_at", "updated_at" ], "additionalProperties": false, "examples": [ { "id": "seg_1Ae4gI7kM0oR3tV6xB9d", "object": "segment", "name": "VIP customers not messaged this month", "description": null, "rules": { "op": "and", "rules": [ { "field": "tags", "operator": "has_any", "value": [ "vip" ] }, { "field": "consent.whatsapp", "operator": "is", "value": "opted_in" }, { "field": "last_messaged_at", "operator": "not_in_last_days", "value": 30 } ] }, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-01T08:00:00.000Z" } ] }, "SegmentList": { "type": "object", "description": "A page of segments, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" }, "description": "Page of results." }, "has_more": { "type": "boolean", "description": "Whether more results exist after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `starting_after` to fetch the next page. `null` when `has_more` is `false`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "SegmentPreview": { "type": "object", "title": "Segment preview", "properties": { "object": { "type": "string", "const": "segment_preview", "description": "Always `segment_preview`." }, "segment_id": { "type": [ "string", "null" ], "description": "The segment that was evaluated." }, "count": { "type": "integer", "minimum": 0, "description": "Contacts matching the rules right now." }, "sample": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "description": "Up to five matching contacts, newest first." } }, "required": [ "object", "segment_id", "count", "sample" ], "additionalProperties": false, "examples": [ { "object": "segment_preview", "segment_id": "seg_1Ae4gI7kM0oR3tV6xB9d", "count": 412, "sample": [ { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "channel_identifiers": { "telegram": "482910375" }, "locale": "ar", "timezone": "Asia/Dubai", "attributes": { "city": "Dubai", "orders": 12 }, "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": { "state": "opted_in", "source": "api", "updated_at": "2026-10-01T08:00:00.000Z" } }, "blocked": false, "blocked_reason": null, "last_messaged_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-05T09:30:00.000Z" } ] } ] }, "Campaign": { "type": "object", "title": "Campaign", "description": "One message sent to many recipients, with its progress.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `cmp_`.", "examples": [ "cmp_5Cf8hK1mP4rT7vY0aD3g" ] }, "object": { "type": "string", "const": "campaign", "description": "Always `campaign`." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "Mode of the API key that created the campaign. Test-mode campaigns run against the sandbox and are free." }, "name": { "type": "string", "description": "Name of the campaign." }, "channel_id": { "type": "string", "description": "Channel the campaign sends on." }, "channel_type": { "type": "string", "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ], "description": "Type of that channel." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "queued", "sending", "paused", "completed", "cancelled", "failed" ], "description": "`draft` until launched; `scheduled` while waiting for `schedule.send_at`; `queued` while the audience snapshot is taken; `sending`; `paused`; then `completed`, `cancelled` or `failed`." }, "pause_reason": { "type": [ "string", "null" ], "enum": [ "user", "admin", "insufficient_balance", "channel_unavailable", null ], "description": "Why the campaign is paused. `insufficient_balance` means the funds ran out: top up, then resume." }, "failure_reason": { "type": [ "string", "null" ], "description": "Why the campaign failed." }, "audience": { "description": "Who the campaign is sent to.", "oneOf": [ { "type": "object", "title": "Segment", "properties": { "type": { "type": "string", "const": "segment" }, "segment_id": { "type": "string", "description": "Segment ID. The rules are evaluated when sending starts." } }, "required": [ "type", "segment_id" ], "additionalProperties": false }, { "type": "object", "title": "List", "properties": { "type": { "type": "string", "const": "list" }, "list_id": { "type": "string", "description": "Contact list ID." } }, "required": [ "type", "list_id" ], "additionalProperties": false }, { "type": "object", "title": "Tags", "properties": { "type": { "type": "string", "const": "tags" }, "tags": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string" }, "description": "Contacts carrying these tags." }, "match": { "type": "string", "enum": [ "any", "all" ], "description": "Whether a contact needs one of the tags or all of them." } }, "required": [ "type", "tags", "match" ], "additionalProperties": false }, { "type": "object", "title": "Pasted recipients", "properties": { "type": { "type": "string", "const": "adhoc" }, "count": { "type": "integer", "description": "Number of recipients supplied with the campaign." }, "save_as_contacts": { "type": "boolean", "description": "Whether the recipients are saved as contacts when the campaign starts." } }, "required": [ "type", "count", "save_as_contacts" ], "additionalProperties": false } ] }, "message": { "type": "object", "description": "What is sent: `type` and the content object under the key named by `type`, exactly as in `POST /v1/messages`. Strings may contain merge tags such as `{{first_name}}`, `{{last_name}}`, `{{full_name}}`, `{{phone}}`, `{{email}}`, `{{locale}}` and `{{attributes.}}`; each recipient gets their own value. Unknown tags are rejected when the campaign is saved.", "properties": { "type": { "type": "string", "description": "Message type. Must be one of the `capabilities` of the channel. Live WhatsApp campaigns must use `template`." } }, "required": [ "type" ], "additionalProperties": true }, "merge_fallbacks": { "type": "object", "description": "Value used for a merge tag when a recipient has none.", "additionalProperties": { "type": "string" } }, "require_opt_in": { "type": "boolean", "description": "When `true`, only contacts whose consent for the channel type is `opted_in` are messaged; the others are skipped as `no_consent`." }, "consent_declared": { "type": "boolean", "description": "Whether you declared that the recipients agreed to be contacted. Required to launch." }, "schedule": { "type": "object", "description": "When the campaign sends.", "properties": { "send_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When sending starts. `null` starts as soon as the campaign is launched." }, "timezone": { "type": "string", "description": "IANA time zone of `send_window`. Defaults to the time zone of the account." }, "send_window": { "type": [ "object", "null" ], "description": "Local-time window outside which nothing is sent (quiet hours). A window whose `end` is not after its `start` runs overnight.", "properties": { "start": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Start, `HH:MM`." }, "end": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "End, `HH:MM`." } }, "required": [ "start", "end" ], "additionalProperties": false }, "recipient_timezone": { "type": "boolean", "description": "Apply `send_window` in the time zone of each contact that has one, instead of `timezone`." } }, "additionalProperties": false, "required": [ "send_at", "timezone", "send_window", "recipient_timezone" ] }, "throttle_per_second": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Most messages per second the campaign sends." }, "counters": { "type": "object", "description": "Progress. `total` is fixed when the audience snapshot is complete; `queued + sent + failed + skipped + cancelled` equals `total`.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Recipients in the snapshot." }, "queued": { "type": "integer", "minimum": 0, "description": "Recipients not sent to yet." }, "sent": { "type": "integer", "minimum": 0, "description": "Messages accepted and not failed. Includes delivered and read." }, "delivered": { "type": "integer", "minimum": 0, "description": "Messages delivered. Includes read." }, "read": { "type": "integer", "minimum": 0, "description": "Messages read." }, "failed": { "type": "integer", "minimum": 0, "description": "Messages rejected or failed." }, "skipped": { "type": "integer", "minimum": 0, "description": "Recipients that were never sent to." }, "cancelled": { "type": "integer", "minimum": 0, "description": "Recipients left unsent when the campaign was cancelled." }, "skip_reasons": { "type": "object", "description": "Skipped recipients by reason.", "propertyNames": { "enum": [ "no_identifier", "no_consent", "unsubscribed", "duplicate", "invalid_number", "insufficient_balance" ] }, "additionalProperties": { "type": "integer" } } }, "required": [ "total", "queued", "sent", "delivered", "read", "failed", "skipped", "cancelled", "skip_reasons" ], "additionalProperties": false }, "cost": { "type": "object", "description": "Gateway fee of the campaign. Fees of the channel provider (for example Meta conversation fees) are billed by the provider and are not included.", "properties": { "currency": { "type": "string", "const": "USD", "description": "Always `USD`." }, "estimated_wallet_micros": { "type": [ "integer", "null" ], "description": "Estimate made at launch of what the wallet would be charged, in micro-USD. `null` before launch." }, "estimated_credits": { "type": [ "integer", "null" ], "description": "Estimate made at launch of the package credits that would be used." }, "wallet_micros": { "type": "integer", "description": "Charged to the wallet so far, net of refunds for failed messages, in micro-USD." }, "package_credits": { "type": "integer", "description": "Package credits used so far, net of credits returned for failed messages." } }, "required": [ "currency", "estimated_wallet_micros", "estimated_credits", "wallet_micros", "package_credits" ], "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "When the campaign was created." }, "launched_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the campaign was launched." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When sending started." }, "paused_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the campaign was last paused." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the last recipient was processed." }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the campaign was cancelled." } }, "required": [ "id", "object", "mode", "name", "channel_id", "channel_type", "status", "pause_reason", "failure_reason", "audience", "message", "merge_fallbacks", "require_opt_in", "consent_declared", "schedule", "throttle_per_second", "counters", "cost", "created_at", "launched_at", "started_at", "paused_at", "completed_at", "cancelled_at" ], "additionalProperties": false, "examples": [ { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "sending", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 1280, "queued": 640, "sent": 598, "delivered": 571, "read": 302, "failed": 9, "skipped": 33, "cancelled": 0, "skip_reasons": { "unsubscribed": 21, "no_identifier": 12 } }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 598 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": "2026-10-05T09:05:02.000Z", "paused_at": null, "completed_at": null, "cancelled_at": null } ] }, "CampaignList": { "type": "object", "description": "A page of campaigns, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" }, "description": "Page of results." }, "has_more": { "type": "boolean", "description": "Whether more results exist after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `starting_after` to fetch the next page. `null` when `has_more` is `false`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "CampaignCreateParams": { "type": "object", "title": "Create campaign request", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Name of the campaign." }, "channel": { "type": "string", "description": "Channel ID. With a test key, a sandbox channel such as `ch_test_whatsapp`." }, "audience": { "description": "Who to send to: a segment, a list, contacts with certain tags, or recipients supplied with the request.", "oneOf": [ { "type": "object", "title": "Segment", "properties": { "type": { "type": "string", "const": "segment" }, "segment_id": { "type": "string", "description": "Segment ID. The rules are evaluated when sending starts." } }, "required": [ "type", "segment_id" ], "additionalProperties": false }, { "type": "object", "title": "List", "properties": { "type": { "type": "string", "const": "list" }, "list_id": { "type": "string", "description": "Contact list ID." } }, "required": [ "type", "list_id" ], "additionalProperties": false }, { "type": "object", "title": "Tags", "properties": { "type": { "type": "string", "const": "tags" }, "tags": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string" }, "description": "Contacts carrying these tags." }, "match": { "type": "string", "enum": [ "any", "all" ], "default": "any", "description": "Whether a contact needs one of the tags or all of them." } }, "required": [ "type", "tags" ], "additionalProperties": false }, { "type": "object", "title": "Pasted recipients", "properties": { "type": { "type": "string", "const": "adhoc" }, "recipients": { "type": "array", "minItems": 1, "maxItems": 10000, "description": "Up to 10,000 recipients.", "items": { "type": "object", "properties": { "to": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Recipient identifier on the channel: a phone number for WhatsApp and SMS." }, "first_name": { "type": "string", "maxLength": 100, "description": "Given name, for `{{first_name}}`." }, "last_name": { "type": "string", "maxLength": 100, "description": "Family name, for `{{last_name}}`." }, "variables": { "type": "object", "description": "Merge values of this recipient by tag.", "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "to" ], "additionalProperties": false } }, "save_as_contacts": { "type": "boolean", "default": false, "description": "Save the recipients as contacts when sending starts (phone channels)." } }, "required": [ "type", "recipients" ], "additionalProperties": false } ] }, "message": { "type": "object", "description": "What is sent: `type` and the content object under the key named by `type`, exactly as in `POST /v1/messages`. Strings may contain merge tags such as `{{first_name}}`, `{{last_name}}`, `{{full_name}}`, `{{phone}}`, `{{email}}`, `{{locale}}` and `{{attributes.}}`; each recipient gets their own value. Unknown tags are rejected when the campaign is saved.", "properties": { "type": { "type": "string", "description": "Message type. Must be one of the `capabilities` of the channel. Live WhatsApp campaigns must use `template`." } }, "required": [ "type" ], "additionalProperties": true }, "merge_fallbacks": { "type": "object", "description": "Value for a merge tag when a recipient has none, by tag.", "additionalProperties": { "type": "string", "maxLength": 200 } }, "require_opt_in": { "type": "boolean", "default": false, "description": "Only message contacts whose consent for the channel type is `opted_in`." }, "consent_declared": { "type": "boolean", "default": false, "description": "Declare that the recipients agreed to receive messages from you on this channel. Can also be sent when launching." }, "launch": { "type": "boolean", "default": false, "description": "Create and launch in one request. Needs `consent_declared: true`. When the launch is refused, nothing is created." }, "allow_insufficient_funds": { "type": "boolean", "default": false, "description": "With `launch`: start although the funds do not cover every recipient. The campaign pauses when they run out." }, "schedule": { "type": "object", "description": "When the campaign sends.", "properties": { "send_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When sending starts. `null` starts as soon as the campaign is launched." }, "timezone": { "type": "string", "description": "IANA time zone of `send_window`. Defaults to the time zone of the account." }, "send_window": { "type": [ "object", "null" ], "description": "Local-time window outside which nothing is sent (quiet hours). A window whose `end` is not after its `start` runs overnight.", "properties": { "start": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Start, `HH:MM`." }, "end": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "End, `HH:MM`." } }, "required": [ "start", "end" ], "additionalProperties": false }, "recipient_timezone": { "type": "boolean", "description": "Apply `send_window` in the time zone of each contact that has one, instead of `timezone`." } }, "additionalProperties": false }, "throttle_per_second": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Most messages per second. Defaults to 20 and is capped by the per-channel limit." } }, "required": [ "name", "channel", "audience", "message" ], "additionalProperties": false }, "CampaignLaunchParams": { "type": "object", "title": "Launch campaign request", "properties": { "consent_declared": { "type": "boolean", "description": "Declare that the recipients agreed to be contacted, if the campaign does not carry the declaration yet." }, "allow_insufficient_funds": { "type": "boolean", "default": false, "description": "Launch although the funds do not cover every recipient. The campaign then pauses with `pause_reason: \"insufficient_balance\"` when they run out." } }, "additionalProperties": false }, "CampaignRecipient": { "type": "object", "title": "Campaign recipient", "description": "One recipient of a campaign, as snapshotted when sending started.", "properties": { "id": { "type": "string", "description": "Identifier of the recipient within the campaign; the pagination cursor." }, "object": { "type": "string", "const": "campaign_recipient", "description": "Always `campaign_recipient`." }, "contact_id": { "type": [ "string", "null" ], "description": "The contact, when the recipient is one." }, "to": { "type": [ "string", "null" ], "description": "Recipient identifier the message is sent to. `null` when the contact has none for the channel type." }, "name": { "type": [ "string", "null" ], "description": "Display name." }, "status": { "type": "string", "enum": [ "pending", "sent", "delivered", "read", "failed", "skipped", "cancelled" ], "description": "`pending` until sent, then the status of the message, or `skipped` / `cancelled`." }, "skip_reason": { "type": [ "string", "null" ], "enum": [ "no_identifier", "no_consent", "unsubscribed", "duplicate", "invalid_number", "insufficient_balance", null ], "description": "Why the recipient was skipped." }, "message_id": { "type": [ "string", "null" ], "description": "The message that was sent to the recipient." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/MessageError" }, { "type": "null" } ], "description": "Why the send failed." }, "variables": { "type": "object", "description": "Merge values of this recipient.", "additionalProperties": { "type": "string" } }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the message was accepted." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the message was delivered." }, "read_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the message was read." }, "failed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the message failed." } }, "required": [ "id", "object", "contact_id", "to", "name", "status", "skip_reason", "message_id", "error", "variables", "sent_at", "delivered_at", "read_at", "failed_at" ], "additionalProperties": false, "examples": [ { "id": "184467", "object": "campaign_recipient", "contact_id": "ct_8Jk3mP6qR9sT2vW5xY1z", "to": "+971501234567", "name": "Layla Haddad", "status": "delivered", "skip_reason": null, "message_id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "error": null, "variables": { "first_name": "Layla" }, "sent_at": "2026-10-05T09:05:03.120Z", "delivered_at": "2026-10-05T09:05:04.871Z", "read_at": null, "failed_at": null } ] }, "CampaignRecipientList": { "type": "object", "description": "A page of recipients in snapshot order.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignRecipient" }, "description": "Page of results." }, "has_more": { "type": "boolean", "description": "Whether more results exist after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `starting_after` to fetch the next page. `null` when `has_more` is `false`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "IntegrationSource": { "type": "object", "title": "Integration source", "description": "One connected store or site: a plugin installation, a native platform webhook, or your own integration. Plugins read `enabled_events` and `event_settings` from it to know what to send.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `src_`.", "examples": [ "src_9Kd2mQ5vB8cX1zL0pK3j" ] }, "object": { "type": "string", "const": "integration_source", "description": "Always `integration_source`." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "Mode of the key that registered the source. A test source runs against the sandbox and is free." }, "platform": { "type": "string", "description": "Platform slug: `woocommerce`, `wordpress`, `shopify`, `salla`, `zid`, `ikas`, `ticimax`, `custom`, or any other lower-case slug of up to 32 characters." }, "external_id": { "type": "string", "maxLength": 255, "description": "The platform's stable identifier of the store or site: a host name, a shop domain, a merchant ID. `(mode, platform, external_id)` is unique per account." }, "name": { "type": "string", "description": "Display name." }, "url": { "type": [ "string", "null" ], "description": "Public address of the store or site." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "A `disabled` source is refused: its key and its native webhooks answer `403 source_disabled`." }, "plugin_version": { "type": [ "string", "null" ], "description": "Version of the plugin or connector, as it reported it." }, "platform_version": { "type": [ "string", "null" ], "description": "Version of the platform, as the plugin reported it." }, "emits": { "type": "array", "items": { "type": "string" }, "description": "Event types the plugin is able to send. Informational: the console offers these first." }, "enabled_events": { "type": "array", "items": { "type": "string" }, "description": "Event types the plugin should send: those with an enabled automation, and those that cancel one. `[\"*\"]` means send everything." }, "event_settings": { "type": "object", "description": "Hints a plugin needs to behave well, keyed by event type. `cart.abandoned.delay_seconds` is the delay of the reminder: report the cart no later than this after the last cart activity.", "additionalProperties": { "type": "object", "properties": { "delay_seconds": { "type": "integer" } }, "additionalProperties": true } }, "console_url": { "type": "string", "format": "uri", "description": "The automations of this source in the console." }, "automation_url_template": { "type": "string", "description": "Editor of one event type: replace `{event_type}`." }, "ingest_urls": { "type": "object", "description": "Where the platform's own signed webhooks can be pointed, per platform.", "properties": { "woocommerce": { "type": "string", "format": "uri" }, "shopify": { "type": "string", "format": "uri" } }, "required": [ "woocommerce", "shopify" ], "additionalProperties": false }, "config_version": { "type": "integer", "description": "Increases whenever `enabled_events` or `event_settings` change. Also the `ETag` of the source." }, "last_event_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the last event of this source was received." }, "created_at": { "type": "string", "format": "date-time", "description": "When the source was registered." }, "source_key": { "type": "string", "description": "The key of this source, prefixed `om_src_`. It can only push events and read or describe this source. Returned only when the source is created and when the key is rolled." }, "signing_secret": { "type": "string", "description": "The secret native webhooks are verified with, prefixed `isec_`. Returned only when the source is created and when the key is rolled." } }, "required": [ "id", "object", "mode", "platform", "external_id", "name", "url", "status", "plugin_version", "platform_version", "emits", "enabled_events", "event_settings", "console_url", "automation_url_template", "ingest_urls", "config_version", "last_event_at", "created_at" ], "additionalProperties": false, "examples": [ { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [ "order.paid", "order.shipped" ], "event_settings": { "cart.abandoned": { "delay_seconds": 3600 } }, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 12, "last_event_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z" } ] }, "IntegrationSourceList": { "type": "object", "title": "Integration source list", "description": "A page of integration sources, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationSource" }, "description": "The sources." }, "has_more": { "type": "boolean", "description": "Whether more objects follow." }, "next_cursor": { "type": [ "string", "null" ], "description": "ID of the last object while `has_more` is `true`, otherwise `null`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "IntegrationSourceCreateParams": { "type": "object", "title": "Register integration source request", "properties": { "platform": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$", "description": "Platform slug." }, "external_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The platform's stable identifier of the store or site." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name. Defaults to the platform and the identifier." }, "url": { "type": [ "string", "null" ], "description": "Public address of the store or site.", "maxLength": 2048 }, "plugin_version": { "type": [ "string", "null" ], "description": "Version of the plugin.", "maxLength": 64 }, "platform_version": { "type": [ "string", "null" ], "description": "Version of the platform.", "maxLength": 255 }, "emits": { "type": "array", "maxItems": 100, "items": { "type": "string", "description": "One of the documented event types, or `custom.` with a name of lower-case letters, digits, dots and underscores (up to 64 characters).", "examples": [ "order.paid" ] }, "description": "Event types the plugin is able to send." } }, "required": [ "platform", "external_id" ] }, "IntegrationSourceCurrentUpdateParams": { "type": "object", "title": "Describe own source request", "description": "What a source key may change about its own source.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name." }, "url": { "type": [ "string", "null" ], "description": "Public address.", "maxLength": 2048 }, "plugin_version": { "type": [ "string", "null" ], "description": "Version of the plugin.", "maxLength": 64 }, "platform_version": { "type": [ "string", "null" ], "description": "Version of the platform.", "maxLength": 255 }, "emits": { "type": "array", "maxItems": 100, "items": { "type": "string", "description": "One of the documented event types, or `custom.` with a name of lower-case letters, digits, dots and underscores (up to 64 characters).", "examples": [ "order.paid" ] }, "description": "Replaces the event types the plugin is able to send." } }, "additionalProperties": false }, "IntegrationSourceUpdateParams": { "type": "object", "title": "Update integration source request", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name." }, "url": { "type": [ "string", "null" ], "description": "Public address.", "maxLength": 2048 }, "plugin_version": { "type": [ "string", "null" ], "description": "Version of the plugin.", "maxLength": 64 }, "platform_version": { "type": [ "string", "null" ], "description": "Version of the platform.", "maxLength": 255 }, "emits": { "type": "array", "maxItems": 100, "items": { "type": "string", "description": "One of the documented event types, or `custom.` with a name of lower-case letters, digits, dots and underscores (up to 64 characters).", "examples": [ "order.paid" ] }, "description": "Replaces the event types the plugin is able to send." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`disabled` refuses the source key and the native webhooks until it is set back to `active`." }, "signing_secret": { "type": "string", "minLength": 8, "maxLength": 255, "description": "Replaces the secret native webhooks are verified with. Needed for Shopify, which signs with its own key. Write-only." }, "settings": { "type": "object", "description": "How events of this source are treated.", "properties": { "contact_sync": { "type": "boolean", "description": "Upsert the customer of every event into Contacts. Default `true`." }, "consent_mode": { "type": "string", "enum": [ "implied", "explicit" ], "description": "`implied` (default): transactional automations send unless the event says `consent.transactional: false`. `explicit`: they need `true`." }, "store_all_events": { "type": "boolean", "description": "Report `enabled_events: [\"*\"]`, so that the plugin sends every event (debugging)." } }, "additionalProperties": false } }, "additionalProperties": false }, "AutomationMoney": { "type": "object", "title": "Money", "description": "An amount in the minor unit of its currency, never a float.", "properties": { "amount_minor": { "type": "integer", "description": "Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code." }, "formatted": { "type": "string", "maxLength": 64, "description": "The amount as the shop shows it, for example `AED 125.50`. This is what `{{order.total.formatted}}` prints." } }, "required": [ "amount_minor", "currency" ] }, "AutomationCustomer": { "type": "object", "title": "Customer", "description": "Who the event is about, and whom customer automations message. Unknown fields are kept.", "properties": { "id": { "type": [ "string", "integer", "null" ], "description": "The platform's customer ID." }, "name": { "type": [ "string", "null" ], "description": "Full name. Built from first and last name when omitted.", "maxLength": 255 }, "first_name": { "type": [ "string", "null" ], "description": "First name.", "maxLength": 120 }, "last_name": { "type": [ "string", "null" ], "description": "Last name.", "maxLength": 120 }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164 format. A number in another format is normalised like `phone_raw`.", "maxLength": 40 }, "phone_raw": { "type": [ "string", "null" ], "description": "The number as the customer typed it. Read as a national number of `country` (then of the account's country) when `phone` is not E.164.", "maxLength": 60 }, "email": { "type": [ "string", "null" ], "description": "Email address.", "maxLength": 254 }, "locale": { "type": [ "string", "null" ], "description": "BCP 47 language tag. Selects the language variant of the automation.", "maxLength": 35 }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code.", "maxLength": 2 }, "consent": { "type": [ "object", "null" ], "description": "What the customer agreed to, as the source knows it.", "properties": { "transactional": { "type": [ "boolean", "null" ], "description": "`true`, `false`, or `null` for unknown." }, "marketing": { "type": [ "boolean", "null" ], "description": "`true`, `false`, or `null` for unknown. Marketing automations need `true`." }, "channels": { "type": "object", "description": "Per channel type; wins over the two flags for that channel.", "propertyNames": { "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ] }, "additionalProperties": { "type": "string", "enum": [ "opted_in", "opted_out", "unknown" ] } }, "source": { "type": [ "string", "null" ], "description": "Where the consent came from, for example `checkout_checkbox`.", "maxLength": 120 }, "collected_at": { "type": [ "string", "null" ], "description": "When it was collected (ISO-8601)." } } } } }, "AutomationOrder": { "type": "object", "title": "Order", "description": "The order of an `order.*` event. All fields but `id` are optional; unknown fields are kept.", "properties": { "id": { "type": [ "string", "integer" ], "description": "The platform's order ID." }, "number": { "type": [ "string", "integer", "null" ], "description": "The order number customers see." }, "status": { "type": [ "string", "null" ], "description": "Current status on the platform.", "maxLength": 64 }, "previous_status": { "type": [ "string", "null" ], "description": "Status before the change.", "maxLength": 64 }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 code.", "maxLength": 3 }, "total": { "anyOf": [ { "$ref": "#/components/schemas/AutomationMoney" }, { "type": "null" } ], "description": "Order total." }, "subtotal": { "anyOf": [ { "$ref": "#/components/schemas/AutomationMoney" }, { "type": "null" } ], "description": "Subtotal." }, "shipping_total": { "anyOf": [ { "$ref": "#/components/schemas/AutomationMoney" }, { "type": "null" } ], "description": "Shipping." }, "discount_total": { "anyOf": [ { "$ref": "#/components/schemas/AutomationMoney" }, { "type": "null" } ], "description": "Discounts." }, "items": { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "id": { "type": [ "string", "integer", "null" ], "description": "Product ID." }, "name": { "type": [ "string", "null" ], "description": "Product name.", "maxLength": 500 }, "sku": { "type": [ "string", "null" ], "description": "SKU.", "maxLength": 255 }, "quantity": { "type": [ "number", "null" ], "description": "Quantity." }, "unit_price": { "anyOf": [ { "$ref": "#/components/schemas/AutomationMoney" }, { "type": "null" } ], "description": "Price of one unit." }, "url": { "type": [ "string", "null" ], "description": "Product page." }, "image_url": { "type": [ "string", "null" ], "description": "Product image." } } }, "description": "Line items." }, "items_count": { "type": [ "number", "null" ], "description": "Number of units." }, "items_summary": { "type": [ "string", "null" ], "description": "Line items as one line of text, for example `2 × Mug`.", "maxLength": 2000 }, "payment_method": { "type": [ "string", "null" ], "description": "Payment method code.", "maxLength": 120 }, "payment_method_title": { "type": [ "string", "null" ], "description": "Payment method as the customer sees it.", "maxLength": 255 }, "shipping_method": { "type": [ "string", "null" ], "description": "Shipping method.", "maxLength": 255 }, "tracking": { "type": [ "object", "null" ], "description": "Shipment tracking.", "properties": { "number": { "type": [ "string", "null" ], "description": "Tracking number.", "maxLength": 255 }, "url": { "type": [ "string", "null" ], "description": "Tracking page." }, "carrier": { "type": [ "string", "null" ], "description": "Carrier.", "maxLength": 120 } } }, "status_url": { "type": [ "string", "null" ], "description": "Where the customer can follow the order." }, "note": { "type": [ "string", "null" ], "description": "Note to the customer.", "maxLength": 4000 }, "created_at": { "type": [ "string", "null" ], "description": "When the order was placed (ISO-8601)." } }, "required": [ "id" ] }, "AutomationCart": { "type": "object", "title": "Cart", "description": "The cart of a `cart.abandoned` event.", "properties": { "id": { "type": [ "string", "integer" ], "description": "Stable ID of the cart or checkout. A later event with the same ID replaces the pending reminder; an order carrying it in `data.cart_id` cancels it." }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 code.", "maxLength": 3 }, "total": { "anyOf": [ { "$ref": "#/components/schemas/AutomationMoney" }, { "type": "null" } ], "description": "Cart total." }, "items": { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "id": { "type": [ "string", "integer", "null" ], "description": "Product ID." }, "name": { "type": [ "string", "null" ], "description": "Product name.", "maxLength": 500 }, "sku": { "type": [ "string", "null" ], "description": "SKU.", "maxLength": 255 }, "quantity": { "type": [ "number", "null" ], "description": "Quantity." }, "unit_price": { "anyOf": [ { "$ref": "#/components/schemas/AutomationMoney" }, { "type": "null" } ], "description": "Price of one unit." }, "url": { "type": [ "string", "null" ], "description": "Product page." }, "image_url": { "type": [ "string", "null" ], "description": "Product image." } } }, "description": "Line items." }, "items_count": { "type": [ "number", "null" ], "description": "Number of units." }, "items_summary": { "type": [ "string", "null" ], "description": "Line items as one line of text.", "maxLength": 2000 }, "recovery_url": { "type": [ "string", "null" ], "description": "Link that restores the cart." }, "updated_at": { "type": [ "string", "null" ], "description": "Last cart activity (ISO-8601)." } }, "required": [ "id" ] }, "AutomationEventParams": { "type": "object", "title": "Automation event", "description": "A normalised business event: what happened, not what to send. Carry the block that matches the event family (`order` for `order.*`, `cart` for `cart.abandoned`, …) next to `customer`.", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique per source for one real-world occurrence: the idempotency key of the event. Build it from stable parts (`::::`), never from the time of the send attempt." }, "type": { "type": "string", "description": "One of the documented event types, or `custom.` with a name of lower-case letters, digits, dots and underscores (up to 64 characters).", "examples": [ "order.paid" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When it happened at the source. Delays of automations are measured from this instant. Older than 7 days: stored and ignored (`stale`). More than 10 minutes ahead: `400`." }, "source": { "type": "string", "description": "The integration source the event belongs to (`src_…`). Required with an API key, refused with a source key." }, "test": { "type": "boolean", "description": "A test send from a plugin: automations run without delay and quiet hours, and the event is left out of the statistics." }, "site": { "type": [ "object", "null" ], "description": "The store or site. Falls back to the name and URL of the source.", "properties": { "name": { "type": [ "string", "null" ], "description": "Name.", "maxLength": 255 }, "url": { "type": [ "string", "null" ], "description": "Address." } } }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/AutomationCustomer" }, { "type": "null" } ], "description": "Optional for events addressed to the account owner only." }, "order": { "anyOf": [ { "$ref": "#/components/schemas/AutomationOrder" }, { "type": "null" } ] }, "cart": { "anyOf": [ { "$ref": "#/components/schemas/AutomationCart" }, { "type": "null" } ] }, "form": { "type": [ "object", "null" ], "description": "A form submission.", "properties": { "plugin": { "type": [ "string", "null" ], "description": "Form plugin.", "maxLength": 120 }, "id": { "type": [ "string", "integer", "null" ], "description": "Form ID." }, "name": { "type": [ "string", "null" ], "description": "Form name.", "maxLength": 255 }, "fields": { "type": "object", "description": "Label → value.", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "fields_summary": { "type": [ "string", "null" ], "description": "The fields as text, one per line.", "maxLength": 8000 }, "page_url": { "type": [ "string", "null" ], "description": "Page the form is on." } } }, "appointment": { "type": [ "object", "null" ], "description": "An appointment.", "properties": { "id": { "type": [ "string", "integer" ], "description": "Appointment ID." }, "service": { "type": [ "string", "null" ], "description": "Service.", "maxLength": 255 }, "starts_at": { "type": [ "string", "null" ], "description": "Start (ISO-8601)." }, "ends_at": { "type": [ "string", "null" ], "description": "End (ISO-8601)." }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone of the appointment.", "maxLength": 64 }, "location": { "type": [ "string", "null" ], "description": "Where.", "maxLength": 500 }, "staff": { "type": [ "string", "null" ], "description": "With whom.", "maxLength": 255 }, "manage_url": { "type": [ "string", "null" ], "description": "Link to change or cancel." } }, "required": [ "id" ] }, "otp": { "type": [ "object", "null" ], "description": "A one-time password. The code is encrypted at rest until it was sent, then removed; it never appears in logs or in the console.", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The code." }, "expires_in_seconds": { "type": [ "integer", "null" ], "description": "Validity." }, "purpose": { "type": [ "string", "null" ], "description": "What it is for.", "maxLength": 120 } }, "required": [ "code" ] }, "user": { "type": [ "object", "null" ], "description": "A site account.", "properties": { "id": { "type": [ "string", "integer", "null" ], "description": "User ID." }, "login": { "type": [ "string", "null" ], "description": "Login name.", "maxLength": 255 }, "reset_url": { "type": [ "string", "null" ], "description": "Password reset link. Treated like a one-time password." } } }, "comment": { "type": [ "object", "null" ], "description": "A comment.", "properties": { "id": { "type": [ "string", "integer", "null" ], "description": "Comment ID." }, "post_title": { "type": [ "string", "null" ], "description": "Post title.", "maxLength": 500 }, "post_url": { "type": [ "string", "null" ], "description": "Post address." }, "excerpt": { "type": [ "string", "null" ], "description": "Excerpt.", "maxLength": 2000 } } }, "data": { "type": "object", "description": "Free-form extras, up to 32 KB, available as `{{data.*}}`. `data.admin_recipients` adds recipients to owner automations; `data.cart_id` on an order cancels the reminder of that cart.", "additionalProperties": true } }, "required": [ "id", "type", "occurred_at" ] }, "AutomationEventBatchParams": { "type": "object", "title": "Push event batch request", "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/AutomationEventParams" }, "description": "1 to 100 events, processed in order." } }, "required": [ "events" ] }, "AutomationRun": { "type": "object", "title": "Automation run", "description": "What one automation did with an event.", "properties": { "automation_id": { "type": "string", "description": "The automation, prefixed `aut_`." }, "status": { "type": "string", "enum": [ "scheduled", "sent", "skipped", "cancelled", "failed" ], "description": "`scheduled` (waiting for its delay or quiet hours), `sent`, `skipped`, `cancelled` or `failed`." }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time", "description": "When the message is or was due." }, "message_id": { "type": [ "string", "null" ], "description": "The message that was sent. Its status, events and webhooks are those of any message." }, "skip_reason": { "type": [ "string", "null" ], "description": "Why the run was skipped: `no_recipient`, `consent_missing`, `unsubscribed`, `recipient_rate_limited`, `empty_message`, `source_disabled` or `automation_disabled`." } }, "required": [ "automation_id", "status", "scheduled_for", "message_id", "skip_reason" ], "additionalProperties": false }, "AutomationEvent": { "type": "object", "title": "Automation event receipt", "description": "The receipt of one pushed event.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `aev_`.", "examples": [ "aev_3kL9pQ2wE5rT8yU1iO4a" ] }, "object": { "type": "string", "const": "automation_event", "description": "Always `automation_event`." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "Mode of the source." }, "source_id": { "type": "string", "description": "The integration source." }, "event_id": { "type": "string", "description": "The `id` the event was pushed with." }, "type": { "type": "string", "description": "Event type." }, "status": { "type": "string", "enum": [ "accepted", "ignored", "duplicate" ], "description": "`accepted`: at least one automation will run or is scheduled. `ignored`: see `reason`. `duplicate`: the `id` was seen before; this is the first receipt." }, "reason": { "type": [ "string", "null" ], "enum": [ "event_not_enabled", "no_automation_matched", "no_recipient", "consent_missing", "stale", "source_disabled", null ], "description": "Why an event was ignored." }, "automations_matched": { "type": "integer", "description": "Enabled automations whose conditions matched." }, "received_at": { "type": "string", "format": "date-time", "description": "When the event was received." }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRun" }, "description": "One entry per run. Only on `GET /v1/automation_events/{id}`." } }, "required": [ "id", "object", "mode", "source_id", "event_id", "type", "status", "reason", "automations_matched", "received_at" ], "additionalProperties": false, "examples": [ { "id": "aev_3kL9pQ2wE5rT8yU1iO4a", "object": "automation_event", "mode": "live", "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j", "event_id": "woocommerce:order:5012:order.paid:1", "type": "order.paid", "status": "accepted", "reason": null, "automations_matched": 1, "received_at": "2026-10-05T09:30:00.120Z" } ] }, "AutomationEventList": { "type": "object", "title": "Automation event list", "description": "A page of receipts, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationEvent" }, "description": "The receipts." }, "has_more": { "type": "boolean", "description": "Whether more objects follow." }, "next_cursor": { "type": [ "string", "null" ], "description": "ID of the last object while `has_more` is `true`, otherwise `null`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "AutomationEventBatch": { "type": "object", "title": "Event batch result", "description": "One result per event, in request order.", "properties": { "object": { "type": "string", "const": "batch", "description": "Always `batch`." }, "data": { "type": "array", "description": "Per-item results.", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Position of the event in the request." }, "status": { "type": "integer", "description": "HTTP status of this item: `202` accepted or ignored, `200` duplicate, `4xx` refused." }, "event": { "$ref": "#/components/schemas/AutomationEvent" }, "error": { "$ref": "#/components/schemas/ErrorBody" } }, "required": [ "index", "status" ], "additionalProperties": false } }, "accepted": { "type": "integer", "description": "Items with a receipt (new or duplicate)." }, "rejected": { "type": "integer", "description": "Items that were refused." } }, "required": [ "object", "data", "accepted", "rejected" ], "additionalProperties": false }, "IngestAck": { "type": "object", "title": "Webhook acknowledgement", "properties": { "received": { "type": "boolean", "const": true, "description": "Always `true`." } }, "required": [ "received" ], "additionalProperties": false }, "EventList": { "type": "object", "title": "Event list", "description": "A page of events, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "description": "The events, exactly as webhooks deliver them." }, "has_more": { "type": "boolean", "description": "Whether more objects follow." }, "next_cursor": { "type": [ "string", "null" ], "description": "ID of the last object while `has_more` is `true`, otherwise `null`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "TestInboundMessageParams": { "type": "object", "title": "Simulate inbound message request", "properties": { "channel": { "type": "string", "description": "A sandbox channel (`ch_test_`) or a channel created in test mode." }, "from": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The sender: an E.164 phone number for WhatsApp and SMS, a chat or user ID elsewhere." }, "type": { "type": "string", "const": "text", "description": "Only `text` can be simulated." }, "text": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Message text." } }, "required": [ "body" ], "additionalProperties": false }, "sender": { "type": "object", "description": "Profile to report as the sender.", "properties": { "name": { "type": "string", "maxLength": 255 }, "username": { "type": "string", "maxLength": 255 } }, "additionalProperties": false } }, "required": [ "channel", "from", "text" ], "additionalProperties": false }, "Message": { "type": "object", "title": "Message", "description": "An outbound message you sent, or an inbound message received on one of your channels.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `msg_`.", "examples": [ "msg_2b1Xw9aQ3rT8yU0pL4kZ" ] }, "object": { "type": "string", "const": "message", "description": "Always `message`." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "Mode of the API key that created the message." }, "channel_id": { "type": "string", "description": "Channel the message was sent or received on." }, "channel_type": { "type": "string", "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ], "description": "Type of that channel." }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ], "description": "`outbound` for messages you send, `inbound` for messages you receive." }, "to": { "type": "string", "description": "Recipient identifier. For inbound messages, the identifier of your channel." }, "from": { "type": "string", "description": "Sender identifier. For outbound messages, the identifier of your channel." }, "type": { "type": "string", "description": "Content type. One of the common types (`text`, `attachments`, `template`, `button`, `list`, `cta_url`, `location`, `contacts`, `poll`) or a channel-specific type listed in the channel `capabilities`." }, "content": { "type": "object", "description": "The content, under a single key equal to `type`.", "properties": { "text": { "$ref": "#/components/schemas/TextContent" }, "attachments": { "$ref": "#/components/schemas/AttachmentsContent" }, "template": { "$ref": "#/components/schemas/TemplateContent" }, "button": { "$ref": "#/components/schemas/ButtonContent" }, "list": { "$ref": "#/components/schemas/ListContent" }, "cta_url": { "$ref": "#/components/schemas/CtaUrlContent" }, "location": { "$ref": "#/components/schemas/LocationContent" }, "contacts": { "$ref": "#/components/schemas/ContactsContent" }, "poll": { "$ref": "#/components/schemas/PollContent" } }, "additionalProperties": true }, "status": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "read", "failed", "received" ], "description": "Delivery status. Outbound: `queued`, `sending`, `sent`, `delivered`, `read` or `failed`. Inbound: `received`." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/MessageError" }, { "type": "null" } ], "description": "Why the message failed. `null` unless `status` is `failed`." }, "reference": { "type": [ "string", "null" ], "maxLength": 255, "description": "Your own identifier, as supplied when sending." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs supplied when sending. Empty object if none." }, "billing": { "$ref": "#/components/schemas/MessageBilling" }, "sender": { "anyOf": [ { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Display name the sender has on the channel (the WhatsApp profile name, the Telegram first and last name)." }, "username": { "type": [ "string", "null" ], "description": "Handle on the channel, where the channel has one (Telegram, Instagram)." } }, "required": [ "name", "username" ], "additionalProperties": false }, { "type": "null" } ], "description": "Inbound messages: what the channel reported about the sender. `null` on outbound messages and when the channel reported nothing." }, "contact_id": { "type": [ "string", "null" ], "description": "Inbound messages: the contact that had the sender's identifier when the message arrived (`ct_…`), or `null` when there is none. Always `null` on outbound messages." }, "created_at": { "type": "string", "format": "date-time", "description": "When the message was accepted or received." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the message last changed: usually its latest status change. Filter on it with `updated_after`." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the provider accepted the message." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the message reached the recipient device." }, "read_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the recipient read the message, on channels that report it." }, "failed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the message failed." } }, "required": [ "id", "object", "mode", "channel_id", "channel_type", "direction", "to", "from", "type", "content", "status", "error", "reference", "metadata", "billing", "sender", "contact_id", "created_at", "updated_at", "sent_at", "delivered_at", "read_at", "failed_at" ], "additionalProperties": false, "examples": [ { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "delivered", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": "2026-10-05T09:30:02.871Z", "read_at": null, "failed_at": null } ] }, "MessageError": { "type": "object", "title": "Message error", "description": "Failure details of a message with `status: \"failed\"`.", "properties": { "code": { "type": "string", "description": "Failure reason. `provider_error` when the channel provider rejected or could not deliver the message.", "examples": [ "provider_error" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "provider_code": { "type": [ "string", "null" ], "description": "Error code returned by the channel provider. `null` when the provider gave none." } }, "required": [ "code", "message", "provider_code" ], "additionalProperties": false }, "MessageBilling": { "type": "object", "title": "Message billing", "description": "How the message was paid for.", "properties": { "source": { "type": "string", "enum": [ "package", "wallet", "none" ], "description": "`package`: one package credit was consumed. `wallet`: `amount_micros` was debited from the wallet. `none`: not billed (test mode and inbound messages)." }, "amount_micros": { "type": "integer", "description": "Amount debited from the wallet in micro-USD. `0` unless `source` is `wallet`." }, "package_grant_id": { "type": [ "string", "null" ], "description": "Package the credit came from, when `source` is `package`." }, "refunded": { "type": "boolean", "description": "Whether the charge was returned because the message failed." } }, "required": [ "source", "amount_micros", "package_grant_id", "refunded" ], "additionalProperties": false }, "TextContent": { "type": "object", "title": "Text", "description": "Plain text. Supported on every channel.", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Message text, 1 to 4096 characters." }, "preview_url": { "type": "boolean", "description": "Ask the channel to render a preview for the first URL in `body`, where the channel supports it." } }, "required": [ "body" ], "examples": [ { "body": "Your code is 482910" } ] }, "Attachment": { "type": "object", "title": "Attachment", "description": "One media item.", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "audio", "voice", "sticker" ], "description": "Kind of media." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Publicly reachable HTTPS URL of the file. It is fetched at send time." }, "caption": { "type": "string", "maxLength": 1024, "description": "Text shown with the media, where the channel supports captions." }, "filename": { "type": "string", "maxLength": 255, "description": "File name shown to the recipient for documents." } }, "required": [ "type", "url" ] }, "AttachmentsContent": { "type": "array", "title": "Attachments", "description": "A media message. The array must contain exactly one item. Supported on every channel except `sms_otp`.", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Attachment" }, "examples": [ [ { "type": "document", "url": "https://example.com/invoices/1042.pdf", "filename": "invoice-1042.pdf", "caption": "Invoice for order #1042" } ] ] }, "TemplateContent": { "type": "object", "title": "Template", "description": "A pre-approved WhatsApp message template. Required to start a conversation outside the 24-hour customer service window.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Template name as approved in WhatsApp Manager." }, "language": { "type": "object", "description": "Template language.", "properties": { "code": { "type": "string", "minLength": 2, "maxLength": 15, "description": "Language or locale code of the approved translation, for example `en` or `en_US`." } }, "required": [ "code" ] }, "components": { "type": "array", "description": "Values for the template variables, in the WhatsApp Cloud API component format. Omit for templates without variables.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "header", "body", "button" ], "description": "Which part of the template the parameters fill." }, "sub_type": { "type": "string", "description": "Button kind, for `button` components (for example `url` or `quick_reply`)." }, "index": { "type": "string", "description": "Zero-based button position, for `button` components." }, "parameters": { "type": "array", "description": "Parameter values in template order.", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "type" ], "additionalProperties": true } } }, "required": [ "name", "language" ], "examples": [ { "name": "order_shipped", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Layla" }, { "type": "text", "text": "#1042" } ] } ] } ] }, "ButtonContent": { "type": "object", "title": "Button", "description": "A message with one to three quick-reply buttons. A tap arrives as an inbound message carrying the button `id`.", "properties": { "header": { "type": "object", "description": "Optional header shown above the body.", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Header kind." }, "text": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Header text, up to 60 characters." } }, "required": [ "type", "text" ] }, "body": { "type": "object", "description": "Main message text.", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Body text." } }, "required": [ "text" ] }, "footer": { "type": "object", "description": "Optional small print below the body.", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Footer text, up to 60 characters." } }, "required": [ "text" ] }, "action": { "type": "object", "description": "The buttons.", "properties": { "buttons": { "type": "array", "minItems": 1, "maxItems": 3, "description": "One to three reply buttons.", "items": { "type": "object", "properties": { "reply": { "type": "object", "description": "A reply button.", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Your identifier for the button. Returned when the recipient taps it." }, "title": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Button label, up to 20 characters." } }, "required": [ "id", "title" ] } }, "required": [ "reply" ] } } }, "required": [ "buttons" ] } }, "required": [ "body", "action" ], "examples": [ { "body": { "text": "Your delivery is scheduled for tomorrow, 10:00-12:00. Does that work?" }, "footer": { "text": "Order #1042" }, "action": { "buttons": [ { "reply": { "id": "confirm", "title": "Confirm" } }, { "reply": { "id": "reschedule", "title": "Reschedule" } } ] } } ] }, "ListContent": { "type": "object", "title": "List", "description": "A WhatsApp list picker: one button that opens a menu of rows grouped into sections.", "properties": { "header": { "type": "object", "description": "Optional header shown above the body.", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Header kind." }, "text": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Header text, up to 60 characters." } }, "required": [ "type", "text" ] }, "body": { "type": "object", "description": "Main message text.", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Body text." } }, "required": [ "text" ] }, "footer": { "type": "object", "description": "Optional small print below the body.", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Footer text, up to 60 characters." } }, "required": [ "text" ] }, "action": { "type": "object", "description": "The menu.", "properties": { "button": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Label of the button that opens the list, up to 20 characters." }, "sections": { "type": "array", "minItems": 1, "description": "Groups of rows.", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 24, "description": "Section heading, up to 24 characters." }, "rows": { "type": "array", "minItems": 1, "description": "Selectable rows.", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Your identifier for the row. Returned when the recipient selects it." }, "title": { "type": "string", "minLength": 1, "maxLength": 24, "description": "Row label, up to 24 characters." }, "description": { "type": "string", "maxLength": 72, "description": "Optional second line, up to 72 characters." } }, "required": [ "id", "title" ] } } }, "required": [ "title", "rows" ] } } }, "required": [ "button", "sections" ] } }, "required": [ "body", "action" ], "examples": [ { "body": { "text": "Pick a delivery window for order #1042." }, "action": { "button": "Choose a slot", "sections": [ { "title": "Tomorrow", "rows": [ { "id": "slot_am", "title": "10:00-12:00", "description": "Morning" }, { "id": "slot_pm", "title": "16:00-18:00", "description": "Afternoon" } ] } ] } } ] }, "CtaUrlContent": { "type": "object", "title": "CTA URL", "description": "A WhatsApp message with a single button that opens a URL.", "properties": { "header": { "type": "object", "description": "Optional header shown above the body.", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Header kind." }, "text": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Header text, up to 60 characters." } }, "required": [ "type", "text" ] }, "body": { "type": "object", "description": "Main message text.", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Body text." } }, "required": [ "text" ] }, "footer": { "type": "object", "description": "Optional small print below the body.", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Footer text, up to 60 characters." } }, "required": [ "text" ] }, "action": { "type": "object", "description": "The link button.", "properties": { "parameters": { "type": "object", "properties": { "display_text": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Button label, up to 20 characters." }, "url": { "type": "string", "format": "uri", "description": "URL opened when the button is tapped." } }, "required": [ "display_text", "url" ] } }, "required": [ "parameters" ] } }, "required": [ "body", "action" ], "examples": [ { "body": { "text": "Your order is on its way." }, "action": { "parameters": { "display_text": "Track order", "url": "https://example.com/track/1042" } } } ] }, "LocationContent": { "type": "object", "title": "Location", "description": "A map pin. Supported on WhatsApp and Telegram.", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude in decimal degrees." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude in decimal degrees." }, "name": { "type": "string", "maxLength": 255, "description": "Name of the place." }, "address": { "type": "string", "maxLength": 1024, "description": "Address of the place." } }, "required": [ "latitude", "longitude", "name", "address" ], "examples": [ { "latitude": 25.197197, "longitude": 55.274376, "name": "Pickup point", "address": "Sheikh Mohammed bin Rashid Blvd, Dubai" } ] }, "ContactsContent": { "type": "array", "title": "Contacts", "description": "One or more contact cards in the provider contact format. Forwarded to the channel without further validation. Supported on WhatsApp and Telegram.", "minItems": 1, "items": { "type": "object", "properties": { "name": { "type": "object", "description": "Contact name.", "properties": { "formatted_name": { "type": "string", "description": "Full display name." }, "first_name": { "type": "string", "description": "Given name." }, "last_name": { "type": "string", "description": "Family name." } }, "required": [ "formatted_name" ], "additionalProperties": true }, "phones": { "type": "array", "description": "Phone numbers.", "items": { "type": "object", "properties": { "phone": { "type": "string", "description": "Phone number in E.164 format." }, "type": { "type": "string", "description": "Label such as `CELL`, `WORK` or `HOME`." } }, "additionalProperties": true } } }, "additionalProperties": true }, "examples": [ [ { "name": { "formatted_name": "Acme Support", "first_name": "Acme", "last_name": "Support" }, "phones": [ { "phone": "+971800123456", "type": "WORK" } ] } ] ] }, "PollContent": { "type": "object", "title": "Poll", "description": "A Telegram poll.", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Poll question, up to 300 characters." }, "options": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Two to ten answer options of up to 100 characters each." } }, "required": [ "question", "options" ], "examples": [ { "question": "Which delivery window suits you?", "options": [ "Morning", "Afternoon", "Evening" ] } ] }, "MessageCreateParams": { "type": "object", "title": "Send message request", "description": "A message to send. Provide `type` and the content object under the key named by `type`.", "properties": { "channel": { "type": "string", "minLength": 1, "maxLength": 64, "description": "ID of the channel to send from. In test mode, a sandbox channel such as `ch_test_whatsapp`.", "examples": [ "ch_7Hq2mN5vB8cX1zL0pK3j" ] }, "to": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Recipient identifier: E.164 phone number for WhatsApp and SMS, chat ID for Telegram, page-scoped user ID for Messenger and Instagram.", "examples": [ "+971501234567" ] }, "type": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Content type. Must be listed in the channel `capabilities`.", "examples": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "poll" ] }, "text": { "$ref": "#/components/schemas/TextContent" }, "attachments": { "$ref": "#/components/schemas/AttachmentsContent" }, "template": { "$ref": "#/components/schemas/TemplateContent" }, "button": { "$ref": "#/components/schemas/ButtonContent" }, "list": { "$ref": "#/components/schemas/ListContent" }, "cta_url": { "$ref": "#/components/schemas/CtaUrlContent" }, "location": { "$ref": "#/components/schemas/LocationContent" }, "contacts": { "$ref": "#/components/schemas/ContactsContent" }, "poll": { "$ref": "#/components/schemas/PollContent" }, "reply_to": { "type": "string", "minLength": 1, "maxLength": 64, "description": "ID of a message on the same channel to quote. A message that does not exist, or that belongs to another channel or mode, fails with `404 resource_missing`." }, "reference": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your own identifier for the message. Returned on the message and usable as a list filter." }, "metadata": { "type": "object", "maxProperties": 20, "propertyNames": { "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 string keys of up to 64 characters with string values of up to 500 characters. Returned on the message and in webhook events." } }, "required": [ "channel", "to", "type" ], "additionalProperties": true }, "MessageBatchParams": { "type": "object", "title": "Batch request", "properties": { "messages": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/MessageCreateParams" }, "description": "One to 100 messages. Each item has the same shape as the body of `POST /v1/messages`." } }, "required": [ "messages" ] }, "MessageBatch": { "type": "object", "title": "Batch result", "description": "Per-item outcome of a batch send.", "properties": { "object": { "type": "string", "const": "batch", "description": "Always `batch`." }, "data": { "type": "array", "description": "One entry per submitted message, in request order.", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Zero-based position of the message in the request." }, "status": { "type": "integer", "description": "HTTP status the message would have received from `POST /v1/messages`." }, "message": { "$ref": "#/components/schemas/Message", "description": "Present when the item was accepted (`status` 202)." }, "error": { "$ref": "#/components/schemas/ErrorBody", "description": "Present when the item was rejected." } }, "required": [ "index", "status" ], "additionalProperties": false } }, "accepted": { "type": "integer", "description": "Number of accepted messages." }, "rejected": { "type": "integer", "description": "Number of rejected messages." } }, "required": [ "object", "data", "accepted", "rejected" ], "additionalProperties": false, "examples": [ { "object": "batch", "data": [ { "index": 0, "status": 202, "message": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "queued", "error": null, "reference": "order-1042", "metadata": {}, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": null, "delivered_at": null, "read_at": null, "failed_at": null } }, { "index": 1, "status": 402, "error": { "type": "billing_error", "code": "insufficient_balance", "message": "No package credits remain and the wallet balance is below the message price.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance" } } ], "accepted": 1, "rejected": 1 } ] }, "MessageStatusEvent": { "type": "object", "title": "Message status event", "description": "One step in the status history of a message.", "properties": { "status": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "read", "failed", "received" ], "description": "Status the message moved to." }, "description": { "type": "string", "description": "Human-readable detail." }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the status change happened." } }, "required": [ "status", "description", "occurred_at" ], "additionalProperties": false }, "MessageList": { "type": "object", "description": "A page of messages, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Page of results." }, "has_more": { "type": "boolean", "description": "Whether more results exist after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `starting_after` to fetch the next page. `null` when `has_more` is `false`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "MessageStatusEventList": { "type": "object", "description": "The full status history of a message, oldest first. Not paginated: `has_more` is always `false`.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageStatusEvent" }, "description": "All results." }, "has_more": { "type": "boolean", "const": false, "description": "Always `false`: the list is returned whole." }, "next_cursor": { "type": "null", "description": "Always `null`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "Channel": { "type": "object", "title": "Channel", "description": "A sender you connected: a WhatsApp Business number, a Telegram bot, an SMS number and so on.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `ch_`. Sandbox channels use `ch_test_`.", "examples": [ "ch_7Hq2mN5vB8cX1zL0pK3j" ] }, "object": { "type": "string", "const": "channel", "description": "Always `channel`." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "`test` for the built-in sandbox channels, `live` for connected channels." }, "type": { "type": "string", "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ], "description": "Channel type." }, "name": { "type": "string", "description": "Display name you chose." }, "identifier": { "type": "string", "description": "Sender identity on the channel: phone number, bot username, sender ID, page ID or account ID. Always `sandbox` for the built-in sandbox channels." }, "status": { "type": "string", "enum": [ "active", "suspended" ], "description": "`suspended` channels cannot send." }, "connection_status": { "type": "string", "enum": [ "pending", "connected", "reconnecting", "disconnected", "blocked" ], "description": "State of the link to the provider. Messages can be sent only while `connected`." }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Message types the channel accepts as `type` when sending." }, "created_at": { "type": "string", "format": "date-time", "description": "When the channel was created." } }, "required": [ "id", "object", "mode", "type", "name", "identifier", "status", "connection_status", "capabilities", "created_at" ], "additionalProperties": false, "examples": [ { "id": "ch_7Hq2mN5vB8cX1zL0pK3j", "object": "channel", "mode": "live", "type": "whatsapp", "name": "Support line", "identifier": "+971800123456", "status": "active", "connection_status": "connected", "capabilities": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "flow", "product", "product_list", "catalog", "carousel", "location_request" ], "created_at": "2026-10-01T08:00:00.000Z" } ] }, "ChannelCreateParams": { "type": "object", "title": "Connect channel request", "properties": { "type": { "type": "string", "enum": [ "whatsapp", "telegram", "sms", "sms_otp" ], "description": "Channel type. Messenger, Instagram and TikTok channels are connected from the console, because they require an interactive authorization with the provider." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name, up to 255 characters." }, "identifier": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Sender identity: E.164 phone number for `whatsapp` and `sms`, sender ID for `sms_otp`. Required for these types and unique per channel type. Not needed for `telegram`: the bot token is verified with Telegram and the bot username becomes the identifier (a value sent here is ignored)." }, "credentials": { "description": "Provider credentials for the channel type. Passed to the delivery layer and never returned by the API.", "anyOf": [ { "$ref": "#/components/schemas/WhatsAppCredentials" }, { "$ref": "#/components/schemas/TelegramCredentials" }, { "$ref": "#/components/schemas/SmsCredentials" }, { "$ref": "#/components/schemas/SmsOtpCredentials" } ] } }, "required": [ "type", "name", "credentials" ] }, "WhatsAppCredentials": { "type": "object", "title": "WhatsApp credentials", "description": "WhatsApp Business Platform (Cloud API) credentials.", "properties": { "wab_account_id": { "type": "string", "description": "WhatsApp Business Account ID." }, "phone_number_id": { "type": "string", "description": "Phone number ID of the sender." }, "access_token": { "type": "string", "description": "Permanent system user access token with `whatsapp_business_messaging` and `whatsapp_business_management` permissions.", "writeOnly": true } }, "required": [ "wab_account_id", "phone_number_id", "access_token" ] }, "TelegramCredentials": { "type": "object", "title": "Telegram credentials", "properties": { "access_token": { "type": "string", "description": "Bot token issued by BotFather.", "writeOnly": true } }, "required": [ "access_token" ] }, "SmsCredentials": { "type": "object", "title": "SMS credentials", "description": "Twilio credentials for the sending number.", "properties": { "account_sid": { "type": "string", "description": "Twilio account SID." }, "phone_number_sid": { "type": "string", "description": "SID of the Twilio phone number." }, "auth_token": { "type": "string", "description": "Twilio auth token.", "writeOnly": true } }, "required": [ "account_sid", "phone_number_sid", "auth_token" ] }, "SmsOtpCredentials": { "type": "object", "title": "SMS OTP credentials", "properties": { "api_key": { "type": "string", "description": "API key of your OTP SMS route.", "writeOnly": true } }, "required": [ "api_key" ] }, "ChannelUpdateParams": { "type": "object", "title": "Update channel request", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New display name." } }, "required": [ "name" ] }, "ChannelList": { "type": "object", "description": "A page of channels, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" }, "description": "Page of results." }, "has_more": { "type": "boolean", "description": "Whether more results exist after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `starting_after` to fetch the next page. `null` when `has_more` is `false`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "Template": { "type": "object", "title": "WhatsApp template", "description": "A message template registered on the WhatsApp Business Account of a channel.", "properties": { "id": { "type": "string", "description": "Template ID assigned by WhatsApp." }, "name": { "type": "string", "description": "Template name. Use it as `template.name` when sending." }, "language": { "type": "string", "description": "Language code. Use it as `template.language.code` when sending." }, "category": { "type": "string", "description": "WhatsApp template category, for example `UTILITY`, `MARKETING` or `AUTHENTICATION`." }, "status": { "type": "string", "description": "Review status at WhatsApp, for example `APPROVED`, `PENDING` or `REJECTED`. Only approved templates can be sent." }, "components": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Template structure as defined in WhatsApp Manager." }, "variables": { "$ref": "#/components/schemas/TemplateVariables" } }, "required": [ "id", "name", "language", "category", "status", "components", "variables" ], "additionalProperties": false, "examples": [ { "id": "1203948571029384", "name": "order_shipped", "language": "en", "category": "UTILITY", "status": "APPROVED", "components": [ { "type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped." }, { "type": "BUTTONS", "buttons": [ { "type": "URL", "text": "Track order", "url": "https://example.com/track/{{1}}" } ] } ], "variables": { "header": [], "body": [ { "key": "1", "example": null }, { "key": "2", "example": null } ], "buttons": [ { "index": 0, "type": "url", "variables": [ { "key": "1", "example": null } ] } ], "count": 3 } } ] }, "TemplateVariable": { "type": "object", "title": "Template variable", "properties": { "key": { "type": "string", "description": "The placeholder as written between the braces: a position (`1`) or, for named parameters, a name." }, "example": { "type": [ "string", "null" ], "description": "The example value the template was submitted with, when WhatsApp reports one." } }, "required": [ "key", "example" ], "additionalProperties": false }, "TemplateVariables": { "type": "object", "title": "Template variables", "description": "What a send has to fill in, read from `components`: one entry per placeholder, in the order the parameters are sent. Lets a form show one labelled field per variable.", "properties": { "header": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" }, "description": "Placeholders of a text header." }, "body": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" }, "description": "Placeholders of the body." }, "buttons": { "type": "array", "description": "Buttons that take a value: dynamic URLs and copy-code buttons.", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Position of the button in the template, from 0: the `index` of the button component when sending." }, "type": { "type": "string", "description": "Button type in lower case, for example `url` or `copy_code`." }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" }, "description": "Values the button takes." } }, "required": [ "index", "type", "variables" ], "additionalProperties": false } }, "count": { "type": "integer", "description": "Total number of values." } }, "required": [ "header", "body", "buttons", "count" ], "additionalProperties": false }, "TemplateList": { "type": "object", "description": "Templates of a WhatsApp channel. Not paginated: `has_more` is always `false`.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" }, "description": "All results." }, "has_more": { "type": "boolean", "const": false, "description": "Always `false`: the list is returned whole." }, "next_cursor": { "type": "null", "description": "Always `null`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "title": "Webhook endpoint", "description": "A URL on your server that receives events.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `we_`." }, "object": { "type": "string", "const": "webhook_endpoint", "description": "Always `webhook_endpoint`." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "Mode of the API key that created the endpoint. The endpoint receives events of this mode only." }, "url": { "type": "string", "format": "uri", "description": "HTTPS URL that receives the events." }, "description": { "type": [ "string", "null" ], "description": "Your note about the endpoint." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "message.sent", "message.delivered", "message.read", "message.failed", "message.received", "channel.connected", "channel.disconnected", "balance.low", "package.exhausted", "package.expiring", "campaign.started", "campaign.paused", "campaign.completed", "campaign.failed", "*" ] }, "description": "Subscribed event types. `[\"*\"]` means all." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`disabled` endpoints receive nothing. An endpoint is disabled automatically after 50 consecutive failed deliveries." }, "filters": { "$ref": "#/components/schemas/WebhookEndpointFilters" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs supplied by whoever created the endpoint, for its own bookkeeping. Empty object if none." }, "source": { "type": [ "string", "null" ], "description": "The tool that owns the endpoint (`zapier`, `n8n`, `make`…), or `null` for an endpoint created by hand. An endpoint with a `source` is removed automatically after 30 days of uninterrupted failures." }, "created_by": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "api_key" ], "description": "A console user or an API key." }, "id": { "type": "string", "description": "ID of that user or key." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "null" } ], "description": "Who created the endpoint. `null` for endpoints older than this field." }, "has_verification_token": { "type": "boolean", "description": "Whether deliveries carry the `OmniMessage-Verification-Token` header. The token itself is never returned." }, "secret": { "type": "string", "description": "Signing secret, prefixed `whsec_`. Returned only when the endpoint is created and when the secret is rolled." }, "created_at": { "type": "string", "format": "date-time", "description": "When the endpoint was created." } }, "required": [ "id", "object", "mode", "url", "description", "events", "status", "filters", "metadata", "source", "created_by", "has_verification_token", "created_at" ], "additionalProperties": false, "examples": [ { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "mode": "live", "url": "https://example.com/hooks/omni", "description": "Production delivery receipts", "events": [ "message.delivered", "message.failed", "message.received" ], "status": "active", "filters": {}, "metadata": {}, "source": null, "created_by": { "type": "api_key", "id": "key_1qW4eR7tY0uI3oP6aS9d" }, "has_verification_token": false, "created_at": "2026-10-02T11:15:00.000Z" } ] }, "WebhookEndpointCreateParams": { "type": "object", "title": "Create webhook endpoint request", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTPS URL. Hosts that resolve to private or loopback addresses are rejected." }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "message.sent", "message.delivered", "message.read", "message.failed", "message.received", "channel.connected", "channel.disconnected", "balance.low", "package.exhausted", "package.expiring", "campaign.started", "campaign.paused", "campaign.completed", "campaign.failed", "*" ] }, "description": "Event types to subscribe to, or `[\"*\"]` for all." }, "description": { "type": "string", "maxLength": 255, "description": "Optional note." }, "filters": { "$ref": "#/components/schemas/WebhookEndpointFilters" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 20, "description": "Up to 20 string values for your own bookkeeping: a Zap ID, a workflow name." }, "source": { "type": [ "string", "null" ], "pattern": "^[a-z][a-z0-9_-]{0,31}$", "description": "Name of the tool that owns the endpoint, as a lower-case slug (`zapier`, `n8n`, `make`). Set it when an integration creates endpoints on behalf of a user: the console groups by it, and abandoned endpoints are cleaned up." }, "verification_token": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "A static token of 16 to 255 printable characters, sent with every delivery in the `OmniMessage-Verification-Token` header. For receivers that cannot verify the HMAC signature. Write-only." } }, "required": [ "url", "events" ] }, "WebhookEndpointFilters": { "type": "object", "title": "Webhook endpoint filters", "description": "Server-side filters. An event is delivered only when it matches every filter that is set; events that do not carry the filtered property (for example `balance.low`) always pass.", "properties": { "channel_id": { "type": "string", "description": "Only events about this channel: messages on it, and its own `channel.*` events." }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ], "description": "Only message events of this direction." } }, "additionalProperties": false }, "WebhookEndpointUpdateParams": { "type": "object", "title": "Update webhook endpoint request", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "New URL." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Replaces the note. `null` clears it." }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "message.sent", "message.delivered", "message.read", "message.failed", "message.received", "channel.connected", "channel.disconnected", "balance.low", "package.exhausted", "package.expiring", "campaign.started", "campaign.paused", "campaign.completed", "campaign.failed", "*" ] }, "description": "Replaces the subscribed event types." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Set `disabled` to pause deliveries, `active` to resume or to re-enable an automatically disabled endpoint." }, "filters": { "$ref": "#/components/schemas/WebhookEndpointFilters" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 20, "description": "Replaces the metadata." }, "verification_token": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Replaces the verification token. `null` removes it." } } }, "WebhookEndpointList": { "type": "object", "description": "A page of webhook endpoints, newest first.", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "description": "Page of results." }, "has_more": { "type": "boolean", "description": "Whether more results exist after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `starting_after` to fetch the next page. `null` when `has_more` is `false`." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "Event": { "type": "object", "title": "Event", "description": "The body of every webhook request.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `evt_`. Stable across retries: use it to deduplicate." }, "object": { "type": "string", "const": "event", "description": "Always `event`." }, "type": { "type": "string", "enum": [ "message.sent", "message.delivered", "message.read", "message.failed", "message.received", "channel.connected", "channel.disconnected", "balance.low", "package.exhausted", "package.expiring", "campaign.started", "campaign.paused", "campaign.completed", "campaign.failed", "webhook.test" ], "description": "Event type." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "Mode the event belongs to." }, "created_at": { "type": "string", "format": "date-time", "description": "When the event occurred." }, "data": { "type": "object", "description": "Event payload.", "properties": { "object": { "description": "The resource the event is about, as it was when the event occurred: a message for `message.*`, a channel for `channel.*`, the balance for `balance.low`, a package for `package.*`, a campaign for `campaign.*`.", "anyOf": [ { "$ref": "#/components/schemas/Message" }, { "$ref": "#/components/schemas/Channel" }, { "$ref": "#/components/schemas/Balance" }, { "$ref": "#/components/schemas/BalancePackage" }, { "$ref": "#/components/schemas/WebhookEndpoint" }, { "$ref": "#/components/schemas/Campaign" } ] } }, "required": [ "object" ], "additionalProperties": false } }, "required": [ "id", "object", "type", "mode", "created_at", "data" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "type": { "enum": [ "message.sent", "message.delivered", "message.read", "message.failed", "message.received" ] } }, "required": [ "type" ] }, "then": { "properties": { "data": { "properties": { "object": { "$ref": "#/components/schemas/Message" } } } } } }, { "if": { "properties": { "type": { "enum": [ "channel.connected", "channel.disconnected" ] } }, "required": [ "type" ] }, "then": { "properties": { "data": { "properties": { "object": { "$ref": "#/components/schemas/Channel" } } } } } }, { "if": { "properties": { "type": { "enum": [ "balance.low" ] } }, "required": [ "type" ] }, "then": { "properties": { "data": { "properties": { "object": { "$ref": "#/components/schemas/Balance" } } } } } }, { "if": { "properties": { "type": { "enum": [ "package.exhausted", "package.expiring" ] } }, "required": [ "type" ] }, "then": { "properties": { "data": { "properties": { "object": { "$ref": "#/components/schemas/BalancePackage" } } } } } }, { "if": { "properties": { "type": { "enum": [ "webhook.test" ] } }, "required": [ "type" ] }, "then": { "properties": { "data": { "properties": { "object": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, { "if": { "properties": { "type": { "enum": [ "campaign.started", "campaign.paused", "campaign.completed", "campaign.failed" ] } }, "required": [ "type" ] }, "then": { "properties": { "data": { "properties": { "object": { "$ref": "#/components/schemas/Campaign" } } } } } } ], "examples": [ { "id": "evt_6hJ9kL2zX5cV8bN1mQ4w", "object": "event", "type": "message.delivered", "mode": "live", "created_at": "2026-10-05T09:30:02.900Z", "data": { "object": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "delivered", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": "2026-10-05T09:30:02.871Z", "read_at": null, "failed_at": null } } } ] }, "Balance": { "type": "object", "title": "Balance", "description": "Prepaid funds of the account: the wallet and the active message packages.", "properties": { "object": { "type": "string", "const": "balance", "description": "Always `balance`." }, "currency": { "type": "string", "const": "USD", "description": "Always `USD`." }, "wallet_micros": { "type": "integer", "description": "Wallet balance in micro-USD (1 USD = 1,000,000)." }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/BalancePackage" }, "description": "Active packages with credits remaining, earliest expiry first." }, "credits_remaining": { "type": "integer", "description": "Sum of `remaining` across `packages`." } }, "required": [ "object", "currency", "wallet_micros", "packages", "credits_remaining" ], "additionalProperties": false, "examples": [ { "object": "balance", "currency": "USD", "wallet_micros": 48250000, "packages": [ { "id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "name": "100K messages", "quota": 100000, "remaining": 81234, "channel_types": null, "expires_at": "2027-10-05T00:00:00.000Z" } ], "credits_remaining": 81234 } ] }, "BalancePackage": { "type": "object", "title": "Package", "description": "A purchased or granted message package.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `grant_`." }, "name": { "type": "string", "description": "Package name." }, "quota": { "type": "integer", "description": "Messages included." }, "remaining": { "type": "integer", "description": "Messages left." }, "channel_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ] }, "description": "Channel types the credits apply to. `null` means every channel type." }, "expires_at": { "type": "string", "format": "date-time", "description": "When unused credits expire." } }, "required": [ "id", "name", "quota", "remaining", "channel_types", "expires_at" ], "additionalProperties": false }, "Pricing": { "type": "object", "title": "Pricing", "description": "Effective per-message wallet prices for the account.", "properties": { "object": { "type": "string", "const": "pricing", "description": "Always `pricing`." }, "currency": { "type": "string", "const": "USD", "description": "Always `USD`." }, "data": { "type": "array", "description": "One entry per channel type.", "items": { "type": "object", "properties": { "channel_type": { "type": "string", "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ], "description": "Channel type." }, "unit_price_micros": { "type": "integer", "description": "Price of one outbound message in micro-USD." } }, "required": [ "channel_type", "unit_price_micros" ], "additionalProperties": false } } }, "required": [ "object", "currency", "data" ], "additionalProperties": false, "examples": [ { "object": "pricing", "currency": "USD", "data": [ { "channel_type": "whatsapp", "unit_price_micros": 1000 }, { "channel_type": "telegram", "unit_price_micros": 300 }, { "channel_type": "sms", "unit_price_micros": 500 }, { "channel_type": "sms_otp", "unit_price_micros": 500 }, { "channel_type": "messenger", "unit_price_micros": 500 }, { "channel_type": "instagram", "unit_price_micros": 500 }, { "channel_type": "tiktok", "unit_price_micros": 500 } ] } ] }, "Usage": { "type": "object", "title": "Usage", "description": "Outbound message volume and spend for a date range.", "properties": { "object": { "type": "string", "const": "usage", "description": "Always `usage`." }, "from": { "type": "string", "format": "date", "description": "First day of the range (UTC, inclusive)." }, "to": { "type": "string", "format": "date", "description": "Last day of the range (UTC, inclusive)." }, "group_by": { "type": "string", "enum": [ "day", "channel_type" ], "description": "The grouping that was applied." }, "data": { "type": "array", "description": "Usage rows.", "items": { "type": "object", "properties": { "period": { "type": [ "string", "null" ], "format": "date", "description": "UTC day the row covers. `null` when `group_by` is `channel_type`. Days and channel types without usage have no row." }, "channel_type": { "type": "string", "enum": [ "whatsapp", "telegram", "sms", "sms_otp", "messenger", "instagram", "tiktok" ], "description": "Channel type the row covers." }, "messages": { "type": "integer", "description": "Outbound messages accepted." }, "package_credits": { "type": "integer", "description": "Messages paid with package credits." }, "wallet_micros": { "type": "integer", "description": "Amount debited from the wallet, in micro-USD." }, "failed": { "type": "integer", "description": "Messages that ended `failed`." }, "refunded_micros": { "type": "integer", "description": "Part of `wallet_micros` returned to the wallet because the message failed, in micro-USD. Net wallet spend is `wallet_micros - refunded_micros`. Package credits returned for failed messages are already deducted from `package_credits`." } }, "required": [ "period", "channel_type", "messages", "package_credits", "wallet_micros", "failed", "refunded_micros" ], "additionalProperties": false } }, "totals": { "type": "object", "description": "Sums across `data`.", "properties": { "messages": { "type": "integer", "description": "Outbound messages accepted." }, "package_credits": { "type": "integer", "description": "Messages paid with package credits." }, "wallet_micros": { "type": "integer", "description": "Amount debited from the wallet, in micro-USD." }, "failed": { "type": "integer", "description": "Messages that ended `failed`." }, "refunded_micros": { "type": "integer", "description": "Part of `wallet_micros` returned to the wallet because the message failed, in micro-USD. Net wallet spend is `wallet_micros - refunded_micros`. Package credits returned for failed messages are already deducted from `package_credits`." } }, "required": [ "messages", "package_credits", "wallet_micros", "failed", "refunded_micros" ], "additionalProperties": false } }, "required": [ "object", "from", "to", "group_by", "data", "totals" ], "additionalProperties": false, "examples": [ { "object": "usage", "from": "2026-10-01", "to": "2026-10-05", "group_by": "day", "data": [ { "period": "2026-10-01", "channel_type": "whatsapp", "messages": 1200, "package_credits": 1000, "wallet_micros": 200000, "failed": 12, "refunded_micros": 2000 }, { "period": "2026-10-01", "channel_type": "telegram", "messages": 310, "package_credits": 310, "wallet_micros": 0, "failed": 0, "refunded_micros": 0 }, { "period": "2026-10-02", "channel_type": "whatsapp", "messages": 980, "package_credits": 980, "wallet_micros": 0, "failed": 4, "refunded_micros": 0 } ], "totals": { "messages": 2490, "package_credits": 2290, "wallet_micros": 200000, "failed": 16, "refunded_micros": 2000 } } ] }, "Account": { "type": "object", "title": "Account", "description": "The account and API key behind the current request.", "properties": { "object": { "type": "string", "const": "account", "description": "Always `account`." }, "id": { "type": "string", "description": "Unique identifier, prefixed `acc_`." }, "name": { "type": "string", "description": "Account name." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "Mode of the API key used for the request." }, "api_key": { "type": "object", "description": "The API key used for the request. The secret is never returned.", "properties": { "id": { "type": "string", "description": "Unique identifier, prefixed `key_`." }, "name": { "type": "string", "description": "Key name set in the console." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "messages:write", "messages:read", "channels:read", "channels:write", "webhooks:read", "webhooks:write", "billing:read", "contacts:read", "contacts:write", "campaigns:read", "campaigns:write", "integrations:read", "integrations:write", "events:read", "events:write" ] }, "description": "Scopes granted to the key." } }, "required": [ "id", "name", "scopes" ], "additionalProperties": false }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Features of the API this account can use, for example `automation_events`. Clients treat a missing entry (or a missing field) as \"not available\"; new entries appear over time." } }, "required": [ "object", "id", "name", "mode", "api_key", "capabilities" ], "additionalProperties": false, "examples": [ { "object": "account", "id": "acc_8nM3bV6cX9zL2kJ5hG1f", "name": "Acme Logistics", "mode": "live", "api_key": { "id": "key_1qW4eR7tY0uI3oP6aS9d", "name": "Production backend", "scopes": [ "messages:write", "messages:read", "channels:read" ] }, "capabilities": [ "automation_events", "webhook_filters", "test_inbound", "events_feed" ] } ] }, "Deleted": { "type": "object", "title": "Deleted resource", "description": "Confirmation that a resource was deleted.", "properties": { "id": { "type": "string", "description": "ID of the deleted resource." }, "object": { "type": "string", "enum": [ "channel", "webhook_endpoint", "contact", "contact_list", "integration_source" ], "description": "Type of the deleted resource." }, "deleted": { "type": "boolean", "const": true, "description": "Always `true`." } }, "required": [ "id", "object", "deleted" ], "additionalProperties": false }, "ErrorBody": { "type": "object", "title": "Error", "description": "Details of a failed request.", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "permission_error", "not_found_error", "conflict_error", "channel_error", "rate_limit_error", "api_error" ], "description": "Error category. Maps one-to-one to the HTTP status class of the response." }, "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on `message`.", "examples": [ "parameter_missing" ] }, "message": { "type": "string", "description": "Human-readable explanation. May change; do not parse." }, "param": { "type": "string", "description": "Path of the request field the error relates to, for example `text.body`." }, "details": { "type": "array", "description": "Individual validation failures, when there are several.", "items": { "type": "object", "properties": { "param": { "type": "string", "description": "Field path." }, "code": { "type": "string", "description": "Validation failure code, for example `missing_field` or `invalid`." }, "message": { "type": "string", "description": "Explanation." } }, "required": [ "param", "code", "message" ], "additionalProperties": false } }, "request_id": { "type": "string", "description": "ID of the request, also sent as `X-Request-Id`. Quote it when contacting support." }, "doc_url": { "type": "string", "format": "uri", "description": "Link to the documentation for `code`." } }, "required": [ "type", "code", "message", "request_id", "doc_url" ], "additionalProperties": false }, "Error": { "type": "object", "title": "Error response", "description": "Body of every non-2xx response.", "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } }, "required": [ "error" ], "additionalProperties": false, "examples": [ { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "text.body is required.", "param": "text.body", "details": [ { "param": "text.body", "code": "missing_field", "message": "Required" } ], "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#parameter_missing" } } ] } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.", "schema": { "type": "string", "maxLength": 255 }, "example": "6f1c2a0e-3b7d-4c59-9f0a-2d8e5b1c7a43" }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "StartingAfter": { "name": "starting_after", "in": "query", "required": false, "description": "Cursor for the next page: the `next_cursor` of the previous response (the ID of its last object).", "schema": { "type": "string" } }, "MessageId": { "name": "id", "in": "path", "required": true, "description": "Message ID.", "schema": { "type": "string" }, "example": "msg_2b1Xw9aQ3rT8yU0pL4kZ" }, "ChannelId": { "name": "id", "in": "path", "required": true, "description": "Channel ID.", "schema": { "type": "string" }, "example": "ch_7Hq2mN5vB8cX1zL0pK3j" }, "WebhookEndpointId": { "name": "id", "in": "path", "required": true, "description": "Webhook endpoint ID.", "schema": { "type": "string" }, "example": "we_3kL9pQ2wE5rT8yU1iO4a" }, "ContactId": { "name": "id", "in": "path", "required": true, "description": "Contact ID.", "schema": { "type": "string" }, "example": "ct_8Jk3mP6qR9sT2vW5xY1z" }, "ContactListId": { "name": "id", "in": "path", "required": true, "description": "Contact list ID.", "schema": { "type": "string" }, "example": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "SegmentId": { "name": "id", "in": "path", "required": true, "description": "Segment ID.", "schema": { "type": "string" }, "example": "seg_1Ae4gI7kM0oR3tV6xB9d" }, "CampaignId": { "name": "id", "in": "path", "required": true, "description": "Campaign ID.", "schema": { "type": "string" }, "example": "cmp_5Cf8hK1mP4rT7vY0aD3g" }, "IntegrationSourceId": { "name": "id", "in": "path", "required": true, "description": "Integration source ID.", "schema": { "type": "string" }, "example": "src_9Kd2mQ5vB8cX1zL0pK3j" }, "AutomationEventId": { "name": "id", "in": "path", "required": true, "description": "Automation event ID.", "schema": { "type": "string" }, "example": "aev_3kL9pQ2wE5rT8yU1iO4a" }, "FeedEventId": { "name": "id", "in": "path", "required": true, "description": "Event ID.", "schema": { "type": "string" }, "example": "evt_6hJ9kL2zX5cV8bN1mQ4w" } }, "headers": { "X-Request-Id": { "description": "Unique ID of the request, prefixed `req_`. Log it; support uses it to trace a request.", "schema": { "type": "string" }, "example": "req_0aB3cD6eF9gH2iJ5kL8m" }, "RateLimit-Limit": { "description": "Requests allowed per second for this API key on this endpoint. The `RateLimit-*` headers are sent on every response to a request whose API key was accepted; `401` responses and `403` responses with `ip_not_allowed` or `account_suspended` are rejected before the limit is counted and do not carry them.", "schema": { "type": "integer" }, "example": 100 }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" }, "example": 99 }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" }, "example": 1 }, "Retry-After": { "description": "Seconds to wait before retrying. Sent on `429` responses.", "schema": { "type": "integer" }, "example": 1 }, "ETag": { "description": "Version of the configuration of an integration source, as a quoted string. Send it back in `If-None-Match` to get `304` while nothing changed.", "schema": { "type": "string" }, "example": "\"12\"" }, "OmniMessage-Version": { "description": "Date of the latest additive change to the API (`YYYY-MM-DD`). Informational: the contract of `/v1` only ever grows. See the versioning policy.", "schema": { "type": "string" }, "example": "2026-10-06" }, "Idempotent-Replayed": { "description": "Present with the value `true` when the response is a stored replay for a repeated `Idempotency-Key`.", "schema": { "type": "string", "enum": [ "true" ] }, "example": "true" } }, "responses": { "Unauthorized": { "description": "The API key is missing, invalid, revoked or expired.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_missing": { "summary": "api_key_missing", "value": { "error": { "type": "authentication_error", "code": "api_key_missing", "message": "No API key provided. Send it as \"Authorization: Bearer \".", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#api_key_missing" } } }, "api_key_invalid": { "summary": "api_key_invalid", "value": { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key provided is not valid.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#api_key_invalid" } } }, "api_key_revoked": { "summary": "api_key_revoked", "value": { "error": { "type": "authentication_error", "code": "api_key_revoked", "message": "This API key has been revoked.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#api_key_revoked" } } }, "api_key_expired": { "summary": "api_key_expired", "value": { "error": { "type": "authentication_error", "code": "api_key_expired", "message": "This API key expired on 2026-09-30.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#api_key_expired" } } } } } } }, "Forbidden": { "description": "The API key is not allowed to make this request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "scope_missing": { "summary": "scope_missing", "value": { "error": { "type": "permission_error", "code": "scope_missing", "message": "This API key does not have the messages:write scope.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#scope_missing" } } }, "ip_not_allowed": { "summary": "ip_not_allowed", "value": { "error": { "type": "permission_error", "code": "ip_not_allowed", "message": "Requests from 203.0.113.7 are not allowed for this API key.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#ip_not_allowed" } } }, "account_suspended": { "summary": "account_suspended", "value": { "error": { "type": "permission_error", "code": "account_suspended", "message": "This account is suspended.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#account_suspended" } } } } } } }, "NotFound": { "description": "The resource does not exist in this account and mode.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "resource_missing", "value": { "error": { "type": "not_found_error", "code": "resource_missing", "message": "No such message: msg_2b1Xw9aQ3rT8yU0pL4kZ", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#resource_missing" } } } } } } }, "RateLimited": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Retry after 1 second.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#rate_limit_exceeded" } } } } } } }, "ServerError": { "description": "Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected error occurred.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#internal_error" } } } } } } }, "ServiceUnavailable": { "description": "The delivery layer is temporarily unavailable. Any charge was reversed and nothing was created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_unavailable": { "summary": "upstream_unavailable", "value": { "error": { "type": "api_error", "code": "upstream_unavailable", "message": "The delivery service is temporarily unavailable.", "request_id": "req_0aB3cD6eF9gH2iJ5kL8m", "doc_url": "https://omnimessage.co/docs/errors#upstream_unavailable" } } } } } } } }, "examples": { "Message": { "summary": "A delivered outbound message", "value": { "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "delivered", "error": null, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "package", "amount_micros": 0, "package_grant_id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "refunded": false }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": "2026-10-05T09:30:01.210Z", "delivered_at": "2026-10-05T09:30:02.871Z", "read_at": null, "failed_at": null } }, "InboundMessage": { "summary": "An inbound message", "value": { "id": "msg_4fD8sA1gH6jK9lZ3xC5v", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "inbound", "to": "+971800123456", "from": "+971501234567", "type": "text", "content": { "text": { "body": "Where is my order?" } }, "status": "received", "error": null, "reference": null, "metadata": {}, "billing": { "source": "none", "amount_micros": 0, "package_grant_id": null, "refunded": false }, "sender": { "name": "Layla Hassan", "username": null }, "contact_id": "ct_8Jk3mP6qR9sT2vW5xY1z", "created_at": "2026-10-05T09:42:10.000Z", "updated_at": "2026-10-05T09:42:10.000Z", "sent_at": null, "delivered_at": null, "read_at": null, "failed_at": null } }, "FailedMessage": { "summary": "A failed, refunded message", "value": { "id": "msg_9cV4nH7jK2mP5qR8sT1w", "object": "message", "mode": "live", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "direction": "outbound", "to": "+971501234567", "from": "+971800123456", "type": "text", "content": { "text": { "body": "Your code is 482910" } }, "status": "failed", "error": { "code": "provider_error", "message": "Message undeliverable.", "provider_code": "131026" }, "reference": "order-1042", "metadata": { "user_id": "u_17" }, "billing": { "source": "wallet", "amount_micros": 1000, "package_grant_id": null, "refunded": true }, "sender": null, "contact_id": null, "created_at": "2026-10-05T09:30:00.000Z", "updated_at": "2026-10-05T09:30:02.871Z", "sent_at": null, "delivered_at": null, "read_at": null, "failed_at": "2026-10-05T09:30:03.118Z" } }, "Channel": { "summary": "A connected WhatsApp channel", "value": { "id": "ch_7Hq2mN5vB8cX1zL0pK3j", "object": "channel", "mode": "live", "type": "whatsapp", "name": "Support line", "identifier": "+971800123456", "status": "active", "connection_status": "connected", "capabilities": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "flow", "product", "product_list", "catalog", "carousel", "location_request" ], "created_at": "2026-10-01T08:00:00.000Z" } }, "SandboxChannel": { "summary": "A built-in sandbox channel", "value": { "id": "ch_test_whatsapp", "object": "channel", "mode": "test", "type": "whatsapp", "name": "WhatsApp sandbox", "identifier": "sandbox", "status": "active", "connection_status": "connected", "capabilities": [ "text", "attachments", "template", "button", "list", "cta_url", "location", "contacts", "flow", "product", "product_list", "catalog", "carousel", "location_request" ], "created_at": "2026-10-01T08:00:00.000Z" } }, "WebhookEndpoint": { "summary": "A webhook endpoint", "value": { "id": "we_3kL9pQ2wE5rT8yU1iO4a", "object": "webhook_endpoint", "mode": "live", "url": "https://example.com/hooks/omni", "description": "Production delivery receipts", "events": [ "message.delivered", "message.failed", "message.received" ], "status": "active", "filters": {}, "metadata": {}, "source": null, "created_by": { "type": "api_key", "id": "key_1qW4eR7tY0uI3oP6aS9d" }, "has_verification_token": false, "created_at": "2026-10-02T11:15:00.000Z" } }, "Balance": { "summary": "Wallet and packages", "value": { "object": "balance", "currency": "USD", "wallet_micros": 48250000, "packages": [ { "id": "grant_5tGh2Kp9LmQ4xW7nB1cD", "name": "100K messages", "quota": 100000, "remaining": 81234, "channel_types": null, "expires_at": "2027-10-05T00:00:00.000Z" } ], "credits_remaining": 81234 } }, "Contact": { "summary": "A contact", "value": { "id": "ct_8Jk3mP6qR9sT2vW5xY1z", "object": "contact", "first_name": "Layla", "last_name": "Haddad", "phone": "+971501234567", "email": "layla@example.com", "channel_identifiers": { "telegram": "482910375" }, "locale": "ar", "timezone": "Asia/Dubai", "attributes": { "city": "Dubai", "orders": 12 }, "tags": [ "vip", "newsletter" ], "consent": { "whatsapp": { "state": "opted_in", "source": "api", "updated_at": "2026-10-01T08:00:00.000Z" } }, "blocked": false, "blocked_reason": null, "last_messaged_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-05T09:30:00.000Z" } }, "Segment": { "summary": "A segment", "value": { "id": "seg_1Ae4gI7kM0oR3tV6xB9d", "object": "segment", "name": "VIP customers not messaged this month", "description": null, "rules": { "op": "and", "rules": [ { "field": "tags", "operator": "has_any", "value": [ "vip" ] }, { "field": "consent.whatsapp", "operator": "is", "value": "opted_in" }, { "field": "last_messaged_at", "operator": "not_in_last_days", "value": 30 } ] }, "created_at": "2026-10-01T08:00:00.000Z", "updated_at": "2026-10-01T08:00:00.000Z" } }, "Campaign": { "summary": "A campaign that is sending", "value": { "id": "cmp_5Cf8hK1mP4rT7vY0aD3g", "object": "campaign", "mode": "live", "name": "October delivery update", "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j", "channel_type": "whatsapp", "status": "sending", "pause_reason": null, "failure_reason": null, "audience": { "type": "list", "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c" }, "message": { "type": "template", "template": { "name": "order_update", "language": { "code": "en" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "{{first_name}}" }, { "type": "text", "text": "on its way" } ] } ] } }, "merge_fallbacks": { "first_name": "there" }, "require_opt_in": false, "consent_declared": true, "schedule": { "send_at": null, "timezone": "Asia/Dubai", "send_window": { "start": "09:00", "end": "20:00" }, "recipient_timezone": true }, "throttle_per_second": 20, "counters": { "total": 1280, "queued": 640, "sent": 598, "delivered": 571, "read": 302, "failed": 9, "skipped": 33, "cancelled": 0, "skip_reasons": { "unsubscribed": 21, "no_identifier": 12 } }, "cost": { "currency": "USD", "estimated_wallet_micros": 247000, "estimated_credits": 1000, "wallet_micros": 0, "package_credits": 598 }, "created_at": "2026-10-05T09:00:00.000Z", "launched_at": "2026-10-05T09:05:00.000Z", "started_at": "2026-10-05T09:05:02.000Z", "paused_at": null, "completed_at": null, "cancelled_at": null } }, "CampaignRecipient": { "summary": "A delivered recipient", "value": { "id": "184467", "object": "campaign_recipient", "contact_id": "ct_8Jk3mP6qR9sT2vW5xY1z", "to": "+971501234567", "name": "Layla Haddad", "status": "delivered", "skip_reason": null, "message_id": "msg_2b1Xw9aQ3rT8yU0pL4kZ", "error": null, "variables": { "first_name": "Layla" }, "sent_at": "2026-10-05T09:05:03.120Z", "delivered_at": "2026-10-05T09:05:04.871Z", "read_at": null, "failed_at": null } }, "IntegrationSource": { "summary": "A connected WooCommerce store", "value": { "id": "src_9Kd2mQ5vB8cX1zL0pK3j", "object": "integration_source", "mode": "live", "platform": "woocommerce", "external_id": "shop.example.com", "name": "Acme Shop", "url": "https://shop.example.com/", "status": "active", "plugin_version": "0.1.0", "platform_version": "woocommerce/10.1 wordpress/7.0", "emits": [ "order.created", "order.paid", "order.shipped", "cart.abandoned" ], "enabled_events": [ "order.paid", "order.shipped" ], "event_settings": { "cart.abandoned": { "delay_seconds": 3600 } }, "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations", "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}", "ingest_urls": { "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j", "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j" }, "config_version": 12, "last_event_at": "2026-10-05T09:30:00.000Z", "created_at": "2026-10-01T08:00:00.000Z" } }, "AutomationEvent": { "summary": "The receipt of an accepted event", "value": { "id": "aev_3kL9pQ2wE5rT8yU1iO4a", "object": "automation_event", "mode": "live", "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j", "event_id": "woocommerce:order:5012:order.paid:1", "type": "order.paid", "status": "accepted", "reason": null, "automations_matched": 1, "received_at": "2026-10-05T09:30:00.120Z" } } } } }