{ "openapi": "3.1.0", "info": { "title": "WbizTool API", "version": "1.0.0", "summary": "Send WhatsApp messages from your own number over a REST API.", "description": "The WbizTool REST API sends WhatsApp messages (text, images and files, to numbers and groups, now or scheduled) from your own WhatsApp number, linked to WbizTool the way WhatsApp Web is linked to a phone. It is not the official WhatsApp Business API. Most endpoints authenticate with `client_id` and `api_key` sent in the request body (JSON or form fields), never in a header; the number verification endpoints use an `Authorization: Bearer` header instead. Always read the JSON body and check its `status` field, because some errors come back with HTTP 200. Guides, examples in cURL, Python, Node.js and PHP, and every error message: https://wbiztool.com/docs/", "termsOfService": "https://wbiztool.com/terms/", "contact": { "name": "WbizTool support", "email": "info@wbiztool.com", "url": "https://wbiztool.com/contact-us/" } }, "externalDocs": { "description": "WbizTool API documentation", "url": "https://wbiztool.com/docs/" }, "servers": [ { "url": "https://wbiztool.com/api/v1", "description": "Production" } ], "tags": [ { "name": "Messages", "description": "Send, schedule, cancel and track WhatsApp messages." }, { "name": "Media", "description": "Host files in the workspace Media directory and reuse their URLs." }, { "name": "Reminders", "description": "Recurring messages on a cron schedule." }, { "name": "Number verification", "description": "Check whether numbers are on WhatsApp. Uses a Bearer header." }, { "name": "WhatsApp numbers", "description": "Connect numbers and check which are connected." }, { "name": "Account", "description": "Credential and health checks." } ], "paths": { "/send_msg/": { "post": { "operationId": "sendMessage", "tags": [ "Messages" ], "summary": "Send a message", "description": "Queue a WhatsApp text, image or file to one phone number (or a group with `group_name`) from your connected number. `status: 1` means queued, not yet sent; follow it with a webhook or Message status. Image and file URLs are downloaded during the call (up to 100 MB). Upload a file instead with `multipart/form-data` and the field `file`. A non-POST request returns HTTP 400 `Invalid request method`.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/send-message-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" }, "examples": { "text": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678, "msg_type": 0, "country_code": "91", "phone": "9876543210", "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday." }, "summary": "Text message" }, "image": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678, "msg_type": 1, "country_code": "91", "phone": "9876543210", "img_url": "https://example.com/offers/diwali-sale.jpg", "msg": "Our Diwali sale starts today" }, "summary": "Image from a URL" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SendMessageMultipartRequest" } } } }, "responses": { "200": { "description": "Message queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreated" }, "examples": { "created": { "value": { "status": 1, "message": "Created", "msg_id": 9817263 } } } } } }, "400": { "description": "Request refused; nothing was queued. Examples of `message`: `Auth Error - Please send correct API key and Client id`, `Invalid client id.`, `Auth Error: invalid api key`, `Either phone or group_name parameter is required`, `Please provide either phone OR group_name, not both`, `Invalid phone number`, `Invalid Contact Number \"…\"`, `Msg cant be null`, `Message length is too long`, `Image Url Can't be null`, `File Url Can't be null`, `Invalid file url, Can't download`, `Invalid whatsapp client …`, `Invalid whatsapp client id.`, `Not enough credits`, `Demo Account can not access apis`, `Account Disabled`, `Invalid JSON format: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "noMsg": { "value": { "status": 0, "message": "Msg cant be null" }, "summary": "Msg cant be null" }, "badKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "429": { "description": "Daily fair-use limit reached for this number (1,000 messages in 24 hours).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyLimitError" }, "examples": { "dailyLimit": { "value": { "status": 0, "msg_id": 9817264, "code": "daily_limit_reached", "message": "Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow." } } } } } } }, "security": [] } }, "/send_msg/group/": { "post": { "operationId": "sendGroupMessage", "tags": [ "Messages" ], "summary": "Send a message to a group", "description": "Queue a WhatsApp text, image or file to a group your connected number is a member of. The group is matched by its exact name when the message is sent, so group problems (`Group not found`) only show in Message status or the webhook. Upload a file with `multipart/form-data` and the field `file`. A `group_name` sent as a JSON number, or a `msg_type` that is not a whole number, returns an HTML error page (HTTP 500).", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/send-message-to-group-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendGroupMessageRequest" }, "examples": { "text": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678, "msg_type": 0, "group_name": "Sales Team Mumbai", "msg": "Reminder: *weekly review* starts at 4 PM today." }, "summary": "Text to a group" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SendGroupMessageRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SendGroupMessageMultipartRequest" } } } }, "responses": { "200": { "description": "Message queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreated" }, "examples": { "created": { "value": { "status": 1, "message": "Created", "msg_id": 9817263 } } } } } }, "400": { "description": "Request refused. Examples of `message`: `Group Name cant be null`, `Msg cant be null`, `Image Url Can't be null`, `File Url Can't be null`, `Invalid whatsapp client …`, `Invalid whatsapp client id.`, `Not enough credits`, `Auth Error: invalid api key`, `Account Disabled`, `Invalid JSON format: …`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "noGroup": { "value": { "status": 0, "message": "Group Name cant be null" }, "summary": "Group Name cant be null" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } }, "429": { "description": "Daily fair-use limit reached for this number (1,000 messages in 24 hours).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyLimitError" }, "examples": { "dailyLimit": { "value": { "status": 0, "msg_id": 9817264, "code": "daily_limit_reached", "message": "Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow." } } } } } }, "500": { "description": "HTML error page instead of JSON (see the operation description).", "content": { "text/html": { "schema": { "type": "string" } } } } }, "security": [] } }, "/send_msg/multi/": { "post": { "operationId": "sendMultiMessage", "tags": [ "Messages" ], "summary": "Send to multiple numbers", "description": "Queue the same message to several phone numbers and group names given as one comma-separated `phone` string; one `msg_id` per recipient. The whole batch must fit in the number's daily fair-use room (and the free plan's messages) or nothing is created. Most errors come back with HTTP 200 and `status: 0`; a missing or non-numeric `whatsapp_client`, a non-string `phone` or a non-numeric `msg_type` returns an empty object `{}`. Images and files by URL only; `group_name` and `expire_after_seconds` are ignored. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/send-msg-multi-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMultiMessageRequest" }, "examples": { "mixed": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678, "msg_type": 0, "country_code": "91", "phone": "9876543210,9812345670,Sales Team Mumbai", "msg": "Our Diwali sale starts tomorrow. Get 20% off on all orders!" }, "summary": "Numbers and a group" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SendMultiMessageRequest" } } } }, "responses": { "200": { "description": "Messages queued (`status: 1`), or the request failed (`status: 0`, or `{}`). Failure messages: `Auth Error`, `Msg cant be null`, `Image Url Can't be null`, `File Url Can't be null`, `Not enough credits: … messages requested, … credits remaining`, `Daily limit reached: …` (with `code: daily_limit_reached`), `Invalid whatsapp client`, `No valid contacts found`, `Demo Account can not access apis`, `Invalid JSON format: …`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MultiMessageCreated" }, { "$ref": "#/components/schemas/DailyLimitError" }, { "$ref": "#/components/schemas/ApiError" }, { "type": "object", "maxProperties": 0, "description": "Empty object: failed." } ] }, "examples": { "created": { "value": { "msg_ids": [ 9817263, 9817264, 9817265 ], "messages": [ { "msg_id": 9817263, "contact": "919876543210", "is_group": false }, { "msg_id": 9817264, "contact": "919812345670", "is_group": false }, { "msg_id": 9817265, "contact": "Sales Team Mumbai", "is_group": true } ], "message": "Successfully created 3 messages", "status": 1 }, "summary": "Created" }, "invalidNumber": { "value": { "status": 0, "message": "Invalid whatsapp client" }, "summary": "Invalid whatsapp client" } } } } }, "400": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } } }, "security": [] } }, "/schedule_msg/": { "post": { "operationId": "scheduleMessage", "tags": [ "Messages" ], "summary": "Schedule a message", "description": "Queue a text, image or file to a phone number or group for a date and time (`dd/mm/yyyy`, `HH:MM`, `timezone`). A time in the past is sent straight away. Until it is sent the message has status `0` and can be cancelled. Images and files by URL only (downloaded at send time). Most errors come back with HTTP 200 and `status: 0`. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/schedule-message-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleMessageRequest" }, "examples": { "phone": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678, "msg_type": 0, "country_code": "91", "phone": "9876543210", "msg": "Hi Aman, a reminder that your appointment is today at 11:30 AM.", "date": "24/12/2026", "time": "09:00", "timezone": "Asia/Kolkata" }, "summary": "To a phone number" }, "group": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678, "msg_type": 0, "group_name": "Sales Team Mumbai", "msg": "Team meeting starts in 15 minutes.", "date": "24/12/2026", "time": "14:45", "timezone": "Asia/Kolkata" }, "summary": "To a group" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ScheduleMessageRequest" } } } }, "responses": { "200": { "description": "Scheduled (`status: 1`) or refused (`status: 0`). Failure messages include `Auth Error`, `Either phone or group_name parameter is required`, `Please provide either phone OR group_name, not both`, `Invalid phone number`, `Invalid Contact Number \"…\"`, `Msg cant be null`, `Image Url Can't be null`, `File Url Can't be null`, `Scheduled date & time is not in valid format…`, `Unknown timezone \"…\": …`, `Invalid msg_type: use 0 (text), 1 (image) or 2 (file)`, `Invalid whatsapp client …`, `Not enough credits`, `Demo Account can not access apis`, `Invalid JSON format: …`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MessageCreated" }, { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "created": { "value": { "msg_id": 9817263, "message": "Created", "status": 1 }, "summary": "Scheduled" }, "badDate": { "value": { "status": 0, "message": "Scheduled date & time is not in valid format" }, "summary": "Scheduled date & time is not in valid format" } } } } }, "400": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } }, "429": { "description": "Daily fair-use limit reached for this number (1,000 messages in 24 hours).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyLimitError" }, "examples": { "dailyLimit": { "value": { "status": 0, "msg_id": 9817264, "code": "daily_limit_reached", "message": "Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow." } } } } } }, "500": { "description": "Server error; nothing was scheduled. Try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "serverError": { "value": { "status": 0, "message": "Server error: the message was not scheduled. Please try again." }, "summary": "Server error: the message was not scheduled. Please try again." } } } } } }, "security": [] } }, "/cancel_msg/": { "post": { "operationId": "cancelMessage", "tags": [ "Messages" ], "summary": "Cancel a message", "description": "Cancel a message that has not been sent yet (status `0`, Created): scheduled or queued. It then reports status `3` and its webhook gets a `CANCELLED` event. A message a bot is already sending may still go out. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/cancel-message-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelMessageRequest" }, "examples": { "cancel": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "msg_id": 9817263 } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CancelMessageRequest" } } } }, "responses": { "200": { "description": "Cancelled (`status: 1`, `message: Cancelled`) or not (`status: 0`). Failure messages: `Msg has been Sent`, `Msg has been Failed`, `Msg has been Cancelled`, `Msg has been Expired`, `No msg found for given msg_id`, `Msg_id cant be null`, `Auth Error`, `Invalid JSON format: …`; a JSON body sent with another method than POST returns `{}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleResult" }, "examples": { "cancelled": { "value": { "message": "Cancelled", "status": 1 }, "summary": "Cancelled" }, "alreadySent": { "value": { "status": 0, "message": "Msg has been Sent" }, "summary": "Msg has been Sent" } } } } }, "400": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } } }, "security": [] } }, "/message/status/{msg_id}/": { "post": { "operationId": "getMessageStatus", "tags": [ "Messages" ], "summary": "Get message status", "description": "Current state of one message. Here `status` is the message's own status code (0 Created, 1 Sent, 2 Failed, 3 Cancelled, 4 Expired), not a success flag; an unknown ID also returns `0`, so check `message` first. A non-numeric ID returns an HTML 404 page, a non-POST request `{}`. Messages untouched for about 90 days are purged. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/message-status-api/" }, "parameters": [ { "name": "msg_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The `msg_id` returned when the message was sent or scheduled.", "example": 9817263 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credentials" }, "examples": { "credentials": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Credentials" } } } }, "responses": { "200": { "description": "The message state, an unknown ID, or `Auth Error` (`{\"message\": \"Auth Error\", \"status\": 0}`; also for an invalid JSON body).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MessageStatus" }, { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "sent": { "value": { "message": "Sent", "status": 1, "status_text": "Sent", "error": "" }, "summary": "Sent" }, "failed": { "value": { "message": "Failed", "status": 2, "status_text": "Failed", "error": "Phone number invalid" }, "summary": "Failed" }, "unknown": { "value": { "message": "Unknown message id", "status": 0, "status_text": "pending", "error": "Invalid message id" }, "summary": "Unknown ID" } } } } }, "400": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } } }, "security": [] } }, "/msg_status/": { "post": { "operationId": "getMessageStatusDeprecated", "tags": [ "Messages" ], "deprecated": true, "summary": "Get message status (deprecated)", "description": "Old form of Message status with `msg_id` in the body; returns the same fields. It also accepts GET with `client_id`, `api_key` and `msg_id` in the query string, which exposes the key in logs. Use `POST /message/status/{msg_id}/` instead. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/message-status-api/#tips" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecatedMessageStatusRequest" }, "examples": { "status": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "msg_id": 9817263 } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DeprecatedMessageStatusRequest" } } } }, "responses": { "200": { "description": "Same body as Message status.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MessageStatus" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "400": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } } }, "security": [] } }, "/report/": { "post": { "operationId": "getMessageHistory", "tags": [ "Messages" ], "summary": "Get message history", "description": "Messages in the workspace created in a date range (from `start_date` 00:00 IST up to, not including, `end_date`), 200 per page, oldest first, whatever sent them (API, dashboard, campaigns). `status` is always `0`: success is `message: Success` with `total`. `Success` without `total` means the `whatsapp_client` ID is not in the workspace. Pagination needs a JSON body with `page` as a number. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/history-messages-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageHistoryRequest" }, "examples": { "week": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "start_date": "01-09-2026", "end_date": "08-09-2026", "page": 1 } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/MessageHistoryRequest" } } } }, "responses": { "200": { "description": "History, or an error with `status: 0` and an empty `history` (`Error` for missing or badly formatted dates, an invalid JSON body or a non-POST request; `Auth Error`; `Demo Account can not access apis`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageHistory" }, "examples": { "success": { "value": { "message": "Success", "status": 0, "total": 3, "history": [ { "id": 9817263, "msg_type": "Text", "contact": "919876543210", "message_status": "Sent" }, { "id": 9817264, "msg_type": "File", "contact": "919812345670", "message_status": "Failed" }, { "id": 9817265, "msg_type": "Image", "contact": "Sales Team Mumbai", "message_status": "Pending" } ] }, "summary": "Success" }, "error": { "value": { "message": "Error", "status": 0, "history": [] }, "summary": "Error" } } } } }, "400": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } } }, "security": [] } }, "/media/upload/": { "post": { "operationId": "uploadMedia", "tags": [ "Media" ], "summary": "Upload a media file", "description": "Upload an image, document, audio, video or archive (up to 64 MB, within the workspace's media storage) to the Media directory and get a public `file_url` to send with. Only `multipart/form-data` is read. Always HTTP 200: check `status`.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/media-upload-api/" }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadMediaRequest" } } } }, "responses": { "200": { "description": "Uploaded (`status: 1`) or refused (`status: 0`). Errors also come back with HTTP 200 and `status: 0`: `client_id is required`, `api_key is required`, `client_id must be a valid integer`, `Invalid API key`, `Invalid client_id for this API key`, `Only POST method is supported`, `media_file is required`, `File is too large. Maximum size is 64MB. Your file: …MB`, `File type not supported. Type detected: …`, `Storage full: …`, `Error uploading file: …`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MediaUploaded" }, { "$ref": "#/components/schemas/MediaError" } ] }, "examples": { "uploaded": { "value": { "status": 1, "message": "File uploaded successfully", "data": { "id": 5122, "file_name": "media_12345_17895804001234_3f9a1c7e.pdf", "original_file_name": "invoice-4821.pdf", "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895804001234_3f9a1c7e.pdf", "file_type": "file", "file_size": 248312, "file_size_display": "242.5 KB", "mime_type": "application/pdf", "is_image": false, "file_extension": "pdf", "created_at": "2026-09-16T10:20:31.512934+00:00" } }, "summary": "Uploaded" }, "tooLarge": { "value": { "status": 0, "message": "File is too large. Maximum size is 64MB. Your file: 71.3MB" }, "summary": "File is too large. Maximum size is 64MB. Your file: 71.3MB" } } } } } }, "security": [] } }, "/media/list/": { "get": { "operationId": "listMedia", "tags": [ "Media" ], "summary": "List media files", "description": "Files in the workspace's Media directory (deleted files excluded), newest first, with filters and pages. Parameters in the query string. Always HTTP 200: check `status`.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/media-list-api/" }, "parameters": [ { "$ref": "#/components/parameters/ClientIdQuery" }, { "$ref": "#/components/parameters/ApiKeyQuery" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "file_type", "in": "query", "schema": { "type": "string", "enum": [ "image", "file" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive match on the original or stored name." } ], "responses": { "200": { "description": "The files (`status: 1`), newest first, or an error (`status: 0`). Errors also come back with HTTP 200 and `status: 0`: `client_id is required`, `api_key is required`, `client_id must be a valid integer`, `Invalid API key`, `Invalid client_id for this API key`, `Error retrieving media files: …`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MediaList" }, { "$ref": "#/components/schemas/MediaError" } ] }, "examples": { "list": { "value": { "status": 1, "message": "Media files retrieved successfully", "data": { "total_count": 1, "page": 1, "limit": 20, "total_pages": 1, "has_next": false, "has_previous": false, "media_files": [ { "id": 5123, "file_name": "media_12345_17895806123456_b81e04d9.jpg", "original_file_name": "diwali-sale.jpg", "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895806123456_b81e04d9.jpg", "file_type": "image", "file_size": 524288, "file_size_display": "512.0 KB", "mime_type": "image/jpeg", "is_image": true, "file_extension": "jpg", "created_at": "2026-09-16T10:23:52.106447+00:00", "uploaded_by": "aman@example.com" } ] } }, "summary": "One page" }, "badKey": { "value": { "status": 0, "message": "Invalid API key" }, "summary": "Invalid API key" } } } } } }, "security": [] }, "post": { "operationId": "listMediaPost", "tags": [ "Media" ], "summary": "List media files (JSON body)", "description": "Same as the GET form with the parameters in a JSON body, which keeps the API key out of URLs. If `client_id` is also in the query string, the body is ignored. In form fields `page` and `limit` are ignored.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/media-list-api/#request-parameters" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMediaRequest" }, "examples": { "search": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "search": "invoice", "page": 1, "limit": 50 } } } } } }, "responses": { "200": { "description": "The files (`status: 1`), newest first, or an error (`status: 0`). Errors also come back with HTTP 200 and `status: 0`: `client_id is required`, `api_key is required`, `client_id must be a valid integer`, `Invalid API key`, `Invalid client_id for this API key`, `Error retrieving media files: …`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MediaList" }, { "$ref": "#/components/schemas/MediaError" } ] }, "examples": { "list": { "value": { "status": 1, "message": "Media files retrieved successfully", "data": { "total_count": 1, "page": 1, "limit": 20, "total_pages": 1, "has_next": false, "has_previous": false, "media_files": [ { "id": 5123, "file_name": "media_12345_17895806123456_b81e04d9.jpg", "original_file_name": "diwali-sale.jpg", "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895806123456_b81e04d9.jpg", "file_type": "image", "file_size": 524288, "file_size_display": "512.0 KB", "mime_type": "image/jpeg", "is_image": true, "file_extension": "jpg", "created_at": "2026-09-16T10:23:52.106447+00:00", "uploaded_by": "aman@example.com" } ] } }, "summary": "One page" }, "badKey": { "value": { "status": 0, "message": "Invalid API key" }, "summary": "Invalid API key" } } } } } }, "security": [] } }, "/media/{media_id}/": { "parameters": [ { "$ref": "#/components/parameters/MediaId" } ], "get": { "operationId": "getMedia", "tags": [ "Media" ], "summary": "Get a media file", "description": "Details and download URL of one Media directory file by ID; credentials in the query string. Always HTTP 200 (check `status`), except an HTML 404 for a non-numeric ID.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/media-get-api/" }, "parameters": [ { "$ref": "#/components/parameters/ClientIdQuery" }, { "$ref": "#/components/parameters/ApiKeyQuery" } ], "responses": { "200": { "description": "The file (`status: 1`) or an error (`status: 0`). Errors also come back with HTTP 200 and `status: 0`: `client_id is required`, `api_key is required`, `client_id must be a valid integer`, `Invalid API key`, `Invalid client_id for this API key`, `Media file not found`, `Error retrieving media file: …`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MediaUploaded" }, { "$ref": "#/components/schemas/MediaError" } ] }, "examples": { "file": { "value": { "status": 1, "message": "Media file retrieved successfully", "data": { "id": 5122, "file_name": "media_12345_17895804001234_3f9a1c7e.pdf", "original_file_name": "invoice-4821.pdf", "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895804001234_3f9a1c7e.pdf", "file_type": "file", "file_size": 248312, "file_size_display": "242.5 KB", "mime_type": "application/pdf", "is_image": false, "file_extension": "pdf", "created_at": "2026-09-16T10:20:31.512934+00:00", "modified_at": "2026-09-16T10:20:31.512961+00:00", "uploaded_by": "aman@example.com" } }, "summary": "Found" }, "notFound": { "value": { "status": 0, "message": "Media file not found" }, "summary": "Media file not found" } } } } } }, "security": [] }, "post": { "operationId": "getMediaPost", "tags": [ "Media" ], "summary": "Get a media file (JSON body)", "description": "Same as the GET form with `client_id` and `api_key` in a JSON body. If `client_id` is in the query string, the body is ignored.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/media-get-api/#request-parameters" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credentials" }, "examples": { "credentials": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY" } } } } } }, "responses": { "200": { "description": "The file (`status: 1`) or an error (`status: 0`). Errors also come back with HTTP 200 and `status: 0`: `client_id is required`, `api_key is required`, `client_id must be a valid integer`, `Invalid API key`, `Invalid client_id for this API key`, `Media file not found`, `Error retrieving media file: …`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MediaUploaded" }, { "$ref": "#/components/schemas/MediaError" } ] }, "examples": { "file": { "value": { "status": 1, "message": "Media file retrieved successfully", "data": { "id": 5122, "file_name": "media_12345_17895804001234_3f9a1c7e.pdf", "original_file_name": "invoice-4821.pdf", "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895804001234_3f9a1c7e.pdf", "file_type": "file", "file_size": 248312, "file_size_display": "242.5 KB", "mime_type": "application/pdf", "is_image": false, "file_extension": "pdf", "created_at": "2026-09-16T10:20:31.512934+00:00", "modified_at": "2026-09-16T10:20:31.512961+00:00", "uploaded_by": "aman@example.com" } }, "summary": "Found" }, "notFound": { "value": { "status": 0, "message": "Media file not found" }, "summary": "Media file not found" } } } } } }, "security": [] } }, "/reminder/create/": { "post": { "operationId": "createReminder", "tags": [ "Reminders" ], "summary": "Create a recurring reminder", "description": "Create a message that is queued automatically whenever a five-field cron expression matches in the reminder's IANA `timezone`. Needs a plan that includes reminders. Send text values as JSON strings: a number, `true` or `null` in a text field returns an HTML error page (HTTP 500).", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/reminder-create-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReminderRequest" }, "examples": { "text": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678, "reminder_name": "Monthly rent reminder", "phone": "919876543210", "message": "Hi Aman, a reminder that your rent is due on {current_date_formatted}.", "cron_expression": "0 10 1 * *", "timezone": "Asia/Kolkata" }, "summary": "Monthly text reminder" }, "image": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678, "reminder_name": "Weekly class timetable", "phone": "919876543210", "msg_type": 1, "img_url": "https://example.com/timetable.png", "message": "Here is this week's timetable.", "cron_expression": "0 8 * * 1", "timezone": "Asia/Kolkata" }, "summary": "Weekly image reminder" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CreateReminderRequest" } } } }, "responses": { "200": { "description": "Reminder created and active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderCreated" }, "examples": { "created": { "value": { "reminder_id": 3187, "message": "Reminder created successfully", "status": 1 } } } } } }, "400": { "description": "Refused. Examples of `message`: `Invalid JSON format: …` (also for any GET), `Invalid client id.`, `Reminder name cannot be null`, `Phone number cannot be null`, `Invalid phone number or group name`, `Message template cannot be null`, `Cron expression cannot be null`, `Invalid cron expression`, `Invalid timezone`, `Image URL cannot be null for image messages`, `File URL cannot be null for file messages`, `Auth Error: invalid api key`, `Auth Error: please check client id`, `Demo Account cannot access APIs`, `Not enough credits`, `Upgrade your plan to use reminders feature`, `WhatsApp Logged Out. Please Reconnect!!`, `Invalid WhatsApp client id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badTimezone": { "value": { "status": 0, "message": "Invalid timezone" }, "summary": "Invalid timezone" } } } } }, "500": { "description": "The reminder could not be saved (`Error creating reminder: …`), or an HTML error page for a non-string text value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [] } }, "/reminder/list/": { "post": { "operationId": "listReminders", "tags": [ "Reminders" ], "summary": "List reminders", "description": "Active and paused reminders of the workspace, 50 per page, newest first (cancelled ones excluded). POST only. `next_run` is computed as if the timezone were UTC, and the timezone is not returned.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/reminder-list-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRemindersRequest" }, "examples": { "page1": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "page": 1 } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ListRemindersRequest" } } } }, "responses": { "200": { "description": "One page of reminders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderList" }, "examples": { "list": { "value": { "reminders": [ { "id": 3187, "name": "Monthly rent reminder", "to_number": "919876543210", "message_template": "Hi Aman, a reminder that your rent is due on {current_date_formatted}.", "msg_type": 0, "msg_type_display": "Text", "img_url": "", "file_name": "", "cron_expression": "0 10 1 * *", "next_run": "2026-10-01 10:00:00 UTC", "is_active": true, "whatsapp_client_id": 678, "created_at": "2026-09-16 04:45:12" } ], "total": 1, "page": 1, "page_size": 50, "message": "Success", "status": 1 } } } } } }, "400": { "description": "Refused: `Invalid JSON format: …` (also for GET), `Auth Error - Please send correct API key and Client id`, `Invalid client id`, `Auth Error: invalid api key`, `Auth Error: please check client id`, `Demo Account cannot access APIs`, `Upgrade your plan to use reminders feature`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "noPlan": { "value": { "status": 0, "message": "Upgrade your plan to use reminders feature" }, "summary": "Upgrade your plan to use reminders feature" } } } } }, "500": { "description": "`Error fetching reminders: …`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [] } }, "/reminder/cancel/": { "post": { "operationId": "cancelReminder", "tags": [ "Reminders" ], "summary": "Cancel a reminder", "description": "Stop a reminder for good (paused ones too). It cannot be restored; a message it already queued is not removed. Cancelling twice returns `Reminder not found`.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/reminder-cancel-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelReminderRequest" }, "examples": { "cancel": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "reminder_id": "3187" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CancelReminderRequest" } } } }, "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleResult" }, "examples": { "cancelled": { "value": { "message": "Reminder cancelled successfully", "status": 1 } } } } } }, "400": { "description": "Refused: `Invalid JSON format: …`, `Reminder ID cannot be null`, `Auth Error - Please send correct API key and Client id`, `Invalid client id`, `Invalid reminder id`, `Auth Error: invalid api key`, `Auth Error: please check client id`, `Demo Account cannot access APIs`, `Upgrade your plan to use reminders feature`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badId": { "value": { "status": 0, "message": "Invalid reminder id" }, "summary": "Invalid reminder id" } } } } }, "404": { "description": "The reminder does not exist, is in another workspace or was already cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "notFound": { "value": { "status": 0, "message": "Reminder not found" }, "summary": "Reminder not found" } } } } }, "500": { "description": "`Error cancelling reminder: …`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [] } }, "/verification/create/": { "post": { "operationId": "createVerification", "tags": [ "Number verification" ], "summary": "Create a number verification task", "description": "Check whether phone numbers are registered on WhatsApp. Returns a `campaign_id` at once; a connected WhatsApp number of the workspace then checks the numbers in the background. Authenticates with `Authorization: Bearer YOUR_API_KEY` (no `client_id`); the body must be JSON. Needs a plan with number verification, which also limits numbers per request and per billing period.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/verification-create-api/" }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVerificationRequest" }, "examples": { "leads": { "value": { "campaign_name": "Website leads - September", "numbers": [ "919876543210", "+91 98765 43211", "14155550123" ] } } } } } }, "responses": { "200": { "description": "Task created; every accepted number starts as `pending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationCreated" }, "examples": { "created": { "value": { "status": "success", "message": "Verification task created successfully", "campaign_id": 4521, "numbers_count": 3, "numbers_submitted": [ "919876543210", "919876543211", "14155550123" ] } } } } } }, "400": { "description": "`Numbers array is required`, `No valid phone numbers found`, `Request contains N numbers but your plan allows only M verifications`, or the billing period quota (`code: quota_exceeded`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" }, "examples": { "noValid": { "value": { "status": "error", "message": "No valid phone numbers found" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" }, "examples": { "missing": { "value": { "status": "error", "message": "API key required" } }, "invalid": { "value": { "status": "error", "message": "Invalid API key" } } } } } }, "403": { "description": "Plan without number verification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" }, "examples": { "noPlan": { "value": { "status": "error", "message": "Verification feature not available for your plan" } } } } } }, "405": { "description": "Not a POST request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" }, "examples": { "method": { "value": { "status": "error", "message": "Only POST method allowed" } } } } } }, "500": { "description": "`Internal server error: …` (often an invalid JSON body or a non-numeric parameter).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" } } } } } } }, "/verification/status/": { "get": { "operationId": "getVerificationStatus", "tags": [ "Number verification" ], "summary": "Get verification task status", "description": "Progress of a verification task and the result of every number in it (no pagination). Poll every 30 to 60 seconds until `overall_status` is `completed`. Bearer header (or an `api_key` query parameter).", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/verification-status-api/" }, "security": [ { "bearerAuth": [] }, { "apiKeyQuery": [] } ], "parameters": [ { "name": "campaign_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "The `campaign_id` from Create verification.", "example": 4521 } ], "responses": { "200": { "description": "Task progress and results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationStatus" }, "examples": { "processing": { "value": { "status": "success", "campaign_id": 4521, "campaign_name": "Website leads - September", "overall_status": "processing", "progress": { "total": 3, "pending": 1, "verified": 1, "invalid": 1, "completed_percentage": 66.67 }, "results": [ { "number": "14155550123", "status": "pending", "checked_at": null, "created_at": "2026-09-16T10:15:00.483101+00:00" }, { "number": "919876543210", "status": "verified", "checked_at": "2026-09-16T10:16:12.204551+00:00", "created_at": "2026-09-16T10:15:00.482913+00:00" }, { "number": "919876543211", "status": "invalid", "checked_at": "2026-09-16T10:16:19.915372+00:00", "created_at": "2026-09-16T10:15:00.483020+00:00" } ], "created_at": "2026-09-16T10:15:00.471820+00:00", "last_updated": "2026-09-16T10:15:00.471820+00:00" } } } } } }, "400": { "description": "`campaign_id is required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" }, "examples": { "missing": { "value": { "status": "error", "message": "API key required" } }, "invalid": { "value": { "status": "error", "message": "Invalid API key" } } } } } }, "404": { "description": "`Campaign not found` (or `Task not found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" }, "examples": { "notFound": { "value": { "status": "error", "message": "Campaign not found" } } } } } }, "405": { "description": "Not a GET request (`Only GET method allowed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" } } } }, "500": { "description": "`Internal server error: …` (often an invalid JSON body or a non-numeric parameter).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" } } } } } } }, "/verification/results/": { "get": { "operationId": "getVerificationResults", "tags": [ "Number verification" ], "summary": "List verification results", "description": "Verification results page by page (newest first), optionally for one task and one status, including tasks started in the dashboard. Increase `offset` by `limit` until `has_more` is `false`. Bearer header (or an `api_key` query parameter).", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/verification-results-api/" }, "security": [ { "bearerAuth": [] }, { "apiKeyQuery": [] } ], "parameters": [ { "name": "campaign_id", "in": "query", "schema": { "type": "integer" }, "example": 4521 }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "verified", "invalid" ] }, "description": "Case-sensitive; any other value applies no filter." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "One page of results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResults" }, "examples": { "verified": { "value": { "status": "success", "total_count": 2, "returned_count": 2, "limit": 100, "offset": 0, "has_more": false, "results": [ { "id": 88215, "campaign_id": 4521, "campaign_name": "Website leads - September", "number": "14155550123", "status": "verified", "checked_at": "2026-09-16T10:16:26.730114+00:00", "created_at": "2026-09-16T10:15:00.483101+00:00" }, { "id": 88213, "campaign_id": 4521, "campaign_name": "Website leads - September", "number": "919876543210", "status": "verified", "checked_at": "2026-09-16T10:16:12.204551+00:00", "created_at": "2026-09-16T10:15:00.482913+00:00" } ] } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" }, "examples": { "missing": { "value": { "status": "error", "message": "API key required" } }, "invalid": { "value": { "status": "error", "message": "Invalid API key" } } } } } }, "404": { "description": "`Campaign not found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" } } } }, "405": { "description": "Not a GET request (`Only GET method allowed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" } } } }, "500": { "description": "`Internal server error: …` (often an invalid JSON body or a non-numeric parameter).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationError" } } } } } } }, "/whatsapp/connect/": { "post": { "operationId": "connectWhatsapp", "summary": "Connect a WhatsApp number", "description": "Start linking a WhatsApp number (Advanced and Enterprise plans). The call only starts it: the QR code (`login_method=qr`, default) or an 8-character pairing code (`login_method=phone`) arrives at `webhook_url` (see the `whatsappConnect` webhook), followed by `connected` or `not_connected`. A request not picked up within 10 minutes expires. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/whatsapp-connect-api/" }, "tags": [ "WhatsApp numbers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectWhatsappRequest" }, "examples": { "qr": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET" }, "summary": "QR code" }, "phone": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "login_method": "phone", "whatsapp_number": "919876543210", "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET" }, "summary": "Phone (pairing) code" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ConnectWhatsappRequest" } } } }, "responses": { "200": { "description": "Connection request created (`status: 1`) or refused (`status: 0`): `Auth Error` (also for an invalid JSON body), `Higher Subscription Required`, `WhatsApp Account Limit Reached. Upgrade your account to get more whatsapp limit`, `Already Connected With Given Number`; a non-POST request returns `{}`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WhatsappConnectStarted" }, { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "created": { "value": { "message": "Whatsapp Client Created", "whatsapp_client_id": 678, "login_method": "qr", "status": 1 }, "summary": "Created" }, "plan": { "value": { "status": 0, "message": "Higher Subscription Required" }, "summary": "Higher Subscription Required" } } } } }, "400": { "description": "`login_method must be 'qr' or 'phone'`, the phone-number format error for `login_method=phone`, `Auth Error: invalid api key` or `Invalid WhatsApp client`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" }, "badRow": { "value": { "status": 0, "message": "Invalid WhatsApp client" }, "summary": "Invalid WhatsApp client" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } }, "500": { "description": "`webhook_url` longer than 250 characters." } }, "security": [] } }, "/whatsapp-client/create/": { "post": { "operationId": "connectWhatsappAlias", "summary": "Connect a WhatsApp number (alias)", "description": "Identical alias of `POST /whatsapp/connect/`: same code, same responses. Used by the Python client.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/whatsapp-connect-api/" }, "tags": [ "WhatsApp numbers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectWhatsappRequest" }, "examples": { "qr": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET" }, "summary": "QR code" }, "phone": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "login_method": "phone", "whatsapp_number": "919876543210", "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET" }, "summary": "Phone (pairing) code" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ConnectWhatsappRequest" } } } }, "responses": { "200": { "description": "Connection request created (`status: 1`) or refused (`status: 0`): `Auth Error` (also for an invalid JSON body), `Higher Subscription Required`, `WhatsApp Account Limit Reached. Upgrade your account to get more whatsapp limit`, `Already Connected With Given Number`; a non-POST request returns `{}`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WhatsappConnectStarted" }, { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "created": { "value": { "message": "Whatsapp Client Created", "whatsapp_client_id": 678, "login_method": "qr", "status": 1 }, "summary": "Created" }, "plan": { "value": { "status": 0, "message": "Higher Subscription Required" }, "summary": "Higher Subscription Required" } } } } }, "400": { "description": "`login_method must be 'qr' or 'phone'`, the phone-number format error for `login_method=phone`, `Auth Error: invalid api key` or `Invalid WhatsApp client`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" }, "badRow": { "value": { "status": 0, "message": "Invalid WhatsApp client" }, "summary": "Invalid WhatsApp client" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } }, "500": { "description": "`webhook_url` longer than 250 characters." } }, "security": [] } }, "/whatsapp-client/list/": { "post": { "operationId": "listConnectedNumbers", "tags": [ "WhatsApp numbers" ], "summary": "List connected numbers", "description": "The WhatsApp numbers (and Telegram accounts) of the workspace that are connected right now, with the IDs to pass as `whatsapp_client`. A non-POST request returns `{}`; an unexpected server problem an HTML 500 page. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/whatsapp-client-list-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credentials" }, "examples": { "credentials": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Credentials" } } } }, "responses": { "200": { "description": "Connected numbers (`status: 1`), or `{\"message\": \"Auth Error\", \"status\": 0}`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConnectedNumbers" }, { "$ref": "#/components/schemas/ApiError" } ] }, "examples": { "list": { "value": { "message": "okay", "whatsapp_clients": [ { "id": 678, "whatsapp_client_id": 678, "whatsapp_client_number": "919876543210", "platform": "whatsapp", "is_connected": true }, { "id": 702, "whatsapp_client_id": 702, "whatsapp_client_number": "919812345670", "platform": "telegram", "is_connected": true } ], "status": 1 } } } } } }, "400": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } }, "500": { "description": "HTML error page instead of JSON (see the operation description).", "content": { "text/html": { "schema": { "type": "string" } } } } }, "security": [] } }, "/whatsapp-client/status/": { "post": { "operationId": "getConnectionStatus", "tags": [ "WhatsApp numbers" ], "summary": "Get connection status", "description": "Whether one WhatsApp number is connected. `Disconnected` also has `status: 0`, like an error, so check `message`. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/whatsapp-client-status-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappClientRequest" }, "examples": { "check": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678 } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WhatsappClientRequest" } } } }, "responses": { "200": { "description": "`Connected` (`status: 1`), `Disconnected` (`status: 0`), or an error with `status: 0`: `Auth Error`, `Auth Error 2` (the ID is not in this workspace), `Demo Account can not access apis`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleResult" }, "examples": { "connected": { "value": { "message": "Connected", "status": 1 }, "summary": "Connected" }, "disconnected": { "value": { "message": "Disconnected", "status": 0 }, "summary": "Disconnected" } } } } }, "400": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "403": { "description": "`client_id` is not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidClientId": { "value": { "status": 0, "message": "Invalid Client Id" }, "summary": "Invalid Client Id" } } } } } }, "security": [] } }, "/whatsapp/accounts/": { "post": { "operationId": "listWhatsappAccounts", "tags": [ "WhatsApp numbers" ], "summary": "List all WhatsApp numbers", "description": "Every WhatsApp number of the workspace that has not been deleted, connected or not, sorted by ID. A successful response has no `message` field.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/whatsapp-accounts-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credentials" }, "examples": { "credentials": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Credentials" } } } }, "responses": { "200": { "description": "The numbers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappAccounts" }, "examples": { "accounts": { "value": { "whatsapp_clients": [ { "whatsapp_client_id": 678, "whatsapp_number": "919876543210", "status": "connected" }, { "whatsapp_client_id": 702, "whatsapp_number": "919812345678", "status": "not_connected" } ], "status": 1 } } } } } }, "400": { "description": "Refused: `Auth Error - Please send correct API key and Client id`, `Invalid client id.`, `Auth Error: invalid api key`, or `This API key is not linked to a workspace. Create a new API key in WbizTool.`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" } } } } }, "405": { "description": "Not a POST request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "method": { "value": { "status": 0, "message": "Method not allowed, use POST" }, "summary": "Method not allowed, use POST" } } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal": { "value": { "status": 0, "message": "Internal error, please try again" }, "summary": "Internal error, please try again" } } } } } }, "security": [] } }, "/me/": { "post": { "operationId": "checkCredentials", "tags": [ "Account" ], "summary": "Check credentials", "description": "Confirm that `client_id` and `api_key` work together and, optionally, that a WhatsApp number ID belongs to the workspace. Sends nothing and does not count as a message.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/check-my-creds-api/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCredentialsRequest" }, "examples": { "withNumber": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY", "whatsapp_client": 678 }, "summary": "Key and number" }, "keyOnly": { "value": { "client_id": 12345, "api_key": "YOUR_API_KEY" }, "summary": "Key only" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CheckCredentialsRequest" } } } }, "responses": { "200": { "description": "Valid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialsOk" }, "examples": { "ok": { "value": { "status": 1, "message": "Okay", "name": "aman@example.com - 919876543210" } } } } } }, "400": { "description": "Refused: `Auth Error - Please send correct API key and Client id`, `Invalid client id.`, `Auth Error: invalid api key`, `This API key is not linked to a workspace. Create a new API key in WbizTool.`, `Invalid WhatsApp Client ID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badKey": { "value": { "status": 0, "message": "Auth Error: invalid api key" }, "summary": "Auth Error: invalid api key" }, "badNumber": { "value": { "status": 0, "message": "Invalid WhatsApp Client ID" }, "summary": "Invalid WhatsApp Client ID" } } } } }, "405": { "description": "Not a POST request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "method": { "value": { "status": 0, "message": "Method not allowed, use POST" }, "summary": "Method not allowed, use POST" } } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal": { "value": { "status": 0, "message": "Internal error, please try again" }, "summary": "Internal error, please try again" } } } } } }, "security": [] } }, "/status/": { "get": { "operationId": "getApiStatus", "tags": [ "Account" ], "summary": "API health check", "description": "Liveness check: needs no credentials, accepts any method and always returns the same body. It does not check credentials or whether a number is connected. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/check-my-creds-api/#checking-the-api-is-up" }, "security": [], "responses": { "200": { "description": "The API is reachable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 200 ] }, "data": { "type": "object" } } }, "examples": { "up": { "value": { "status": 200, "data": {} } } } } } } } } } }, "webhooks": { "messageStatus": { "post": { "operationId": "messageStatusWebhook", "tags": [ "Messages" ], "summary": "Message status event", "description": "Sent to the `webhook` URL of a message when it is sent, fails, is cancelled or expires. Respond with any 2xx; on a timeout (10 s), an unreachable endpoint, 429 or 5xx it is retried after 30 s, 1 min and 2 min. Only public addresses are called.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/send-message-api/#webhook" }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "msg_id", "status" ], "properties": { "msg_id": { "type": "integer", "description": "The `msg_id` returned when the message was sent." }, "status": { "type": "string", "enum": [ "SENT", "FAILED", "CANCELLED", "EXPIRED" ] } } }, "examples": { "sent": { "value": { "msg_id": 9817263, "status": "SENT" } } } } } }, "responses": { "200": { "description": "Any 2xx response acknowledges the event." } }, "security": [] } }, "whatsappConnect": { "post": { "operationId": "whatsappConnectWebhook", "tags": [ "WhatsApp numbers" ], "summary": "WhatsApp connect event", "description": "Sent to the `webhook_url` of Connect a WhatsApp number at each step: `qr_generated` (repeated every several seconds while waiting for a scan), `pairing_code` (once), then `connected` or `not_connected`. Not signed: put a secret in the URL and confirm with Connection status. Not retried; WbizTool waits up to 10 seconds.", "externalDocs": { "description": "Full documentation", "url": "https://wbiztool.com/docs/whatsapp-connect-api/#webhook-events" }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "status", "whatsapp_client_id" ], "properties": { "status": { "type": "string", "enum": [ "qr_generated", "pairing_code", "connected", "not_connected" ] }, "whatsapp_client_id": { "type": "integer" }, "qr_image": { "type": "string", "description": "Only with `qr_generated`: a `data:image/png;base64,…` URL." }, "pairing_code": { "type": "string", "description": "Only with `pairing_code`: the 8-character code." }, "whatsapp_number": { "type": "string", "description": "Only with `connected`: the linked number with its country code." } } }, "examples": { "connected": { "value": { "status": "connected", "whatsapp_client_id": 678, "whatsapp_number": "919876543210" } }, "pairing": { "value": { "status": "pairing_code", "whatsapp_client_id": 678, "pairing_code": "K5EWPGY5" } } } } } }, "responses": { "200": { "description": "Any HTTP status is accepted." } }, "security": [] } } }, "components": { "schemas": { "Credentials": { "type": "object", "description": "Your API credentials, sent in the request body (JSON or form fields) of every request that uses them. Both come from Settings → API keys in the dashboard. The API key decides which workspace the request acts on.", "required": [ "client_id", "api_key" ], "properties": { "client_id": { "type": "integer", "description": "Your API Client ID from Settings → API keys.", "examples": [ 12345 ] }, "api_key": { "type": "string", "description": "One of your API keys from the same page. Keep it secret.", "examples": [ "YOUR_API_KEY" ] } } }, "MsgType": { "type": "integer", "enum": [ 0, 1, 2 ], "default": 0, "description": "`0` text (default), `1` image, `2` file or document." }, "WhatsappClientId": { "type": "integer", "description": "ID of the WhatsApp number (or Telegram account) to send from, shown as \"ID …\" on the number's card on WhatsApp numbers in the dashboard.", "examples": [ 678 ] }, "Phone": { "type": "string", "description": "The recipient's WhatsApp number, with its country code (`919876543210`) or without it (`9876543210`) together with `country_code`. Spaces, `+`, `-`, `.`, brackets and a leading `00` are removed; a number written with `+` or `00` carries its own country code. From a Telegram account it can also be an `@username`, a `t.me/username` link or `tg:`.", "examples": [ "9876543210" ] }, "CountryCode": { "type": "string", "description": "Country calling code without `+`, for example `91` for India or `1` for the USA. Added in front of `phone` unless the number already starts with it or is written with `+` or `00` (with `91`, a 10-digit number always gets the prefix).", "examples": [ "91" ] }, "Msg": { "type": "string", "description": "Message text; required when `msg_type` is 0. For images and files it is the caption and can be empty. WhatsApp formatting works (`*bold*`, `_italic_`, `~strikethrough~`). `message` is accepted as an alias." }, "ImgUrl": { "type": "string", "format": "uri", "description": "Public `http`/`https` URL of the image. Required when `msg_type` is 1 (and no file is uploaded)." }, "FileUrl": { "type": "string", "format": "uri", "description": "Public `http`/`https` URL the file can be downloaded from directly. Required when `msg_type` is 2 (and no file is uploaded)." }, "FileName": { "type": "string", "description": "File name the recipient sees, such as `invoice-4821.pdf`. Sent in lower case, characters such as `& : ? * $ ;` become `_`, cut to 150 characters. With `msg_type` 2, `.pdf` is added when the extension is missing or not supported." }, "Webhook": { "type": "string", "format": "uri", "description": "Public URL that receives a form-encoded `POST` (`msg_id`, `status`) when the message is sent, fails, is cancelled or expires. See the `messageStatus` webhook." }, "ExpireAfterSeconds": { "type": "integer", "minimum": 1, "description": "Mark the message as expired (status `4`) if it has not been sent within this many seconds. Checked by a background job at least 30 seconds after the deadline.", "examples": [ 3600 ] }, "ApiError": { "type": "object", "description": "A failed request. `status` is `0` and `message` says why. (`Account Disabled` has no `status` field.)", "required": [ "message" ], "properties": { "status": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string" } } }, "DailyLimitError": { "type": "object", "description": "The sending number reached its fair-use limit of 1,000 messages in 24 hours. The refused message still has a `msg_id` and shows as failed.", "required": [ "status", "message", "code" ], "properties": { "status": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "daily_limit_reached" ] }, "msg_id": { "type": "integer" } } }, "MessageCreated": { "type": "object", "required": [ "status", "message", "msg_id" ], "properties": { "status": { "type": "integer", "enum": [ 1 ], "description": "`1`: the message was queued (not yet sent)." }, "message": { "type": "string", "enum": [ "Created" ] }, "msg_id": { "type": "integer", "description": "ID of the queued message. Save it to check the status or cancel it." } } }, "SimpleResult": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` success, `0` failure." }, "message": { "type": "string" } } }, "MediaFile": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID of the media file." }, "file_name": { "type": "string", "description": "Name the file is stored under (generated by WbizTool)." }, "original_file_name": { "type": "string", "description": "The name of the uploaded file." }, "file_url": { "type": "string", "format": "uri", "description": "Public download URL; use it as `img_url` or `file_url` when sending. Store it as it is (CDN or S3 host)." }, "file_type": { "type": "string", "enum": [ "image", "file" ] }, "file_size": { "type": "integer", "description": "Size in bytes." }, "file_size_display": { "type": "string", "examples": [ "242.5 KB" ] }, "mime_type": { "type": "string", "examples": [ "application/pdf" ] }, "is_image": { "type": "boolean" }, "file_extension": { "type": "string", "description": "Lower-case extension without the dot." }, "created_at": { "type": "string", "format": "date-time" }, "uploaded_by": { "type": [ "string", "null" ], "description": "Login username of the team member who uploaded the file. Not returned by the upload endpoint." }, "modified_at": { "type": "string", "format": "date-time", "description": "Only returned by the get-media endpoint." } } }, "MediaError": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "integer", "enum": [ 0 ] }, "message": { "type": "string" } } }, "Reminder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "The reminder name, or `Unnamed Reminder`." }, "to_number": { "type": "string", "description": "Phone number or group name the reminder is sent to." }, "message_template": { "type": "string" }, "msg_type": { "$ref": "#/components/schemas/MsgType" }, "msg_type_display": { "type": "string", "enum": [ "Text", "Image", "File" ] }, "img_url": { "type": [ "string", "null" ] }, "file_name": { "type": [ "string", "null" ] }, "cron_expression": { "type": "string" }, "next_run": { "type": "string", "description": "Next match as `YYYY-MM-DD HH:MM:SS UTC`, computed as if the reminder's timezone were UTC, or `Invalid cron`." }, "is_active": { "type": "boolean", "description": "`false` when paused." }, "whatsapp_client_id": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "description": "UTC, `YYYY-MM-DD HH:MM:SS`." } } }, "VerificationError": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "quota_exceeded" ], "description": "Only when the billing period's verifications are used up." }, "used": { "type": "integer" }, "limit": { "type": "integer" } } }, "VerificationNumberStatus": { "type": "string", "enum": [ "pending", "verified", "invalid", "unknown" ], "description": "`pending` waiting, `verified` on WhatsApp, `invalid` not on WhatsApp / not a valid number / check failed, `unknown` check cancelled by support." }, "SendMessageRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "whatsapp_client": { "$ref": "#/components/schemas/WhatsappClientId", "description": "Number to send from. Required if the workspace has more than one connected number; otherwise the only connected number is used (WhatsApp first)." }, "phone": { "$ref": "#/components/schemas/Phone" }, "group_name": { "type": "string", "description": "Exact WhatsApp group name, instead of `phone`. Send one or the other, never both." }, "country_code": { "$ref": "#/components/schemas/CountryCode" }, "msg_type": { "$ref": "#/components/schemas/MsgType" }, "msg": { "$ref": "#/components/schemas/Msg", "maxLength": 3000 }, "img_url": { "$ref": "#/components/schemas/ImgUrl" }, "file_url": { "$ref": "#/components/schemas/FileUrl" }, "file_name": { "$ref": "#/components/schemas/FileName" }, "expire_after_seconds": { "$ref": "#/components/schemas/ExpireAfterSeconds" }, "webhook": { "$ref": "#/components/schemas/Webhook" } }, "oneOf": [ { "required": [ "phone" ] }, { "required": [ "group_name" ] } ] } ] }, "FileUpload": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The image or file to send instead of `img_url`/`file_url`." } } }, "SendMessageMultipartRequest": { "allOf": [ { "$ref": "#/components/schemas/SendMessageRequest" }, { "$ref": "#/components/schemas/FileUpload" } ] }, "SendGroupMessageRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "group_name" ], "properties": { "whatsapp_client": { "$ref": "#/components/schemas/WhatsappClientId", "description": "Number to send from. Required unless the workspace has exactly one connected number." }, "group_name": { "type": "string", "description": "Name of the WhatsApp group exactly as WhatsApp shows it. Send it as a string." }, "msg_type": { "$ref": "#/components/schemas/MsgType" }, "msg": { "$ref": "#/components/schemas/Msg" }, "img_url": { "$ref": "#/components/schemas/ImgUrl" }, "file_url": { "$ref": "#/components/schemas/FileUrl" }, "file_name": { "$ref": "#/components/schemas/FileName" }, "expire_after_seconds": { "$ref": "#/components/schemas/ExpireAfterSeconds" }, "webhook": { "$ref": "#/components/schemas/Webhook" } } } ] }, "SendGroupMessageMultipartRequest": { "allOf": [ { "$ref": "#/components/schemas/SendGroupMessageRequest" }, { "$ref": "#/components/schemas/FileUpload" } ] }, "SendMultiMessageRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "whatsapp_client", "phone" ], "properties": { "whatsapp_client": { "$ref": "#/components/schemas/WhatsappClientId", "description": "Number to send from. Always required here." }, "phone": { "type": "string", "description": "Phone numbers and group names in one comma-separated string, e.g. `9876543210,9812345670,Sales Team Mumbai`. Not a JSON array. Text with letters is treated as a group name; numbers that are too short/long are skipped." }, "country_code": { "type": [ "string", "integer" ], "description": "Added in front of each phone number unless it already starts with it or is written with `+`/`00`.", "examples": [ "91" ] }, "msg_type": { "$ref": "#/components/schemas/MsgType" }, "msg": { "$ref": "#/components/schemas/Msg" }, "img_url": { "$ref": "#/components/schemas/ImgUrl" }, "file_url": { "$ref": "#/components/schemas/FileUrl" }, "file_name": { "$ref": "#/components/schemas/FileName" }, "webhook": { "$ref": "#/components/schemas/Webhook" } } } ] }, "ScheduleMessageRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "whatsapp_client", "date", "time" ], "properties": { "whatsapp_client": { "$ref": "#/components/schemas/WhatsappClientId", "description": "Number to send from. Always required here." }, "date": { "type": "string", "pattern": "^\\d{2}/\\d{2}/\\d{4}$", "description": "Day to send, `dd/mm/yyyy`.", "examples": [ "24/12/2026" ] }, "time": { "type": "string", "pattern": "^\\d{1,2}:\\d{2}$", "description": "Time to send, 24-hour `HH:MM`, no seconds.", "examples": [ "09:00" ] }, "timezone": { "type": "string", "default": "IST", "description": "IANA timezone name (e.g. `Asia/Kolkata`) or one of the abbreviations IST, UTC, GMT, EST, CST, MST, PST, CET, CEST, EET, EEST, JST, AEST, AEDT. Offsets such as `GMT+5:30` are refused.", "examples": [ "Asia/Kolkata" ] }, "phone": { "$ref": "#/components/schemas/Phone" }, "group_name": { "type": "string", "description": "WhatsApp group name instead of `phone`; never both." }, "country_code": { "$ref": "#/components/schemas/CountryCode" }, "msg_type": { "$ref": "#/components/schemas/MsgType" }, "msg": { "$ref": "#/components/schemas/Msg" }, "img_url": { "$ref": "#/components/schemas/ImgUrl" }, "file_url": { "$ref": "#/components/schemas/FileUrl" }, "file_name": { "$ref": "#/components/schemas/FileName" }, "webhook": { "$ref": "#/components/schemas/Webhook" } }, "oneOf": [ { "required": [ "phone" ] }, { "required": [ "group_name" ] } ] } ] }, "CancelMessageRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "msg_id" ], "properties": { "msg_id": { "type": "integer", "description": "The `msg_id` returned when the message was sent or scheduled.", "examples": [ 9817263 ] } } } ] }, "DeprecatedMessageStatusRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "msg_id" ], "properties": { "msg_id": { "type": "integer", "examples": [ 9817263 ] } } } ] }, "MessageHistoryRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "start_date", "end_date" ], "properties": { "start_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "First day, `DD-MM-YYYY` (midnight IST).", "examples": [ "01-09-2026" ] }, "end_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "End of the range, `DD-MM-YYYY`. This day itself is not included.", "examples": [ "08-09-2026" ] }, "whatsapp_client": { "$ref": "#/components/schemas/WhatsappClientId", "description": "Only messages from this number." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "200 messages per page. Only works as a JSON number; as a form field or string the response has `total` but an empty `history`." } } } ] }, "WhatsappClientRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "whatsapp_client" ], "properties": { "whatsapp_client": { "$ref": "#/components/schemas/WhatsappClientId", "description": "ID of the number to check." } } } ] }, "CheckCredentialsRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "whatsapp_client": { "$ref": "#/components/schemas/WhatsappClientId", "description": "Optional: also check that this number ID belongs to the key's workspace (deleted numbers fail)." } } } ] }, "ConnectWhatsappRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "webhook_url": { "type": "string", "format": "uri", "maxLength": 250, "description": "Receives the QR code or phone code and the result (see the `whatsappConnect` webhook). Without it you cannot get the QR code through the API." }, "login_method": { "type": "string", "enum": [ "qr", "phone" ], "default": "qr", "description": "`qr` sends a QR code to the webhook; `phone` an 8-character pairing code." }, "whatsapp_number": { "type": "string", "description": "Required with `login_method=phone`: full international number, country code first, no leading `0`. Ignored for `qr`.", "examples": [ "919876543210" ] }, "whatsapp_client_id": { "type": "integer", "description": "Reconnect this existing, disconnected number (keeps its ID). Leave out to add a new number." } } } ] }, "ListMediaRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "file_type": { "type": "string", "enum": [ "image", "file" ] }, "search": { "type": "string", "description": "Case-insensitive match on the original or stored name." } } } ] }, "UploadMediaRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "media_file" ], "properties": { "media_file": { "type": "string", "format": "binary", "description": "The file, up to 64 MB. Supported extensions: jpg jpeg png gif webp bmp, pdf doc docx xls xlsx ppt pptx txt csv, mp3 m4a wav ogg aac, mp4 mov avi, zip rar." } } } ] }, "CreateReminderRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "reminder_name", "phone", "message", "cron_expression" ], "properties": { "whatsapp_client": { "$ref": "#/components/schemas/WhatsappClientId", "description": "Number to send from. If left out (or not in the workspace), each run uses a number connected at that time." }, "reminder_name": { "type": "string", "examples": [ "Monthly rent reminder" ] }, "phone": { "type": "string", "description": "Recipient number with its country code (no separate `country_code`), a WhatsApp group name, or a Telegram `@username`/`t.me` link/`tg:`.", "examples": [ "919876543210" ] }, "message": { "type": "string", "description": "Message text; may contain template variables such as `{current_date_formatted}` or `{reminder_name}`." }, "cron_expression": { "type": "string", "description": "Five-field cron expression (minute hour day month weekday), no seconds or `@daily` shortcuts.", "examples": [ "0 10 1 * *" ] }, "timezone": { "type": "string", "default": "UTC", "description": "IANA timezone name such as `Asia/Kolkata`. Abbreviations like `IST` are refused.", "examples": [ "Asia/Kolkata" ] }, "msg_type": { "$ref": "#/components/schemas/MsgType", "description": "`0` text (default), `1` image, `2` file. Other values count as `0`." }, "img_url": { "type": "string", "format": "uri", "maxLength": 1000, "description": "Public URL of the image (`msg_type` 1) or of the file (`msg_type` 2). Downloaded on every run." }, "file_name": { "type": "string", "maxLength": 100, "description": "For `msg_type` 2: the file name with its extension." } } } ] }, "ListRemindersRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "50 per page." } } } ] }, "CancelReminderRequest": { "allOf": [ { "$ref": "#/components/schemas/Credentials" }, { "type": "object", "required": [ "reminder_id" ], "properties": { "reminder_id": { "type": [ "string", "integer" ], "pattern": "^\\d+$", "description": "ID from Create reminder or List reminders, as a whole number (string or number).", "examples": [ "3187" ] } } } ] }, "CreateVerificationRequest": { "type": "object", "required": [ "numbers" ], "properties": { "numbers": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Numbers with their country code. Spaces, `+`, `-`, brackets and one leading `0` are removed; results with fewer than 10 digits or other characters are dropped. Duplicates are kept." }, "campaign_name": { "type": "string", "maxLength": 500, "description": "Defaults to `API Verification `. Do not send `null`." } } }, "MultiMessageCreated": { "type": "object", "required": [ "status", "message", "msg_ids", "messages" ], "properties": { "status": { "type": "integer", "enum": [ 1 ] }, "message": { "type": "string", "examples": [ "Successfully created 3 messages" ] }, "msg_ids": { "type": "array", "items": { "type": "integer" } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "msg_id": { "type": "integer" }, "contact": { "type": "string", "description": "Number with country code applied, or the group name." }, "is_group": { "type": "boolean" } } } } } }, "MessageStatus": { "type": "object", "required": [ "status", "message", "status_text", "error" ], "properties": { "status": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "description": "The message's own status: `0` Created (queued), `1` Sent, `2` Failed, `3` Cancelled, `4` Expired. Also `0` for an unknown ID; check `message`." }, "status_text": { "type": "string", "enum": [ "Created", "Sent", "Failed", "Cancelled", "Expired", "pending" ], "description": "`pending` only with `Unknown message id`." }, "message": { "type": "string", "description": "Same as `status_text`, or `Unknown message id`." }, "error": { "type": [ "string", "null" ], "description": "Why the message failed; empty or null otherwise." } } }, "MessageHistory": { "type": "object", "required": [ "message", "status", "history" ], "properties": { "message": { "type": "string", "description": "`Success` (with `total`) when the request worked." }, "status": { "type": "integer", "enum": [ 0 ], "description": "Always `0`, even on success." }, "total": { "type": "integer", "description": "Messages in the range across all pages. Only on success." }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "msg_type": { "type": "string", "enum": [ "Text", "Image", "File" ] }, "contact": { "type": "string" }, "message_status": { "type": "string", "enum": [ "Pending", "Sent", "Delivered", "Read", "Failed", "Cancelled", "Expired" ], "description": "`Delivered` and `Read` are reserved and not currently recorded." } } } } } }, "MediaUploaded": { "type": "object", "required": [ "status", "message", "data" ], "properties": { "status": { "type": "integer", "enum": [ 1 ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MediaFile" } } }, "MediaList": { "type": "object", "required": [ "status", "message", "data" ], "properties": { "status": { "type": "integer", "enum": [ 1 ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "total_count": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "media_files": { "type": "array", "items": { "$ref": "#/components/schemas/MediaFile" } } } } } }, "ReminderCreated": { "type": "object", "required": [ "status", "message", "reminder_id" ], "properties": { "status": { "type": "integer", "enum": [ 1 ] }, "message": { "type": "string", "enum": [ "Reminder created successfully" ] }, "reminder_id": { "type": "integer" } } }, "ReminderList": { "type": "object", "required": [ "status", "message", "reminders", "total", "page", "page_size" ], "properties": { "status": { "type": "integer", "enum": [ 1 ] }, "message": { "type": "string", "enum": [ "Success" ] }, "reminders": { "type": "array", "items": { "$ref": "#/components/schemas/Reminder" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer", "enum": [ 50 ] } } }, "VerificationCreated": { "type": "object", "required": [ "status", "message", "campaign_id", "numbers_count", "numbers_submitted" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" }, "campaign_id": { "type": "integer" }, "numbers_count": { "type": "integer" }, "numbers_submitted": { "type": "array", "items": { "type": "string" } } } }, "VerificationStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "campaign_id": { "type": "integer" }, "campaign_name": { "type": "string" }, "overall_status": { "type": "string", "enum": [ "pending", "processing", "completed" ] }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "pending": { "type": "integer" }, "verified": { "type": "integer" }, "invalid": { "type": "integer" }, "completed_percentage": { "type": "number" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "status": { "$ref": "#/components/schemas/VerificationNumberStatus" }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } }, "created_at": { "type": "string", "format": "date-time" }, "last_updated": { "type": "string", "format": "date-time" } } }, "VerificationResults": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "total_count": { "type": "integer" }, "returned_count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "campaign_id": { "type": [ "integer", "null" ] }, "campaign_name": { "type": [ "string", "null" ] }, "number": { "type": "string" }, "status": { "$ref": "#/components/schemas/VerificationNumberStatus" }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "WhatsappConnectStarted": { "type": "object", "required": [ "status", "message", "whatsapp_client_id", "login_method" ], "properties": { "status": { "type": "integer", "enum": [ 1 ] }, "message": { "type": "string", "enum": [ "Whatsapp Client Created" ] }, "whatsapp_client_id": { "type": "integer" }, "login_method": { "type": "string", "enum": [ "qr", "phone" ] } } }, "ConnectedNumbers": { "type": "object", "required": [ "status", "message", "whatsapp_clients" ], "properties": { "status": { "type": "integer", "enum": [ 1 ] }, "message": { "type": "string", "enum": [ "okay" ] }, "whatsapp_clients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Same as `whatsapp_client_id`." }, "whatsapp_client_id": { "type": "integer" }, "whatsapp_client_number": { "type": "string" }, "platform": { "type": "string", "enum": [ "whatsapp", "telegram" ] }, "is_connected": { "type": "boolean", "description": "Always `true`." } } } } } }, "WhatsappAccounts": { "type": "object", "required": [ "status", "whatsapp_clients" ], "properties": { "status": { "type": "integer", "enum": [ 1 ] }, "whatsapp_clients": { "type": "array", "items": { "type": "object", "properties": { "whatsapp_client_id": { "type": "integer" }, "whatsapp_number": { "type": "string" }, "status": { "type": "string", "enum": [ "connected", "not_connected" ] } } } } } }, "CredentialsOk": { "type": "object", "required": [ "status", "message", "name" ], "properties": { "status": { "type": "integer", "enum": [ 1 ] }, "message": { "type": "string", "enum": [ "Okay" ] }, "name": { "type": "string", "description": "Username of the workspace's creator, plus ` - ` when `whatsapp_client` was sent." } } } }, "parameters": { "ClientIdQuery": { "name": "client_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Your API Client ID.", "example": 12345 }, "ApiKeyQuery": { "name": "api_key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Your API key (query strings are often logged; POST with JSON avoids that).", "example": "YOUR_API_KEY" }, "MediaId": { "name": "media_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID from Upload media or List media.", "example": 5122 } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Number verification endpoints only: `Authorization: Bearer YOUR_API_KEY` (a key from Settings → API keys). Other endpoints take `client_id` and `api_key` in the body (see the `Credentials` schema)." }, "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "Alternative for the GET number verification endpoints; the header keeps the key out of logs." } } } }