{ "openapi": "3.1.0", "info": { "title": "WaDesk API", "version": "v1", "description": "WaDesk REST API. Authenticate with a workspace API key: send it as `Authorization: Bearer `. Generate keys in the dashboard under Developers / API." }, "servers": [ { "url": "http://192.168.1.189:8008/api/v1" } ], "security": [ { "http": [] } ], "paths": { "/me": { "get": { "operationId": "v1.account.me", "description": "data: {\n account: { name, email },\n workspace: { id, name, slug, timezone, currency },\n plan: { id, name, is_free },\n limits: { : int|null }, // null = unlimited\n features: { : bool } // unlocked capabilities\n}", "summary": "GET /api/v1/me \u2014 the current workspace, its plan and numeric limits", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "account": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "email" ] }, "workspace": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "timezone": { "type": "string" }, "currency": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "timezone", "currency" ] }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Free" ] } ] }, "is_free": { "type": "boolean" } }, "required": [ "id", "name", "is_free" ] }, "limits": { "type": "string" }, "features": { "type": "array", "items": {} } }, "required": [ "account", "workspace", "plan", "limits", "features" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Workspace not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/usage": { "get": { "operationId": "v1.account.usage", "description": "data: {\n period: { label, resets_on, days_left },\n messages: { used, limit, unlimited, remaining, percent },\n credits: int, // owner wallet credits\n meters: { : { label, used, limit, unlimited, percent } }\n}", "summary": "GET /api/v1/usage \u2014 message sends used and remaining this billing month", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "label": { "type": "string" }, "resets_on": { "type": "string" }, "days_left": { "type": "string" } }, "required": [ "label", "resets_on", "days_left" ] }, "messages": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "unlimited": { "type": "boolean" }, "remaining": { "type": [ "object", "null" ] }, "percent": { "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "integer", "enum": [ 0 ] } ] } }, "required": [ "used", "limit", "unlimited", "remaining", "percent" ] }, "credits": { "type": "integer" }, "meters": { "type": "string" } }, "required": [ "period", "messages", "credits", "meters" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Workspace not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/auto-replies": { "get": { "operationId": "v1.auto-replies.index", "summary": "GET /api/v1/auto-replies \u2014 list the workspace's auto-replies", "tags": [ "AutoReply" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "list_failed" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Could not list auto-replies." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "v1.auto-replies.store", "summary": "POST /api/v1/auto-replies \u2014 create an auto-reply", "tags": [ "AutoReply" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreAutoReplyRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/auto-replies/{id}": { "get": { "operationId": "v1.auto-replies.show", "summary": "GET /api/v1/auto-replies/{id} \u2014 one auto-reply", "tags": [ "AutoReply" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Auto-reply not found." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } }, "put": { "operationId": "v1.auto-replies.update", "summary": "PUT /api/v1/auto-replies/{id} \u2014 update an auto-reply", "tags": [ "AutoReply" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutoReplyRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "delete": { "operationId": "v1.auto-replies.destroy", "summary": "DELETE /api/v1/auto-replies/{id} \u2014 delete an auto-reply", "tags": [ "AutoReply" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Auto-reply not found." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/broadcasts": { "post": { "operationId": "v1.broadcasts.store", "summary": "POST /api/v1/broadcasts \u2014 send a template to a list / group", "tags": [ "Broadcast" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreBroadcastRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "broadcast_ids": { "anyOf": [ { "type": "string" }, { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } ] }, "devices_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 1 ] } ] } }, "required": [ "broadcast_ids", "devices_count" ] } }, "required": [ "data", "meta" ] }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "broadcast_ids": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "devices_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 1 ] } ] } }, "required": [ "broadcast_ids", "devices_count" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "get": { "operationId": "v1.broadcasts.index", "summary": "GET /api/v1/broadcasts \u2014 recent broadcasts for the workspace", "tags": [ "Broadcast" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] } } } } } } }, "/broadcasts/{id}": { "get": { "operationId": "v1.broadcasts.show", "summary": "GET /api/v1/broadcasts/{id} \u2014 one broadcast with status counts", "tags": [ "Broadcast" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Broadcast not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/broadcasts/{id}/recipients": { "get": { "operationId": "v1.broadcasts.recipients", "summary": "GET /api/v1/broadcasts/{id}/recipients \u2014 per-recipient delivery", "tags": [ "Broadcast" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "integer" }, "status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "pending" ] } ] }, "error": { "type": "string" }, "wa_message_id": { "type": "string" }, "sent_at": { "type": "string" }, "delivered_at": { "type": "string" }, "read_at": { "type": "string" } }, "required": [ "contact_id", "status", "error", "wa_message_id", "sent_at", "delivered_at", "read_at" ] } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "stats": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "count", "stats" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Broadcast not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/broadcasts/{id}/stop": { "post": { "operationId": "v1.broadcasts.stop", "summary": "POST /api/v1/broadcasts/{id}/stop \u2014 cancel a scheduled / in-flight broadcast", "tags": [ "Broadcast" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_stoppable" }, "message": { "type": "string", "const": "Only scheduled or in-flight broadcasts can be stopped." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Broadcast not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/campaigns/statistics": { "get": { "operationId": "v1.campaigns.statistics", "summary": "GET /api/v1/campaigns/statistics \u2014 workspace-wide rollup", "tags": [ "Campaign" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "stats_failed" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Statistics could not be fetched." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/campaigns": { "get": { "operationId": "v1.campaigns.index", "summary": "GET /api/v1/campaigns \u2014 list the workspace's campaigns", "tags": [ "Campaign" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "list_failed" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Campaigns could not be listed." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "v1.campaigns.store", "description": "Routes through the web WaCampaignsController::store \u2014 the SINGLE real\ndispatch path. `now` campaigns fire immediately; `scheduled`/`recurring`\nare armed for the heartbeat sweeper. (The mobile-app controller only\npersists rows and never dispatches, so we deliberately don't use it.)\nThe public `schedule_type=later` maps to the web vocabulary `scheduled`,\nand recipient phone numbers ride in as `manual_numbers` \u2014 the web path\nmaterialises a workspace Contact for each, so sends are always scoped to\nthe caller's own workspace.", "summary": "POST /api/v1/campaigns \u2014 create a campaign and dispatch it", "tags": [ "Campaign" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCampaignRequest" } } } }, "responses": { "422": { "$ref": "#/components/responses/ValidationException" }, "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "plan_limit" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Campaign plan limit reached." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/campaigns/{id}": { "get": { "operationId": "v1.campaigns.show", "summary": "GET /api/v1/campaigns/{id} \u2014 one campaign with counts + metrics", "tags": [ "Campaign" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "counts": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "metrics": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "counts", "metrics" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Campaign not found." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "v1.campaigns.destroy", "summary": "DELETE /api/v1/campaigns/{id} \u2014 delete a scheduled / failed / completed campaign", "tags": [ "Campaign" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Campaign deleted successfully" ] } ] } }, "required": [ "deleted", "message" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] }, { "type": "string" } ] } } } } } } }, "/campaigns/{id}/stop": { "post": { "operationId": "v1.campaigns.stop", "summary": "POST /api/v1/campaigns/{id}/stop \u2014 stop a running / scheduled campaign", "tags": [ "Campaign" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] }, { "type": "string" } ] } } } } } } }, "/contacts": { "get": { "operationId": "v1.contacts.index", "summary": "GET /api/v1/contacts \u2014 paginated list, optional ?search", "tags": [ "Contact" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "page": { "type": [ "object", "null" ] }, "per_page": { "type": [ "object", "null" ] }, "total": { "type": "integer", "minimum": 0 }, "last_page": { "type": "integer" } }, "required": [ "page", "per_page", "total", "last_page" ] } }, "required": [ "data", "meta" ] } } } } } }, "post": { "operationId": "v1.contacts.store", "summary": "POST /api/v1/contacts \u2014 create a contact", "tags": [ "Contact" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreContactRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/contacts/{id}": { "get": { "operationId": "v1.contacts.show", "summary": "GET /api/v1/contacts/{id} \u2014 read a single contact", "tags": [ "Contact" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Contact not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } }, "put": { "operationId": "v1.contacts.update", "summary": "PUT /api/v1/contacts/{id} \u2014 update a contact (only present fields)", "tags": [ "Contact" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Contact not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "delete": { "operationId": "v1.contacts.destroy", "summary": "DELETE /api/v1/contacts/{id} \u2014 delete a contact", "tags": [ "Contact" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Contact not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/contact-groups": { "get": { "operationId": "v1.contact-groups.index", "summary": "GET /api/v1/contact-groups \u2014 list groups with member counts", "tags": [ "ContactGroup" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] } } } } } }, "post": { "operationId": "v1.contact-groups.store", "summary": "POST /api/v1/contact-groups \u2014 create a group", "tags": [ "ContactGroup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreContactGroupRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/contact-groups/{id}": { "delete": { "operationId": "v1.contact-groups.destroy", "summary": "DELETE /api/v1/contact-groups/{id} \u2014 delete a group + detach it", "tags": [ "ContactGroup" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Contact group not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/deals": { "get": { "operationId": "v1.deals.index", "summary": "GET /api/v1/deals \u2014 paginated, optional pipeline_id / stage_id / status", "tags": [ "Deal" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "operationId": "v1.deals.store", "summary": "POST /api/v1/deals \u2014 create an opportunity", "tags": [ "Deal" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 191 }, "pipeline_id": { "type": [ "integer", "null" ] }, "stage_id": { "type": [ "integer", "null" ] }, "value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 99999999 }, "currency": { "type": [ "string", "null" ], "maxLength": 10 }, "contact_id": { "type": [ "integer", "null" ] }, "owner_user_id": { "type": [ "integer", "null" ] }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "title" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/deals/{id}": { "get": { "operationId": "v1.deals.show", "summary": "GET /api/v1/deals/{id}", "tags": [ "Deal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "operationId": "v1.deals.update", "summary": "PUT /api/v1/deals/{id} \u2014 update fields (incl. stage to advance it)", "tags": [ "Deal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 191 }, "value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 99999999 }, "currency": { "type": [ "string", "null" ], "maxLength": 10 }, "stage_id": { "type": [ "integer", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "owner_user_id": { "type": [ "integer", "null" ] }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time" }, "lost_reason": { "type": [ "string", "null" ], "maxLength": 191 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "delete": { "operationId": "v1.deals.destroy", "summary": "DELETE /api/v1/deals/{id}", "tags": [ "Deal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/devices": { "get": { "operationId": "v1.devices.index", "summary": "GET /api/v1/devices \u2014 list the workspace's WhatsApp devices", "tags": [ "Device" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] } } } } } } }, "/devices/{id}": { "get": { "operationId": "v1.devices.show", "summary": "GET /api/v1/devices/{id} \u2014 one device", "tags": [ "Device" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Device not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/flows": { "get": { "operationId": "v1.flows.index", "summary": "GET /api/v1/flows \u2014 list the workspace's flows", "tags": [ "Flow" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] } } } } } } }, "/flows/{id}": { "get": { "operationId": "v1.flows.show", "summary": "GET /api/v1/flows/{id} \u2014 one flow", "tags": [ "Flow" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Flow not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/flows/{id}/enroll": { "post": { "operationId": "v1.flows.enroll", "summary": "POST /api/v1/flows/{id}/enroll \u2014 enroll a contact (by id or phone) into\nthe flow. Delegates to FlowEnrollmentService::enroll(), which is\nidempotent at the UNIQUE(flow_id, contact_id) constraint and POSTs to\nthe Node flow runtime", "tags": [ "Flow" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollFlowRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "flow_id": { "type": "string" }, "contact_id": { "type": "integer" }, "subscriber_id": { "type": "string" }, "status": { "type": "string" }, "enrolled_at": { "type": "string" } }, "required": [ "flow_id", "contact_id", "subscriber_id", "status", "enrolled_at" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "contact_not_found" }, "message": { "type": "string", "const": "No contact matches that id or phone in this workspace." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Flow not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } ] } } } } } } }, "/flows/{id}/subscribers": { "get": { "operationId": "v1.flows.subscribers", "summary": "GET /api/v1/flows/{id}/subscribers \u2014 list the flow's subscribers and\ntheir state. Mirrors FlowsController::apiSubscribers", "tags": [ "Flow" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "counts": { "type": "object", "properties": { "active": { "type": "integer", "minimum": 0 }, "paused": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "active", "paused", "completed", "failed" ] } }, "required": [ "count", "counts" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Flow not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/messages": { "post": { "operationId": "v1.messages.store", "summary": "POST /api/v1/messages \u2014 send one message (text / location)", "tags": [ "Message" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "get": { "operationId": "v1.messages.index", "summary": "GET /api/v1/messages \u2014 recent message history", "tags": [ "Message" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] } } } } } } }, "/messages/{id}": { "get": { "operationId": "v1.messages.show", "summary": "GET /api/v1/messages/{id} \u2014 delivery status of one message", "tags": [ "Message" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Message not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/scheduled": { "post": { "operationId": "v1.scheduled.store", "summary": "POST /api/v1/scheduled \u2014 schedule a send (template/message + recipients + run_at)", "tags": [ "Scheduled" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreScheduledRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "get": { "operationId": "v1.scheduled.index", "summary": "GET /api/v1/scheduled \u2014 list the workspace's scheduled messages", "tags": [ "Scheduled" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] } } } } } } }, "/scheduled/{id}": { "get": { "operationId": "v1.scheduled.show", "summary": "GET /api/v1/scheduled/{id} \u2014 one scheduled message", "tags": [ "Scheduled" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Scheduled message not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "v1.scheduled.destroy", "summary": "DELETE /api/v1/scheduled/{id} \u2014 cancel a future scheduled message", "tags": [ "Scheduled" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_cancellable" }, "message": { "type": "string", "const": "This schedule is already finished." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Scheduled message not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/templates": { "get": { "operationId": "v1.templates.index", "summary": "GET /api/v1/templates \u2014 list the workspace's templates", "tags": [ "Template" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "list_failed" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Templates could not be listed." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "v1.templates.store", "summary": "POST /api/v1/templates \u2014 create a template", "tags": [ "Template" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreTemplateRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/templates/categories": { "get": { "operationId": "v1.templates.categories", "summary": "GET /api/v1/templates/categories \u2014 the Meta category list", "tags": [ "Template" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } } } } }, "/templates/{id}": { "get": { "operationId": "v1.templates.show", "summary": "GET /api/v1/templates/{id} \u2014 single template detail", "tags": [ "Template" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Template not found." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } }, "put": { "operationId": "v1.templates.update", "summary": "PUT /api/v1/templates/{id} \u2014 update a template", "tags": [ "Template" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "delete": { "operationId": "v1.templates.destroy", "summary": "DELETE /api/v1/templates/{id} \u2014 delete a template", "tags": [ "Template" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Template deleted successfully" ] } ] } }, "required": [ "deleted", "message" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Template not found." ] } ] }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } }, "/webhooks": { "get": { "operationId": "v1.webhooks.index", "summary": "GET /api/v1/webhooks \u2014 list the workspace's registered webhooks", "tags": [ "Webhook" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "available_events": { "type": "array", "items": {} } }, "required": [ "count", "available_events" ] } }, "required": [ "data", "meta" ] } } } } } }, "post": { "operationId": "v1.webhooks.store", "summary": "POST /api/v1/webhooks \u2014 register a new outbound webhook endpoint", "tags": [ "Webhook" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreWebhookRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/webhooks/{id}": { "delete": { "operationId": "v1.webhooks.destroy", "summary": "DELETE /api/v1/webhooks/{id} \u2014 remove a webhook endpoint", "tags": [ "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] }, "meta": { "type": "string" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "Webhook not found." }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ] } } } } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "EnrollFlowRequest": { "type": "object", "description": "Enroll a contact into a flow. Scramble reads these rules to document the\nrequest body. Identify the contact by `contact_id` (a contact already in\nthe workspace) OR by `phone` (the contact is looked up by its E.164\nnumber). Exactly one is required; the controller resolves it to a Contact\nand hands it to FlowEnrollmentService::enroll().", "properties": { "contact_id": { "type": [ "integer", "null" ], "description": "Id of an existing contact in the workspace. Required unless `phone` is given." }, "phone": { "type": [ "string", "null" ], "description": "Contact phone in international format (digits, E.164). Used to look up\nthe contact when `contact_id` is omitted. Required unless `contact_id` is given.", "maxLength": 32 } }, "title": "EnrollFlowRequest" }, "SendMessageRequest": { "type": "object", "description": "Send a single WhatsApp message. Scramble reads these rules to document the\nrequest body. Supports text, media (by URL) and location; template/bulk\nsends use the /templates + /broadcasts endpoints.", "properties": { "to": { "type": "string", "description": "Recipient phone in international format (digits, E.164). Required.", "maxLength": 32 }, "device_id": { "type": [ "integer", "null" ], "description": "Sending device id (optional \u2014 defaults to the workspace's primary)." }, "type": { "type": [ "string", "null" ], "description": "Message type. Defaults to \"text\".", "enum": [ "text", "image", "video", "document", "location" ] }, "text": { "type": [ "string", "null" ], "description": "Text body (required for text; used as caption for media).", "maxLength": 4096 }, "media_url": { "type": [ "string", "null" ], "format": "uri", "description": "Public media URL (for image/video/document types).", "maxLength": 2048 }, "latitude": { "type": [ "number", "null" ], "description": "Location (when type=location).", "minimum": -90, "maximum": 90 }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 } }, "required": [ "to" ], "title": "SendMessageRequest" }, "StoreAutoReplyRequest": { "type": "object", "description": "Create a keyword auto-reply. Scramble reads these rules to document the\nrequest body. Mirrors the input keys the existing\nAutoreplyController::store accepts, exposed under public-facing names. A\n\"custom\" reply carries one or more `replies[]` text variants; a \"flow\"\nreply points at a saved flow_id.", "properties": { "keyword": { "type": "string", "description": "Trigger keyword(s). Comma-separated phrases are allowed. Required.", "maxLength": 255 }, "matching_method": { "type": [ "string", "null" ], "description": "How the inbound message is matched against the keyword. Defaults to exact.", "enum": [ "fuzzy", "exact", "contains" ] }, "fuzzy_similarity": { "type": [ "integer", "null" ], "description": "Fuzzy match threshold 0-100 (only used when matching_method=fuzzy).", "minimum": 0, "maximum": 100 }, "device_id": { "type": "string", "description": "Sending device id. Required." }, "status": { "type": [ "boolean", "null" ], "description": "Whether the rule is active. Defaults to true." }, "reply_type": { "type": [ "string", "null" ], "description": "Reply kind: \"custom\" (text variants) or \"flow\" (a saved flow). Defaults to custom.", "enum": [ "custom", "flow" ] }, "flow_id": { "type": [ "integer", "null" ], "description": "Flow id to run (required when reply_type=flow)." }, "replies": { "type": [ "array", "null" ], "description": "Reply text variants (for reply_type=custom). At least one required for custom.", "items": { "type": "string", "maxLength": 4096 } } }, "required": [ "keyword", "device_id" ], "title": "StoreAutoReplyRequest" }, "StoreBroadcastRequest": { "type": "object", "description": "Create a broadcast \u2014 send one template to a list of contacts and/or a\ncontact group. Scramble reads these rules to document the request body.\n\nMirrors the input keys the existing BroadcastsController::store accepts\n(broadcast_name / template_id / contacts[] / groups[] / device_id /\nschedule_type+send_date+send_time / timezone), exposed under public-facing\nnames. At least one of `recipients` or `group_id` is required; provide\n`schedule_at` to schedule for later, omit it to send now.", "properties": { "name": { "type": "string", "description": "Broadcast label shown in the dashboard. Required.", "maxLength": 255 }, "template_id": { "type": "integer", "description": "Approved WaTemplate id to send to every recipient. Required." }, "group_id": { "type": [ "integer", "null" ], "description": "Contact-group id \u2014 every member is added as a recipient." }, "device_id": { "type": [ "integer", "null" ], "description": "Sending device id (optional \u2014 defaults to the workspace's primary device)." }, "schedule_at": { "type": [ "string", "null" ], "description": "When to send \u2014 ISO 8601 / parseable datetime. Omit to send immediately.", "maxLength": 64 }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone for schedule_at (e.g. Asia/Kolkata). Defaults to UTC.", "maxLength": 64 }, "recipients": { "type": [ "array", "null" ], "description": "Recipient contact ids. Required unless `group_id` is given.", "items": { "type": "integer" } } }, "required": [ "name", "template_id" ], "title": "StoreBroadcastRequest" }, "StoreCampaignRequest": { "type": "object", "description": "Create a campaign \u2014 a multi-recipient send (template, custom message or\nflow) with optional A/B testing. Scramble reads these rules to document the\nrequest body.\n\nMirrors the input keys the existing App\\CampaignController::store accepts\n(campaign_name / device_id / campaign_type / schedule_type / template_id(s) /\nflow_id / custom_message / send_date+send_time / timezone / ab_* / contacts),\nexposed under public-facing names. Recipients are supplied as a list of\nphone numbers in international format.", "properties": { "campaign_name": { "type": "string", "description": "Campaign label shown in the dashboard. Required.", "maxLength": 255 }, "device_id": { "type": "string", "description": "Sending device \u2014 the device's phone number or id. Required." }, "campaign_type": { "type": "string", "description": "What the campaign sends. Required.", "enum": [ "custom", "template", "flow" ] }, "schedule_type": { "type": "string", "description": "When to send: now, later (needs send_date+send_time), or recurring. Required.", "enum": [ "now", "later", "recurring" ] }, "template_id": { "type": [ "integer", "null" ], "description": "WaTemplate id (required for non-A/B template campaigns)." }, "template_id_a": { "type": [ "integer", "null" ], "description": "A/B testing: the two competing WaTemplate ids." }, "template_id_b": { "type": [ "integer", "null" ] }, "flow_id": { "type": [ "integer", "null" ], "description": "Flow id (required for flow campaigns)." }, "custom_message": { "type": [ "string", "null" ], "description": "Free-text message body (required for custom campaigns).", "maxLength": 4096 }, "send_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date to send on (Y-m-d) \u2014 required when schedule_type=later." }, "send_time": { "type": [ "string", "null" ], "description": "Time to send at (HH:MM) \u2014 required when schedule_type=later.", "maxLength": 16 }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone for send_date/send_time. Defaults to UTC.", "maxLength": 64 }, "ab_testing": { "type": [ "string", "null" ], "description": "Enable A/B testing (template campaigns only)." }, "ab_split": { "type": [ "integer", "null" ], "description": "Percentage of recipients sent variant A (10-90). Defaults to 50.", "minimum": 10, "maximum": 90 }, "contacts": { "type": "array", "description": "Recipient phone numbers in international format. At least one required.", "items": { "type": "string", "maxLength": 32 }, "minItems": 1 } }, "required": [ "campaign_name", "device_id", "campaign_type", "schedule_type", "contacts" ], "title": "StoreCampaignRequest" }, "StoreContactGroupRequest": { "type": "object", "description": "Create a contact group in the current workspace. Scramble reads these rules\nto document the request body. Mirrors ContactsController::groupStore.", "properties": { "name": { "type": "string", "description": "Group name. Required.", "maxLength": 191 }, "note": { "type": [ "string", "null" ], "description": "Optional note/description for the group.", "maxLength": 500 }, "color": { "type": [ "string", "null" ], "description": "Optional UI colour (hex or token, e.g. #2563eb).", "maxLength": 32 } }, "required": [ "name" ], "title": "StoreContactGroupRequest" }, "StoreContactRequest": { "type": "object", "description": "Create a contact in the current workspace. Scramble reads these rules to\ndocument the request body. Mirrors the validation in the existing\nContactsController::store.", "properties": { "name": { "type": [ "string", "null" ], "description": "Contact's full display name. Required when first_name is omitted.", "maxLength": 191 }, "first_name": { "type": [ "string", "null" ], "description": "Optional name parts. Combined into `name` when `name` is blank.", "maxLength": 191 }, "middle_name": { "type": [ "string", "null" ], "maxLength": 191 }, "last_name": { "type": [ "string", "null" ], "maxLength": 191 }, "title": { "type": [ "string", "null" ], "description": "Optional salutation/title (e.g. Mr, Dr).", "maxLength": 50 }, "phone": { "type": "string", "description": "Phone number in international format (digits, E.164). Required.", "maxLength": 32 }, "country_code": { "type": [ "string", "null" ], "description": "Country dial code (e.g. +91). Prefixed onto the phone if missing.", "maxLength": 10 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Optional email address.", "maxLength": 191 }, "language": { "type": [ "string", "null" ], "description": "Optional preferred language / locale.", "maxLength": 80 }, "address": { "type": [ "string", "null" ], "description": "Optional postal address.", "maxLength": 1000 }, "note": { "type": [ "string", "null" ], "description": "Optional free-text note attached to the contact.", "maxLength": 2000 }, "attributes": { "type": [ "array", "null" ], "description": "Free-form key/value attributes stored against the contact.", "items": { "type": "string" } }, "is_unsubscribed": { "type": [ "boolean", "null" ], "description": "Whether the contact has opted out of messages. Defaults to false." }, "group_ids": { "type": [ "array", "null" ], "description": "Group ids the contact belongs to. Each must exist.", "items": { "type": "integer" } } }, "required": [ "phone" ], "title": "StoreContactRequest" }, "StoreScheduledRequest": { "type": "object", "description": "Schedule a WhatsApp send for later. Scramble reads these rules to document\nthe request body. Mirrors the input keys the existing\nQueueController::scheduleMessage accepts (name / message / template_id /\nrecipients / send_at / timezone / device_id), exposed under public-facing\nnames. A template OR a message body is required.", "properties": { "name": { "type": "string", "description": "Schedule label. Required.", "maxLength": 255 }, "message": { "type": [ "string", "null" ], "description": "Body text (required unless a template_id is given). Max 4096 chars.", "maxLength": 4096 }, "template_id": { "type": [ "integer", "null" ], "description": "WaTemplate id to send instead of free text (optional)." }, "device_id": { "type": [ "integer", "null" ], "description": "Sending device id (optional \u2014 defaults to the workspace's connected device)." }, "run_at": { "type": "string", "description": "When to send \u2014 ISO 8601 / parseable datetime interpreted in `timezone`. Required.", "maxLength": 64 }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone for run_at (e.g. Asia/Kolkata). Defaults to the workspace timezone.", "maxLength": 64 }, "recipients": { "type": "array", "description": "Recipient phone numbers in international format. At least one required.", "items": { "type": "string", "maxLength": 32 }, "minItems": 1 } }, "required": [ "name", "run_at", "recipients" ], "title": "StoreScheduledRequest" }, "StoreTemplateRequest": { "type": "object", "description": "Create a WhatsApp message template. Scramble reads these rules to document\nthe request body. Mirrors the existing TemplateController::store validation.", "properties": { "template_name": { "type": "string", "description": "Template name. Required.", "maxLength": 191 }, "template_type": { "type": [ "string", "null" ], "description": "Template type. Defaults to \"standard\".", "enum": [ "standard", "carousel", "media", "auth" ] }, "category": { "type": "string", "description": "Category \u2014 Meta numeric id (1/2/3), meta slug, or industry bucket. Required." }, "header": { "type": [ "string", "null" ], "description": "Optional header text (max 255 chars).", "maxLength": 255 }, "template_body": { "type": [ "string", "null" ], "description": "Body text (required for standard templates, max 4096 chars).", "maxLength": 4096 }, "footer": { "type": [ "string", "null" ], "description": "Optional footer text (max 255 chars).", "maxLength": 255 }, "language": { "type": [ "string", "null" ], "description": "Language code (e.g. en_US). Defaults to en_US.", "maxLength": 16 }, "buttons": { "type": [ "string", "null" ], "description": "Buttons \u2014 CTA / quick-reply array (or parallel-array form)." }, "quick_replies": { "type": [ "string", "null" ], "description": "Quick-reply buttons (folded into buttons[])." }, "carousel_data": { "type": [ "string", "null" ], "description": "Carousel cards payload (for carousel templates)." }, "latitude": { "type": [ "number", "null" ], "description": "LOCATION header \u2014 send a map pin. Provide latitude + longitude\n(both required together) with an optional name + address.", "minimum": -90, "maximum": 90 }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 }, "location_name": { "type": [ "string", "null" ], "maxLength": 191 }, "location_address": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "template_name", "category" ], "title": "StoreTemplateRequest" }, "StoreWebhookRequest": { "type": "object", "description": "Register an outbound webhook endpoint for the current workspace. Scramble\nreads these rules to document the request body. Mirrors the validation in\nthe in-app WebhooksController::store.\n\nThe platform POSTs a JSON envelope to the registered `url` whenever a\nsubscribed event fires. When a signing `secret` is configured the request\ncarries an `X-WaDesk-Signature` header (HMAC-SHA256 of the body).", "properties": { "url": { "type": "string", "format": "uri", "description": "Public HTTPS endpoint the platform POSTs events to. Required.", "maxLength": 2048 }, "name": { "type": [ "string", "null" ], "description": "Optional friendly label shown in the dashboard.", "maxLength": 191 }, "secret": { "type": [ "string", "null" ], "description": "Optional HMAC signing secret. When set, deliveries carry an\nX-WaDesk-Signature header so receivers can verify authenticity.", "maxLength": 191 }, "active": { "type": [ "boolean", "null" ], "description": "Whether the endpoint is active and should receive events.\nDefaults to true." }, "events": { "type": [ "array", "null" ], "description": "Event names to subscribe to. Omit (or pass [\"*\"]) to receive all.\nSupported events fired by the system:\nmessage_received \u2014 inbound message received\nmessage_sent \u2014 outbound message sent\nmessage_delivered \u2014 outbound message delivered\nmessage_read \u2014 outbound message read\nmessage_failed \u2014 outbound message failed\nbroadcast_created \u2014 broadcast created\nbroadcast_status_updated \u2014 broadcast status changed\nbroadcast_message_status_updated \u2014 per-recipient broadcast status changed\ncampaign_created \u2014 campaign created\ncampaign_status_updated \u2014 campaign status changed\ncampaign_contact_status_updated \u2014 per-contact campaign status changed\ncampaign_contact_clicked \u2014 campaign contact clicked a link\ncampaign_contact_replied \u2014 campaign contact replied\ncontact_opt_in \u2014 contact opted in\ncontact_updated \u2014 contact updated\ndevice_status_updated \u2014 device (number) status changed\n\"*\" \u2014 subscribe to every event", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "url" ], "title": "StoreWebhookRequest" }, "UpdateAutoReplyRequest": { "type": "object", "description": "Update a keyword auto-reply. Scramble reads these rules to document the\nrequest body. Same shape as StoreAutoReplyRequest \u2014 the underlying\nAutoreplyController::update replaces the rule's settings and appends any new\n`replies[]` text variants.", "properties": { "keyword": { "type": "string", "description": "Trigger keyword(s). Comma-separated phrases are allowed. Required.", "maxLength": 255 }, "matching_method": { "type": [ "string", "null" ], "description": "How the inbound message is matched against the keyword. Defaults to exact.", "enum": [ "fuzzy", "exact", "contains" ] }, "fuzzy_similarity": { "type": [ "integer", "null" ], "description": "Fuzzy match threshold 0-100 (only used when matching_method=fuzzy).", "minimum": 0, "maximum": 100 }, "device_id": { "type": "string", "description": "Sending device id. Required." }, "status": { "type": [ "boolean", "null" ], "description": "Whether the rule is active. Defaults to true." }, "reply_type": { "type": [ "string", "null" ], "description": "Reply kind: \"custom\" (text variants) or \"flow\" (a saved flow). Defaults to custom.", "enum": [ "custom", "flow" ] }, "flow_id": { "type": [ "integer", "null" ], "description": "Flow id to run (required when reply_type=flow)." }, "replies": { "type": [ "array", "null" ], "description": "Reply text variants (for reply_type=custom). At least one required for custom.", "items": { "type": "string", "maxLength": 4096 } } }, "required": [ "keyword", "device_id" ], "title": "UpdateAutoReplyRequest" }, "UpdateContactRequest": { "type": "object", "description": "Update an existing contact in the current workspace. Every field is\noptional \u2014 only the keys present in the request body are changed. Scramble\nreads these rules to document the request body.", "properties": { "name": { "type": [ "string", "null" ], "description": "Contact's full display name.", "maxLength": 191 }, "first_name": { "type": [ "string", "null" ], "description": "Optional name parts.", "maxLength": 191 }, "middle_name": { "type": [ "string", "null" ], "maxLength": 191 }, "last_name": { "type": [ "string", "null" ], "maxLength": 191 }, "title": { "type": [ "string", "null" ], "description": "Optional salutation/title (e.g. Mr, Dr).", "maxLength": 50 }, "phone": { "type": [ "string", "null" ], "description": "Phone number in international format (digits, E.164).", "maxLength": 32 }, "country_code": { "type": [ "string", "null" ], "description": "Country dial code (e.g. +91). Prefixed onto the phone if missing.", "maxLength": 10 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email address.", "maxLength": 191 }, "language": { "type": [ "string", "null" ], "description": "Preferred language / locale.", "maxLength": 80 }, "address": { "type": [ "string", "null" ], "description": "Postal address.", "maxLength": 1000 }, "note": { "type": [ "string", "null" ], "description": "Free-text note attached to the contact.", "maxLength": 2000 }, "attributes": { "type": [ "array", "null" ], "description": "Free-form key/value attributes stored against the contact.", "items": { "type": "string" } }, "is_unsubscribed": { "type": [ "boolean", "null" ], "description": "Whether the contact has opted out of messages." }, "group_ids": { "type": [ "array", "null" ], "description": "Group ids the contact belongs to (replaces the existing set).", "items": { "type": "integer" } } }, "title": "UpdateContactRequest" }, "UpdateTemplateRequest": { "type": "object", "description": "Update a WhatsApp message template. Scramble reads these rules to document\nthe request body. Mirrors the existing TemplateController::update validation.", "properties": { "template_name": { "type": "string", "description": "Template name. Required.", "maxLength": 191 }, "template_type": { "type": [ "string", "null" ], "description": "Template type. Defaults to the existing value.", "enum": [ "standard", "carousel", "media", "auth" ] }, "category": { "type": "string", "description": "Category \u2014 Meta numeric id (1/2/3), meta slug, or industry bucket. Required." }, "header": { "type": [ "string", "null" ], "description": "Optional header text (max 255 chars).", "maxLength": 255 }, "template_body": { "type": "string", "description": "Body text. Required (max 4096 chars).", "maxLength": 4096 }, "footer": { "type": [ "string", "null" ], "description": "Optional footer text (max 255 chars).", "maxLength": 255 }, "language": { "type": [ "string", "null" ], "description": "Language code (e.g. en_US). Defaults to the existing value.", "maxLength": 16 }, "buttons": { "type": [ "string", "null" ], "description": "Buttons \u2014 CTA / quick-reply array (or parallel-array form)." }, "quick_replies": { "type": [ "string", "null" ], "description": "Quick-reply buttons (folded into buttons[])." }, "carousel_data": { "type": [ "string", "null" ], "description": "Carousel cards payload (for carousel templates)." }, "latitude": { "type": [ "number", "null" ], "description": "LOCATION header \u2014 send a map pin. Provide latitude + longitude\n(both required together) with an optional name + address.", "minimum": -90, "maximum": 90 }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 }, "location_name": { "type": [ "string", "null" ], "maxLength": 191 }, "location_address": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "template_name", "category", "template_body" ], "title": "UpdateTemplateRequest" } }, "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" ] } } } } } } }