{ "openapi": "3.1.0", "info": { "title": "Vancely API", "version": "1.0", "description": "REST API for WhatsApp notifications and two-way conversations: connect a number, send messages to people who expect them, and receive inbound messages and delivery receipts by webhook. Authenticate with `Authorization: Bearer wsk_...` (create keys in the dashboard). Every error has the shape `{\"error\": {\"code\", \"message\", \"details\"?}}`. Guides, error codes and webhook signatures: [\/docs](\/docs)." }, "servers": [ { "url": "https:\/\/vancely.bytevancer.com\/api\/v1", "description": "Live" } ], "security": [ { "bearerAuth": [] } ], "paths": { "\/me": { "get": { "operationId": "account.show", "description": "Returns the account behind the API key, its current plan limits and this month's usage.", "summary": "Account, plan and usage", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "subscription": { "type": [ "object", "null" ], "properties": { "status": { "type": "string" }, "ends_at": { "type": "string" } }, "required": [ "status", "ends_at" ] }, "plan": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "max_channels": { "type": "integer" }, "monthly_messages": { "type": "integer" }, "daily_messages_per_channel": { "type": "integer" }, "rate_per_minute": { "type": "integer" } }, "required": [ "name", "max_channels", "monthly_messages", "daily_messages_per_channel", "rate_per_minute" ] }, "usage_this_month": { "type": "object", "properties": { "sent": { "type": "integer" }, "received": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "sent", "received", "failed" ] } }, "required": [ "id", "name", "status", "subscription", "plan", "usage_this_month" ] } }, "required": [ "data" ] } } } } } } }, "\/channels": { "get": { "operationId": "channel.index", "summary": "List channels", "tags": [ "Channels\n\nA channel is one WhatsApp number connected to your account.", "Channel" ], "responses": { "200": { "description": "Array of `ChannelResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ChannelResource" } } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "channel.store", "description": "Starts a WhatsApp session. Then poll `GET \/channels\/{id}\/qr` and scan the QR code with the phone\n(WhatsApp \u2192 Linked devices), or pass `pairing_phone` to get an 8-character pairing code instead.", "summary": "Create a channel", "tags": [ "Channels\n\nA channel is one WhatsApp number connected to your account.", "Channel" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "pairing_phone": { "type": [ "string", "null" ], "description": "The number being connected, to link with a pairing code instead of a QR.", "maxLength": 32 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "`ChannelResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ChannelResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/channels\/{channel}": { "get": { "operationId": "channel.show", "summary": "Get a channel", "tags": [ "Channels\n\nA channel is one WhatsApp number connected to your account.", "Channel" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ChannelResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ChannelResource" } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "channel.destroy", "description": "Logs the number out of WhatsApp and removes the session. Message history is kept.", "summary": "Delete a channel", "tags": [ "Channels\n\nA channel is one WhatsApp number connected to your account.", "Channel" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" } } } }, "\/channels\/{channel}\/qr": { "get": { "operationId": "channel.qr", "description": "While `status` is `qr`, `qr` holds the raw QR payload \u2014 render it as a QR code, or use `qr_svg`.\nIt changes every ~20 seconds, so poll every 3\u20135 seconds until `status` becomes `connected`.", "summary": "Get the QR \/ pairing code", "tags": [ "Channels\n\nA channel is one WhatsApp number connected to your account.", "Channel" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "qr": { "type": [ "string", "null" ] }, "qr_svg": { "type": [ "string", "null" ] }, "pairing_code": { "type": [ "string", "null" ] } }, "required": [ "status", "qr", "qr_svg", "pairing_code" ] } }, "required": [ "data" ] } } } } } } }, "\/channels\/{channel}\/reconnect": { "post": { "operationId": "channel.reconnect", "description": "Restarts the session after a disconnect or logout; a new QR will be issued if needed.", "summary": "Reconnect a channel", "tags": [ "Channels\n\nA channel is one WhatsApp number connected to your account.", "Channel" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "pairing_phone": { "type": [ "string", "null" ], "maxLength": 32 } } } } } }, "responses": { "200": { "description": "`ChannelResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ChannelResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/channels\/{channel}\/resume": { "post": { "operationId": "channel.resume", "description": "Channels are paused automatically when their failure or reply rates suggest a ban risk.\nResume only after fixing the cause (e.g. messaging people who did not opt in).", "summary": "Resume a paused channel", "tags": [ "Channels\n\nA channel is one WhatsApp number connected to your account.", "Channel" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ChannelResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ChannelResource" } }, "required": [ "data" ] } } } } } } }, "\/contacts\/check": { "post": { "operationId": "contact.check", "description": "Returns which numbers have WhatsApp. Max 50 per call.", "summary": "Check numbers", "tags": [ "Contacts", "Contact" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "numbers": { "type": "array", "items": { "type": "string", "maxLength": 32 }, "minItems": 1, "maxItems": 50 } }, "required": [ "channel_id", "numbers" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} } }, "required": [ "data" ] } } } }, "502": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "check_limit_reached" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "channel_not_connected" }, "message": { "type": "string", "const": "This channel is not connected to WhatsApp." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/contacts\/opt-in": { "post": { "operationId": "contact.optIn", "description": "Records that a number agreed to receive messages from a channel (e.g. at checkout),\nso later messages don't need `consent` on every call. Also clears a previous opt-out.", "summary": "Record opt-in", "tags": [ "Contacts", "Contact" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "phone": { "type": "string", "maxLength": 32 }, "source": { "type": "string", "enum": [ "order", "otp", "signup", "support", "manual" ] }, "reference": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "channel_id", "phone", "source" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phone": { "type": "string" }, "source": { "type": "string" }, "opted_out": { "type": "boolean" } }, "required": [ "phone", "source", "opted_out" ] } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "recipient_opted_out" }, "message": { "type": "string", "const": "This recipient replied STOP. Only they can opt back in, by replying START." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/contacts\/opt-out": { "post": { "operationId": "contact.optOut", "description": "Blocks further messages from this channel to the number. Recipients can also opt out by replying STOP.", "summary": "Record opt-out", "tags": [ "Contacts", "Contact" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "phone": { "type": "string", "maxLength": 32 } }, "required": [ "channel_id", "phone" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phone": { "type": [ "string", "object" ] }, "opted_out": { "type": "boolean" } }, "required": [ "phone", "opted_out" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/conversations\/{channel}\/{phone}": { "get": { "operationId": "conversation.show", "summary": "Get a conversation (who is handling a contact)", "tags": [ "Conversations", "Conversation" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "channel_id": { "type": "string" }, "contact": { "type": [ "string", "null", "array", "object" ] }, "mode": { "type": "string", "enum": [ "human", "bot" ] }, "bot_paused_until": { "type": [ "string", "null" ] }, "flow": { "type": [ "string", "null" ] }, "waiting_for_event": { "type": [ "string", "null" ] } }, "required": [ "channel_id", "contact", "mode", "bot_paused_until", "flow", "waiting_for_event" ] } }, "required": [ "data" ] } } } } } } }, "\/conversations\/{channel}\/{phone}\/events": { "post": { "operationId": "conversation.event", "description": "Continues a flow that is waiting at a \"Wait for event\" step with this `event` name (e.g. `payment.confirmed`\nfrom your payment webhook). `data` (\u2264 8 KB) is saved in the step's variable. `409 no_waiting_session` when\nthe contact's flow isn't waiting for this event (it may have timed out).", "summary": "Send an event to a waiting flow", "tags": [ "Conversations", "Conversation" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.-]{0,63}$" }, "data": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "event" ] } } } }, "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "queued" } }, "required": [ "status" ] } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "no_waiting_session" }, "message": { "type": "string", "const": "This contact's flow is not waiting for this event." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/conversations\/{channel}\/{phone}\/handoff": { "post": { "operationId": "conversation.handoff", "description": "Stops the bot for this contact (a running flow ends with `conversation.handoff`). `minutes` (0 = until\nreleased; default 60) is when the bot may answer again.", "summary": "Hand a conversation to a person", "tags": [ "Conversations", "Conversation" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "minutes": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10080 } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "channel_id": { "type": "string" }, "contact": { "type": "string" }, "mode": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "bot_paused_until": { "type": [ "string", "null" ] } }, "required": [ "conversation_id", "channel_id", "contact", "mode", "reason", "bot_paused_until" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/conversations\/{channel}\/{phone}\/release": { "post": { "operationId": "conversation.release", "summary": "Give a conversation back to the bot", "tags": [ "Conversations", "Conversation" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "channel_id": { "type": "string" }, "contact": { "type": "string" }, "mode": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "bot_paused_until": { "type": [ "string", "null" ] } }, "required": [ "conversation_id", "channel_id", "contact", "mode", "reason", "bot_paused_until" ] } }, "required": [ "data" ] } } } } } } }, "\/reminders\/cancel": { "post": { "operationId": "conversation.cancelReminders", "summary": "Cancel reminders by key (e.g. when a booking is cancelled)", "tags": [ "Conversations", "Conversation" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "cancel_key": { "type": "string", "maxLength": 100 } }, "required": [ "cancel_key" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cancelled": { "type": "integer" } }, "required": [ "cancelled" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/reminders\/{reminder}": { "delete": { "operationId": "conversation.destroyReminder", "summary": "Cancel one reminder", "tags": [ "Conversations", "Conversation" ], "parameters": [ { "name": "reminder", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "reminder_not_pending" }, "message": { "type": "string", "const": "This reminder was already sent or cancelled." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/flows": { "get": { "operationId": "flow.index", "summary": "List bot flows", "tags": [ "Flows", "Flow" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "live": { "type": "boolean" }, "active_version": { "type": [ "integer", "null" ] }, "triggers": { "type": "array", "description": "A chat widget's bot trigger sits on its hidden web channel, which never leaves the dashboard.", "items": { "type": "object", "properties": { "type": { "type": "string" }, "channel_id": { "type": [ "string", "null" ] }, "keywords": { "type": [ "array", "null" ], "items": {} }, "match": { "type": "string" } }, "required": [ "type", "channel_id", "keywords", "match" ] } }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "live", "active_version", "triggers", "updated_at" ] } } }, "required": [ "data" ] } } } } } } }, "\/flows\/{flow}": { "get": { "operationId": "flow.show", "summary": "Get a bot flow", "tags": [ "Flows", "Flow" ], "parameters": [ { "name": "flow", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "live": { "type": "boolean" }, "active_version": { "type": [ "integer", "null" ] }, "triggers": { "type": "array", "description": "A chat widget's bot trigger sits on its hidden web channel, which never leaves the dashboard.", "items": { "type": "object", "properties": { "type": { "type": "string" }, "channel_id": { "type": [ "string", "null" ] }, "keywords": { "type": [ "array", "null" ], "items": {} }, "match": { "type": "string" } }, "required": [ "type", "channel_id", "keywords", "match" ] } }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "live", "active_version", "triggers", "updated_at" ] } }, "required": [ "data" ] } } } } } } }, "\/flows\/{flow}\/start": { "post": { "operationId": "flow.start", "description": "Starts a live flow for one contact, e.g. to confirm an order or offer booking slots. This is **not** a reply:\nnormal sending rules apply, including `consent` for someone who never wrote to the number, quotas and\nbroadcast detection (personalise the first message). `variables` (\u2264 30) are available as `{{name}}`.\nAnswers `202` and runs in the background; results arrive as `flow.*` webhooks. One start per contact per\n10 minutes; `409` if the contact is already in a flow or talking to a person.", "summary": "Start a flow for a contact", "tags": [ "Flows", "Flow" ], "parameters": [ { "name": "flow", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "to": { "type": "string", "pattern": "^[1-9]\\d{7,14}$" }, "variables": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 30 }, "consent": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "order", "otp", "signup", "support", "manual" ] }, "reference": { "type": [ "string", "null" ], "maxLength": 255 } } } }, "required": [ "channel_id", "to" ] } } } }, "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "queued" }, "flow_id": { "type": "string" }, "channel_id": { "type": "string" }, "to": { "type": "string" } }, "required": [ "status", "flow_id", "channel_id", "to" ] } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "start_rate_limited" }, "message": { "type": "string", "const": "A flow was started for this contact in the last 10 minutes." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "conversation_busy" }, "message": { "type": "string", "const": "This contact is already in a flow." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "conversation_with_person" }, "message": { "type": "string", "const": "A person is handling this contact. Release the conversation first." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "recipient_opted_out" }, "message": { "type": "string", "const": "This recipient replied STOP." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "flow_not_live" }, "message": { "type": "string", "const": "Publish and turn on the flow first." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/messages": { "post": { "operationId": "message.store", "description": "Queues a message and returns immediately with `status: queued`; delivery updates arrive by webhook\n(`message.sent`, `message.delivered`, `message.read`, `message.failed`).\n\nThis service is for notifications and conversations with people who expect your messages.\nThe first message to a number that has never written to the channel must include `consent.source`.\nBulk broadcasts, link shorteners and (for new numbers) links\/media are refused with a clear error code.", "summary": "Send a message", "tags": [ "Messages", "Message" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SendMessageRequest" } } } }, "responses": { "202": { "description": "`MessageResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "get": { "operationId": "message.index", "summary": "List messages", "tags": [ "Messages", "Message" ], "parameters": [ { "name": "channel_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "direction", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "in", "out", null ] } }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 16 } }, { "name": "phone", "in": "query", "description": "Filter by counterpart number (digits).", "schema": { "type": [ "string", "null" ], "maxLength": 32 } }, { "name": "search", "in": "query", "description": "Search your `reference` or the message id (message text isn't stored).", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated set of `MessageResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/MessageResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/messages\/{message}": { "get": { "operationId": "message.show", "summary": "Get a message", "tags": [ "Messages", "Message" ], "parameters": [ { "name": "message", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`MessageResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } } } } } }, "\/messages\/{message}\/media": { "get": { "operationId": "message.media", "description": "Streams a photo, voice note, video or document a contact sent you. We don't keep message content:\nthe file is deleted a few minutes after its first complete download, or 24 hours after it arrived.\nDownload it when your `message.received` webhook arrives.", "summary": "Download inbound media", "tags": [ "Messages", "Message" ], "parameters": [ { "name": "message", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "text\/html": { "schema": { "type": "string" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "503": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "media_temporarily_unavailable" }, "message": { "type": "string", "const": "The file could not be fetched right now. Try again shortly." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "media_not_available" }, "message": { "type": "string", "const": "This file is no longer available. Media is deleted a few minutes after its first complete download, or 24 hours after it arrived." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/webhooks": { "get": { "operationId": "webhook.index", "summary": "List webhooks", "tags": [ "Webhooks\n\nEvents are POSTed as JSON `{event", " created_at", " data}` with headers `X-Webhook-Event`", " `X-Webhook-Id` and\n`X-Webhook-Signature: t=", "v1=` where v1 = HMAC-SHA256(secret", " \".\").\nRespond 2xx within 10 seconds; failures are retried 8 times over ~3.5 hours.", "Webhook" ], "responses": { "200": { "description": "Array of `WebhookResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookResource" } } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "webhook.store", "description": "The response includes `secret` \u2014 store it; it is not shown again.", "summary": "Create a webhook", "tags": [ "Webhooks\n\nEvents are POSTed as JSON `{event", " created_at", " data}` with headers `X-Webhook-Event`", " `X-Webhook-Id` and\n`X-Webhook-Signature: t=", "v1=` where v1 = HMAC-SHA256(secret", " \".\").\nRespond 2xx within 10 seconds; failures are retried 8 times over ~3.5 hours.", "Webhook" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookRequest" } } } }, "responses": { "201": { "description": "`WebhookResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookResource" } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "webhook_limit_reached" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/webhooks\/{webhook}": { "get": { "operationId": "webhook.show", "summary": "Get a webhook", "tags": [ "Webhooks\n\nEvents are POSTed as JSON `{event", " created_at", " data}` with headers `X-Webhook-Event`", " `X-Webhook-Id` and\n`X-Webhook-Signature: t=", "v1=` where v1 = HMAC-SHA256(secret", " \".\").\nRespond 2xx within 10 seconds; failures are retried 8 times over ~3.5 hours.", "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookResource" } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "webhook.update", "summary": "Update a webhook", "tags": [ "Webhooks\n\nEvents are POSTed as JSON `{event", " created_at", " data}` with headers `X-Webhook-Event`", " `X-Webhook-Id` and\n`X-Webhook-Signature: t=", "v1=` where v1 = HMAC-SHA256(secret", " \".\").\nRespond 2xx within 10 seconds; failures are retried 8 times over ~3.5 hours.", "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookRequest" } } } }, "responses": { "200": { "description": "`WebhookResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "webhook.destroy", "summary": "Delete a webhook", "tags": [ "Webhooks\n\nEvents are POSTed as JSON `{event", " created_at", " data}` with headers `X-Webhook-Event`", " `X-Webhook-Id` and\n`X-Webhook-Signature: t=", "v1=` where v1 = HMAC-SHA256(secret", " \".\").\nRespond 2xx within 10 seconds; failures are retried 8 times over ~3.5 hours.", "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" } } } }, "\/webhooks\/{webhook}\/rotate-secret": { "post": { "operationId": "webhook.rotateSecret", "summary": "Rotate the signing secret", "tags": [ "Webhooks\n\nEvents are POSTed as JSON `{event", " created_at", " data}` with headers `X-Webhook-Event`", " `X-Webhook-Id` and\n`X-Webhook-Signature: t=", "v1=` where v1 = HMAC-SHA256(secret", " \".\").\nRespond 2xx within 10 seconds; failures are retried 8 times over ~3.5 hours.", "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookResource" } }, "required": [ "data" ] } } } } } } }, "\/webhooks\/{webhook}\/test": { "post": { "operationId": "webhook.test", "description": "Delivers a `webhook.test` event to this endpoint.", "summary": "Send a test event", "tags": [ "Webhooks\n\nEvents are POSTed as JSON `{event", " created_at", " data}` with headers `X-Webhook-Event`", " `X-Webhook-Id` and\n`X-Webhook-Signature: t=", "v1=` where v1 = HMAC-SHA256(secret", " \".\").\nRespond 2xx within 10 seconds; failures are retried 8 times over ~3.5 hours.", "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "delivery_id": { "type": "string" } }, "required": [ "delivery_id" ] } }, "required": [ "data" ] } } } } } } }, "\/webhooks\/{webhook}\/deliveries": { "get": { "operationId": "webhook.deliveries", "summary": "List recent deliveries", "tags": [ "Webhooks\n\nEvents are POSTed as JSON `{event", " created_at", " data}` with headers `X-Webhook-Event`", " `X-Webhook-Id` and\n`X-Webhook-Signature: t=", "v1=` where v1 = HMAC-SHA256(secret", " \".\").\nRespond 2xx within 10 seconds; failures are retried 8 times over ~3.5 hours.", "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `WebhookDeliveryResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookDeliveryResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } } } } }, "\/webhooks\/{webhook}\/deliveries\/{delivery}\/retry": { "post": { "operationId": "webhook.redeliver", "summary": "Retry a delivery", "tags": [ "Webhooks\n\nEvents are POSTed as JSON `{event", " created_at", " data}` with headers `X-Webhook-Event`", " `X-Webhook-Id` and\n`X-Webhook-Signature: t=", "v1=` where v1 = HMAC-SHA256(secret", " \".\").\nRespond 2xx within 10 seconds; failures are retried 8 times over ~3.5 hours.", "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "delivery_id": { "type": "string" } }, "required": [ "delivery_id" ] } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "retry_scheduled" }, "message": { "type": "string", "const": "An automatic retry is already scheduled for this delivery." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "webhook_disabled" }, "message": { "type": "string", "const": "Enable the webhook before retrying its deliveries." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } ] } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "API key from the dashboard (API keys page), sent as `Authorization: Bearer wsk_...`.", "scheme": "bearer", "bearerFormat": "wsk_..." } }, "schemas": { "ChannelResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "paused": { "type": "boolean" }, "paused_reason": { "type": [ "string", "null" ] }, "paused_by": { "type": [ "string", "null" ] }, "health": { "type": "object", "properties": { "score": { "type": [ "integer", "null" ] }, "reply_rate": { "type": [ "number", "null" ] }, "fail_rate": { "type": [ "number", "null" ] }, "checked_at": { "type": [ "string", "null" ] } }, "required": [ "score", "reply_rate", "fail_rate", "checked_at" ] }, "warmup_day": { "type": [ "integer", "null" ] }, "connected_at": { "type": [ "string", "null" ], "description": "1-based: day 1 is the connection day" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "provider", "status", "phone", "paused", "paused_reason", "paused_by", "health", "warmup_day", "connected_at", "created_at" ], "title": "ChannelResource" }, "MessageResource": { "type": "array", "items": {}, "title": "MessageResource" }, "SendMessageRequest": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid", "description": "Channel id (uuid) to send from." }, "to": { "type": "string", "description": "Recipient number in international format, e.g. 923001234567.", "pattern": "^[1-9]\\d{7,14}$" }, "type": { "type": "string", "enum": [ "text", "image", "document", "audio", "video", "location" ] }, "text": { "type": [ "string", "null" ], "maxLength": 4096 }, "media_url": { "type": [ "string", "null" ], "format": "uri", "description": "Public https URL of the file for image\/document\/audio\/video.", "maxLength": 2048 }, "caption": { "type": [ "string", "null" ], "maxLength": 1024 }, "filename": { "type": [ "string", "null" ], "maxLength": 255 }, "mimetype": { "type": [ "string", "null" ], "maxLength": 100 }, "latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 }, "location_name": { "type": [ "string", "null" ], "maxLength": 255 }, "consent": { "type": "object", "description": "Required the first time you message a number that has never written to this channel.", "properties": { "source": { "type": "string", "enum": [ "order", "otp", "signup", "support", "manual" ] }, "reference": { "type": [ "string", "null" ], "maxLength": 255 } } }, "reference": { "type": [ "string", "null" ], "description": "Your own id (order number etc.), echoed back in webhooks.", "maxLength": 255 } }, "required": [ "channel_id", "to" ], "title": "SendMessageRequest" }, "WebhookDeliveryResource": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "next_retry_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "event", "status", "attempts", "response_status", "last_error", "next_retry_at", "delivered_at", "created_at" ], "title": "WebhookDeliveryResource" }, "WebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Public https endpoint that will receive POSTed events.", "maxLength": 2048 }, "events": { "type": "array", "description": "Events to subscribe to.", "items": { "type": "string", "enum": [ "message.received", "message.sent", "message.delivered", "message.read", "message.failed", "channel.connected", "channel.disconnected", "channel.logged_out", "channel.paused", "flow.started", "flow.completed", "flow.abandoned", "flow.failed", "flow.event", "conversation.handoff", "conversation.human_replied", "conversation.released", "chat.started", "chat.message", "chat.ended", "chat.continued_on_whatsapp" ] }, "minItems": 1 }, "channel_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Limit to one channel (uuid); omit for all channels." }, "is_active": { "type": "boolean" } }, "required": [ "url", "events" ], "title": "WebhookRequest" }, "WebhookResource": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "channel_id": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": {} }, "is_active": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "disabled_at": { "type": [ "string", "null" ] }, "secret": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "channel_id", "events", "is_active", "consecutive_failures", "disabled_at", "created_at" ], "title": "WebhookResource" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }