{ "openapi": "3.0.1", "info": { "title": "Integration API v1", "description": "Complete Postman collection for the Integration API v1.\n\n**Base URL:** `{{base_url}}/integration/v1`\n\n## Authentication\nEvery request requires the `X-API-Key` header.\n\n```\nX-API-Key: {{api_key}}\n```\n\n## Credit System\nEvery sent message deducts **1 credit** from your WhatsApp pocket. If the send fails, the credit is automatically refunded.\n\n## Message Types\n| Type | Requires `media_url` | Requires `filename` |\n|---|---|---|\n| `text` | No | No |\n| `image` | ✅ | ✅ |\n| `video` | ✅ | ✅ |\n| `document` | ✅ | ✅ |\n| `audio` | ✅ | ✅ |\n\n## Variables\nConfigure these in your Postman environment:\n- `base_url` — e.g. `https://your-domain.com`\n- `api_key` — your `sk_live_...` key\n- `instance` — your instance ID or name\n- `message_id` — filled automatically by tests\n- `contact_id` — filled automatically by tests\n- `template_id` — filled automatically by tests\n- `workspace_id` — your workspace ID", "version": "1.0.0" }, "tags": [], "paths": { "/integration/v1/ping": { "get": { "summary": "Ping", "deprecated": false, "description": "Quick connectivity check. Returns `pong` with a server timestamp.\n\n**Permission:** Any valid API key\n\n**Response (200)**\n```json\n{\n \"success\": true,\n \"message\": \"pong\",\n \"timestamp\": \"2025-01-15T10:30:00.000000Z\"\n}\n```", "tags": [], "parameters": [ { "name": "Accept", "in": "header", "description": "", "required": false, "example": "application/json", "schema": { "type": "string" } }, { "name": "X-API-Key", "in": "header", "description": "", "required": false, "example": "sk_live_zuQzn0PQWWDYfV4G98rxAlc0P1ptMe9R0st0exIo4cwjVwlw", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "success", "message", "timestamp" ] }, "example": { "success": true, "message": "pong", "timestamp": "2025-01-15T10:30:00.000000Z" } } }, "headers": {} } }, "security": [] } }, "/integration/v1/me": { "get": { "summary": "Get API Key Info (me)", "deprecated": false, "description": "Returns the authenticated user's profile, the API key's permissions, and current pocket balances for both WhatsApp and SMS channels.\n\n**Permission:** Any valid API key\n\n**Response fields:**\n- `user.id` — Account user ID\n- `user.name` — Full name\n- `user.email` — Email address\n- `api_key.name` — Name of this API key\n- `api_key.permissions` — Array of granted permission slugs\n- `api_key.created_at` — ISO 8601 creation timestamp\n- `pockets.whatsapp.balance` — Available WhatsApp credits\n- `pockets.sms.balance` — Available SMS credits", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, "api_key": { "type": "object", "properties": { "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" } }, "required": [ "name", "permissions", "created_at" ] }, "pockets": { "type": "object", "properties": { "whatsapp": { "type": "object", "properties": { "balance": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "balance", "currency" ] }, "sms": { "type": "object", "properties": { "balance": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "balance", "currency" ] } }, "required": [ "whatsapp", "sms" ] } }, "required": [ "user", "api_key", "pockets" ] } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "user": { "id": 93, "name": "Ahmed Almabhouh", "email": "ahmed@example.com" }, "api_key": { "name": "My Integration Key", "permissions": [ "send_message", "read_messages", "manage_contacts" ], "created_at": "2025-01-01T00:00:00.000000Z" }, "pockets": { "whatsapp": { "balance": 250, "currency": "credits" }, "sms": { "balance": 0, "currency": "credits" } } } } } } } }, "security": [] } }, "/integration/v1/messages/send": { "post": { "summary": "Send — With Mentions", "deprecated": false, "description": "Send a group message that @-mentions specific participants.\n\n**Permission:** `send_message`\n\n**Fields:**\n- `mentioned` — Array of JIDs in the format `{phone}@s.whatsapp.net`\n- `mentions_everyone` — Set to `true` to @mention all group members\n\n**Note:** For @everyone mentions, set `mentions_everyone: true` and `content` must contain `@everyone`.", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string" }, "recipient": { "type": "string" }, "message_type": { "type": "string" }, "content": { "type": "string" }, "mentioned": { "type": "array", "items": { "type": "string" } } }, "required": [ "instance", "recipient", "message_type", "content", "mentioned" ] }, "example": { "instance": "{{instance}}", "recipient": "+972GROUPJID@g.us", "message_type": "text", "content": "@972501234567 @972507654321 Please review the attached document.", "mentioned": [ "972501234567@s.whatsapp.net", "972507654321@s.whatsapp.net" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] } }, "/integration/v1/messages/send-bulk": { "post": { "summary": "Send Bulk — Shared Template", "deprecated": false, "description": "Send the same template to multiple recipients, each with their own variable overrides.\n\n**Permission:** `send_message`\n\nThe top-level `template_variables` serve as defaults. Per-message `template_variables` are merged on top — per-message values win on conflict.", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": "{\n \"instance\": \"{{instance}}\",\n \"template_id\": {{template_id}},\n \"template_variables\": {\n \"company\": \"Acme Corp\"\n },\n \"messages\": [\n {\n \"recipient\": \"+972567077653\",\n \"template_variables\": { \"name\": \"Ahmed\" }\n },\n {\n \"recipient\": \"+971501234567\",\n \"template_variables\": { \"name\": \"Sara\" }\n }\n ]\n}" } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] } }, "/integration/v1/messages/send-status": { "post": { "summary": "Send Status — Image Story", "deprecated": false, "description": "Post an image as a WhatsApp Status story.\n\n**Permission:** `send_message`\n\nFor media status types, `content` must be a public HTTPS URL pointing to the media file.", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" }, "caption": { "type": "string" }, "all_contacts": { "type": "boolean" } }, "required": [ "instance", "type", "content", "caption", "all_contacts" ] }, "example": { "instance": "{{instance}}", "type": "image", "content": "https://example.com/banners/summer-sale.jpg", "caption": "Summer sale — up to 50% off!", "all_contacts": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] } }, "/integration/v1/messages/send-location": { "post": { "summary": "Send Location", "deprecated": false, "description": "Send a location pin that opens in WhatsApp Maps.\n\n**Permission:** `send_message`\n\n**Fields:**\n- `instance` ✅\n- `recipient` ✅* or `contact_id` ✅*\n- `latitude` ✅ — Decimal degrees, -90 to 90\n- `longitude` ✅ — Decimal degrees, -180 to 180\n- `name` — Display name for the pin (shown as the location title)\n- `address` — Street address shown below the pin\n- `delay` — Artificial delay in ms\n- `quoted.key.id` — WhatsApp message ID to quote", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string" }, "recipient": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "name": { "type": "string" }, "address": { "type": "string" } }, "required": [ "instance", "recipient", "latitude", "longitude", "name", "address" ] }, "example": { "instance": "{{instance}}", "recipient": "+972567077653", "latitude": 31.7683, "longitude": 35.2137, "name": "Our Head Office", "address": "1 Jaffa Street, Jerusalem" } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "message_id": { "type": "integer" }, "status": { "type": "string" }, "type": { "type": "string" }, "recipient": { "type": "string" }, "queued_at": { "type": "string" }, "instance": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "credits_charged": { "type": "integer" } }, "required": [ "message_id", "status", "type", "recipient", "queued_at", "instance", "credits_charged" ] } }, "required": [ "success", "message", "data" ] }, "example": { "success": true, "message": "Message queued for sending", "data": { "message_id": 12349, "status": "pending", "type": "location", "recipient": "+972567077653", "queued_at": "2025-01-15T10:32:00.000000Z", "instance": { "id": 124, "name": "my-instance" }, "credits_charged": 1 } } } } } }, "security": [] } }, "/integration/v1/messages/send-contact": { "post": { "summary": "Send Contact Card", "deprecated": false, "description": "Send one or more vCard contacts that recipients can save directly to their phone.\n\n**Permission:** `send_message`\n\n**Fields:**\n- `instance` ✅\n- `recipient` ✅* or `contact_id` ✅*\n- `contacts` ✅ — Array of contact objects (at least 1)\n\n**Per-contact object:**\n- `fullName` ✅ — Contact's display name\n- `wuid` ✅ — WhatsApp UID: phone number digits only, no `+` (e.g. `97220001234`)\n- `phoneNumber` ✅ — Display phone number (can include `+` and spaces)\n- `organization` — Company/organization name\n- `email` — Email address\n- `url` — Website URL\n- `delay` — Delay in ms\n- `quoted.key.id` — Message ID to quote", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string" }, "recipient": { "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string" }, "wuid": { "type": "string" }, "phoneNumber": { "type": "string" }, "organization": { "type": "string" }, "email": { "type": "string" }, "url": { "type": "string" } } } } }, "required": [ "instance", "recipient", "contacts" ] }, "example": { "instance": "{{instance}}", "recipient": "+972567077653", "contacts": [ { "fullName": "Support Team", "wuid": "97220001234", "phoneNumber": "+97220001234", "organization": "Acme Corp", "email": "support@acme.com", "url": "https://acme.com" } ] } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "message_id": { "type": "integer" }, "status": { "type": "string" }, "type": { "type": "string" }, "recipient": { "type": "string" }, "queued_at": { "type": "string" }, "instance": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "contacts_count": { "type": "integer" }, "credits_charged": { "type": "integer" } }, "required": [ "message_id", "status", "type", "recipient", "queued_at", "instance", "contacts_count", "credits_charged" ] } }, "required": [ "success", "message", "data" ] }, "example": { "success": true, "message": "Message queued for sending", "data": { "message_id": 12350, "status": "pending", "type": "contact", "recipient": "+972567077653", "queued_at": "2025-01-15T10:33:00.000000Z", "instance": { "id": 124, "name": "my-instance" }, "contacts_count": 1, "credits_charged": 1 } } } } } }, "security": [] } }, "/integration/v1/messages/send-poll": { "post": { "summary": "Send Poll", "deprecated": false, "description": "Send an interactive poll. Recipients vote directly in WhatsApp without leaving the chat.\n\n**Permission:** `send_message`\n\n**Fields:**\n- `instance` ✅\n- `recipient` ✅* or `contact_id` ✅*\n- `name` ✅ — Poll question / title (max 255 chars)\n- `values` ✅ — Array of option strings. Minimum: 2, Maximum: 13\n- `selectable_count` — Maximum number of options a user can select (default: 1, for multi-select increase this)\n\n**Note:** Polls are natively interactive in WhatsApp. Vote results are visible in the chat.", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string" }, "recipient": { "type": "string" }, "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "selectable_count": { "type": "integer" } }, "required": [ "instance", "recipient", "name", "values", "selectable_count" ] }, "example": { "instance": "{{instance}}", "recipient": "+972567077653", "name": "Which day works best for your appointment?", "values": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" ], "selectable_count": 1 } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "message_id": { "type": "integer" }, "status": { "type": "string" }, "type": { "type": "string" }, "recipient": { "type": "string" }, "queued_at": { "type": "string" }, "instance": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "poll": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "selectableCount": { "type": "integer" } }, "required": [ "name", "values", "selectableCount" ] }, "credits_charged": { "type": "integer" } }, "required": [ "message_id", "status", "type", "recipient", "queued_at", "instance", "poll", "credits_charged" ] } }, "required": [ "success", "message", "data" ] }, "example": { "success": true, "message": "Message queued for sending", "data": { "message_id": 12351, "status": "pending", "type": "poll", "recipient": "+972567077653", "queued_at": "2025-01-15T10:34:00.000000Z", "instance": { "id": 124, "name": "my-instance" }, "poll": { "name": "Best time?", "values": [ "Morning", "Afternoon", "Evening" ], "selectableCount": 1 }, "credits_charged": 1 } } } } } }, "security": [] } }, "/integration/v1/messages/send-buttons": { "post": { "summary": "Send Buttons", "deprecated": false, "description": "Send a message with interactive tap-to-action buttons.\n\n**Permission:** `send_message`\n\n**Fields:**\n- `instance` ✅\n- `recipient` ✅* or `contact_id` ✅*\n- `title` ✅ — Header text (max 255 chars)\n- `description` ✅ — Body text\n- `footer` — Footer text (max 60 chars)\n- `buttons` ✅ — Array of button objects (at least 1)\n- `delay` — Delay in ms\n- `quoted.key.id` — Message ID to quote\n\n**Button types:**\n\n| Type | Required Extra Field | Description |\n|---|---|---|\n| `reply` | `id` | Quick reply button — fires a callback with the `id` |\n| `copy` | `copyCode` | Copies text to the user's clipboard |\n| `url` | `url` | Opens a URL in the browser |\n| `call` | `phoneNumber` | Initiates a phone call |\n| `pix` | *(none)* | Brazilian PIX payment trigger |", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string" }, "recipient": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "footer": { "type": "string" }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "displayText": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "phoneNumber": { "type": "string" } }, "required": [ "type", "displayText" ] } } }, "required": [ "instance", "recipient", "title", "description", "footer", "buttons" ] }, "example": { "instance": "{{instance}}", "recipient": "+972567077653", "title": "Your Order is Ready!", "description": "Order #5678 is packed and awaiting pickup.", "footer": "Thank you for shopping with us", "buttons": [ { "type": "reply", "displayText": "✅ Confirm Pickup", "id": "confirm_pickup_5678" }, { "type": "url", "displayText": "🗺 View on Map", "url": "https://maps.google.com/?q=31.7683,35.2137" }, { "type": "call", "displayText": "📞 Call Us", "phoneNumber": "+97220001234" } ] } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "message_id": { "type": "integer" }, "status": { "type": "string" }, "type": { "type": "string" }, "recipient": { "type": "string" }, "queued_at": { "type": "string" }, "instance": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "buttons_count": { "type": "integer" }, "credits_charged": { "type": "integer" } }, "required": [ "message_id", "status", "type", "recipient", "queued_at", "instance", "buttons_count", "credits_charged" ] } }, "required": [ "success", "message", "data" ] }, "example": { "success": true, "message": "Message queued for sending", "data": { "message_id": 12352, "status": "pending", "type": "buttons", "recipient": "+972567077653", "queued_at": "2025-01-15T10:35:00.000000Z", "instance": { "id": 124, "name": "my-instance" }, "buttons_count": 1, "credits_charged": 1 } } } } } }, "security": [] } }, "/integration/v1/messages/message_id/status": { "get": { "summary": "Get Message Status", "deprecated": false, "description": "Get the current delivery status of a specific message.\n\n**Permission:** `send_message`\n\n**Path parameter:**\n- `messageId` — The `message_id` returned when you queued the message\n\n**Status values:**\n| Status | Meaning |\n|---|---|\n| `pending` | Queued, not yet sent |\n| `processing` | Being sent to WhatsApp now |\n| `sent` | Accepted by WhatsApp servers |\n| `delivered` | Delivered to recipient's device |\n| `failed` | Send attempt failed |\n| `refunded` | Failed and credit returned to pocket |", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "message_id": { "type": "integer" }, "status": { "type": "string" }, "type": { "type": "string" }, "recipient": { "type": "string" }, "sent_at": { "type": "string" }, "delivered_at": { "type": "string" }, "failed_at": { "type": "null" }, "error_message": { "type": "null" } }, "required": [ "message_id", "status", "type", "recipient", "sent_at", "delivered_at", "failed_at", "error_message" ] } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "message_id": 12345, "status": "delivered", "type": "text", "recipient": "+972567077653", "sent_at": "2025-01-15T10:30:05.000000Z", "delivered_at": "2025-01-15T10:30:07.000000Z", "failed_at": null, "error_message": null } } } } } }, "security": [] } }, "/integration/v1/messages": { "get": { "summary": "List Messages", "deprecated": false, "description": "List all messages for the authenticated account with filtering and pagination.\n\n**Permission:** `read_messages`\n\n**Query parameters:**\n- `page` — Page number (default: 1)\n- `per_page` — Results per page (default: 50, max: 100)\n- `status` — Filter: `pending`, `sent`, `delivered`, `failed`\n- `type` — Filter by message_type (e.g. `text`, `image`)", "tags": [], "parameters": [ { "name": "status", "in": "query", "description": "Filter by status: pending | sent | delivered | failed", "required": true, "example": "delivered", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Results per page (default: 50, max: 100)", "required": true, "example": "20", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (default: 1)", "required": true, "example": "1", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by message_type (text, image, video, etc.)", "required": false, "example": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] } }, "/integration/v1/messages/message_id": { "get": { "summary": "Get Message Detail", "deprecated": false, "description": "Get full details of a single message record, including content, metadata, and all status timestamps.\n\n**Permission:** `read_messages`\n\n**Path parameter:**\n- `messageId` — The message ID returned when the message was queued", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] } }, "/integration/v1/instances": { "get": { "summary": "List Instances", "deprecated": false, "description": "List all instances (connected WhatsApp phone sessions) owned by the authenticated account.\n\n**Permission:** `manage_instances`\n\n**Response fields per instance:**\n- `id` — Instance ID (use this in message `instance` field)\n- `name` — Instance name (can also be used in `instance` field)\n- `status` — `open` (connected), `close` (disconnected), `connecting`\n- `workspace` — Parent workspace info", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "workspace": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "created_at": { "type": "string" } } } } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": [ { "id": 124, "name": "my-instance", "status": "open", "workspace": { "id": 22, "name": "Main Workspace" }, "created_at": "2025-01-01T00:00:00.000000Z" } ] } } } } }, "security": [] } }, "/integration/v1/instances/instance": { "get": { "summary": "Get Instance", "deprecated": false, "description": "Get details of a single instance by ID or name.\n\n**Permission:** `manage_instances`\n\n**Path parameter:**\n- `instanceId` — Instance ID (integer) or instance name (string)", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] } }, "/integration/v1/instances/instance/status": { "get": { "summary": "Get Instance Live Status", "deprecated": false, "description": "Get the live connection status of an instance by querying the Evolution API in real time.\n\n**Permission:** `manage_instances`\n\n**Connection status values:**\n- `open` — Connected and ready to send messages\n- `close` — Disconnected (scan QR code to reconnect)\n- `connecting` — In the process of connecting\n\n**Response fields:**\n- `instance_id`, `name`\n- `connection_status`\n- `phone_number` — The connected WhatsApp number\n- `battery` — Battery % of the phone (if available)\n- `plugged` — Whether the phone is charging", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "instance_id": { "type": "integer" }, "name": { "type": "string" }, "connection_status": { "type": "string" }, "phone_number": { "type": "string" }, "battery": { "type": "integer" }, "plugged": { "type": "boolean" } }, "required": [ "instance_id", "name", "connection_status", "phone_number", "battery", "plugged" ] } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "instance_id": 124, "name": "my-instance", "connection_status": "open", "phone_number": "+972501234567", "battery": 85, "plugged": true } } } } } }, "security": [] } }, "/integration/v1/contacts": { "get": { "summary": "List Contacts", "deprecated": false, "description": "List all contacts (PhoneNumber records) for the authenticated account.\n\n**Permission:** `manage_contacts`\n\n**Query parameters:**\n- `per_page` — Results per page (default: 50, max: 100)\n- `search` — Filter by phone number or label", "tags": [], "parameters": [ { "name": "per_page", "in": "query", "description": "Results per page (default: 50, max: 100)", "required": true, "example": "50", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": true, "example": "1", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search by phone number or label", "required": false, "example": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } }, "headers": {} } }, "security": [] }, "post": { "summary": "Create Contact", "deprecated": false, "description": "Create a new contact (PhoneNumber record).\n\n**Permission:** `manage_contacts`\n\n**Fields:**\n- `phone` ✅ — E.164 phone number (e.g. `+972567077653`)\n- `label` — Display name / label for the contact\n- `email` — Email address\n- `notes` — Free-text notes about the contact\n\nOnce created, use the returned `id` as `contact_id` in any send endpoint.", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "label": { "type": "string" }, "email": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "phone", "label", "email", "notes" ] }, "example": { "phone": "+972567077653", "label": "Ahmed Almabhouh", "email": "ahmed@example.com", "notes": "VIP customer — prefers Arabic" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "phone_number": { "type": "string" }, "label": { "type": "string" }, "email": { "type": "null" }, "notes": { "type": "null" }, "created_at": { "type": "string" } }, "required": [ "id", "phone_number", "label", "email", "notes", "created_at" ] } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "id": 55, "phone_number": "+972567077653", "label": "Ahmed", "email": null, "notes": null, "created_at": "2025-01-15T10:00:00.000000Z" } } } } } }, "security": [] } }, "/integration/v1/contacts/contact_id": { "get": { "summary": "Get Contact", "deprecated": false, "description": "Get a single contact by ID.\n\n**Permission:** `manage_contacts`", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] }, "put": { "summary": "Update Contact", "deprecated": false, "description": "Update a contact's label, email, or notes.\n\n**Permission:** `manage_contacts`\n\nOnly include the fields you want to update — unset fields are left unchanged.", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "label", "notes" ] }, "example": { "label": "Ahmed Almabhouh (Updated)", "notes": "Upgraded to Premium — prefers Arabic" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] }, "delete": { "summary": "Delete Contact", "deprecated": false, "description": "Permanently delete a contact.\n\n**Permission:** `manage_contacts`\n\n⚠️ This action is irreversible. Messages sent to this contact will retain their history but the contact record will no longer be available.", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] } }, "/integration/v1/templates": { "get": { "summary": "List Templates", "deprecated": false, "description": "List all message templates for the authenticated account.\n\n**Permission:** `manage_templates`", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] }, "post": { "summary": "Create Template — Image", "deprecated": false, "description": "Create an image template. When using this template in a send request, you will still need to provide `media_url` and `filename` in the send request body.", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": "{\n \"workspace_id\": {{workspace_id}},\n \"name\": \"Promo Banner\",\n \"message_type\": \"image\",\n \"content\": \"🎉 Hi {{name}}, check out our latest promotion!\",\n \"is_active\": true\n}" } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] } }, "/integration/v1/workspaces": { "get": { "summary": "List Workspaces", "deprecated": false, "description": "List all workspaces owned by the authenticated account.\n\n**Permission:** `manage_workspaces`", "tags": [], "parameters": [ { "name": "Accept", "in": "header", "description": "", "required": false, "example": "application/json", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } }, "headers": {} } }, "security": [] } }, "/integration/v1/workspaces/workspace_id": { "get": { "summary": "Get Workspace", "deprecated": false, "description": "Get full details of a single workspace.\n\n**Permission:** `manage_workspaces`\n\n**Path parameter:**\n- `workspaceId` — Workspace ID (integer)", "tags": [], "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "security": [] } }, "/integration/v1/messages/send-reaction": { "post": { "summary": "Send Reaction (410 Disabled)", "deprecated": false, "description": "⛔ **Permanently disabled.** Returns `410 Gone`.\n\nThis endpoint is not available in this API version.", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string" }, "message_key": { "type": "object", "properties": { "remoteJid": { "type": "string" }, "fromMe": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "remoteJid", "fromMe", "id" ] }, "reaction": { "type": "string" } }, "required": [ "instance", "message_key", "reaction" ] }, "example": { "instance": "{{instance}}", "message_key": { "remoteJid": "+972567077653@s.whatsapp.net", "fromMe": true, "id": "ABCDEF1234567890" }, "reaction": "❤️" } } } }, "responses": { "410": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "example": { "success": false, "message": "The send-reaction endpoint is not available in this API version." } } } } }, "security": [] } }, "/integration/v1/messages/send-list": { "post": { "summary": "Send List (410 Disabled)", "deprecated": false, "description": "⛔ **Permanently disabled.** Returns `410 Gone`.\n\nWhatsApp has deprecated interactive list messages.", "tags": [], "parameters": [ { "name": "Content-Type", "in": "header", "description": "", "required": true, "example": "application/json", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string" }, "recipient": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "button_text": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "rowId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } } } } } } } }, "required": [ "instance", "recipient", "title", "description", "button_text", "sections" ] }, "example": { "instance": "{{instance}}", "recipient": "+972567077653", "title": "Menu", "description": "Choose an option", "button_text": "Open Menu", "sections": [ { "title": "Services", "rows": [ { "rowId": "row_1", "title": "Support", "description": "Get help" } ] } ] } } } }, "responses": { "410": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "example": { "success": false, "message": "The send-list endpoint is not supported. WhatsApp has deprecated interactive list messages." } } } } }, "security": [] } } }, "components": { "schemas": {}, "responses": {}, "securitySchemes": {} }, "servers": [], "security": [] }