> For the complete documentation index, see [llms.txt](https://help.botpenguin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.botpenguin.com/api-documentation/whatsapp-cloud-api/post-send-whatsapp-message.md). # POST — Send WhatsApp Message ### Overview | Property | Details | | ----------------- | ------------------------------------------------------------------- | | **Method** | `POST` | | **Endpoint** | `https://api.v7.botpenguin.com/whatsapp-automation/wa/send-message` | | **Base URL** | `https://api.v7.botpenguin.com` | | **API Version** | v7 | | **Auth Required** | Yes — API Key | | **Content-Type** | `application/json` | *** ### Authentication BotPenguin APIs use an **API Key** for authentication. Pass it in both the request header and as a query parameter for this endpoint. | Method | Location | Key | Value | | ------- | --------------- | -------- | ----------------------- | | API Key | Request Header | `apiKey` | Your BotPenguin API Key | | API Key | Query Parameter | `apiKey` | Your BotPenguin API Key | {% hint style="info" %} 🔑 **Where to get your API Key:** Navigate to **Dashboard → Settings → API Access**. For full auth setup, see the [API Authentication Guide](/bots/whatsapp-bot/whatapp-chatbot-settings/api-key-settings.md). {% endhint %} *** ### Request #### Headers | Header | Required | Value | | -------------- | -------- | ---------------------------------- | | `apiKey` | ✅ Yes | Your BotPenguin WA Chatbot API Key | | `Content-Type` | ✅ Yes | `application/json` | #### Query Parameters | Parameter | Type | Required | Description | | --------- | -------- | -------- | ---------------------------------- | | `apiKey` | `string` | ✅ Yes | Your BotPenguin WA Chatbot API Key | *** #### Request Body The request body differs based on the message type. Both variants are documented below. **Plain Text Message** ```json { "userName": "Test", "wa_id": "910987654321", "type": "text", "message": { "text": "Hi, how can we help you today?" }, "tags": ["support", "inbound"] } ``` **Media Message (Image)** ```json { "userName": "Test", "wa_id": "910987654321", "type": "image", "message": { "source": "https://example.com/image.jpg", "label": "Here is your product brochure." }, "tags": ["marketing"] } ``` **Body Fields** | Field | Type | Required | Applicable When | Description | | ---------------- | -------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `userName` | `string` | ✅ Yes | Always | Display name of the recipient. Used for internal reference. | | `wa_id` | `string` | ✅ Yes | Always | Recipient's WhatsApp number **with country code, without `+`**. Example: `910987654321` for India. | | `type` | `string` | ✅ Yes | Always | Type of message. Accepted values: `text`, `image`. | | `message.text` | `string` | ✅ Yes | `type: text` | The text content of the message. | | `message.source` | `string` | ✅ Yes | `type: image` | Publicly accessible URL of the image. Supported formats: `jpg`, `png`, and all formats supported by Meta. | | `message.label` | `string` | ❌ No | `type: image` | Caption displayed below the image. | | `tags` | `array` | ❌ No | Always | Labels to assign to this conversation for organisation and filtering. Pass an empty array `[]` if unused. | *** #### Example Requests **Send a Text Message** ```bash curl --location 'https://api.v7.botpenguin.com/whatsapp-automation/wa/send-message?apiKey=YOUR_API_KEY' \ --header 'apiKey: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "userName": "Test", "wa_id": "910987654321", "type": "text", "message": { "text": "Hi, how can we help you today?" }, "tags": ["support"] }' ``` **Send an Image Message** ```bash curl --location 'https://api.v7.botpenguin.com/whatsapp-automation/wa/send-message?apiKey=YOUR_API_KEY' \ --header 'apiKey: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "userName": "Test", "wa_id": "910987654321", "type": "image", "message": { "source": "https://example.com/brochure.jpg", "label": "Here is your product brochure." }, "tags": ["marketing"] }' ``` *** ### Response #### Success — `200 OK` ```json { "success": true, "data": { "_id": "6a2beec7164060995f1393c3", "_user": "5fed38e56fb193dcc6c933f5", "_bot": "678a12ce47a2bd8d197eb432", "_subscriber": "68999ca5af107f2f67be147b", "type": "text", "trigger": "message", "text": "hello API Testing", "status": "SENT", "sentBy": "bot", "isTemplateSentFromInbox": false, "deliveryStatus": [], "isPaid": true, "forwarded": false, "starredBy": [], "links": [], "questionType": "", "mappedAttributeKeys": [], "senderInfo": { "userType": "BOT" }, "isErrorMessage": false, "singleChoiceOptions": [], "medias": [], "translatedMessages": [] } } ``` **Response Fields** **Root Level** | Field | Type | Description | | --------- | --------- | ------------------------------------------------ | | `success` | `boolean` | `true` if the message was accepted for delivery. | | `data` | `object` | Full record of the sent message. | **`data` Object** | Field | Type | Description | | ------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | | `_id` | `string` | Unique identifier of this message record. | | `_user` | `string` | ID of the BotPenguin user (account) that sent the message. | | `_bot` | `string` | ID of the bot through which the message was sent. | | `_subscriber` | `string` | ID of the subscriber (contact) who received the message. | | `type` | `string` | Message type as sent — `text` or `image`. | | `trigger` | `string` | What triggered this message. Value: `message` for API-initiated sends. | | `text` | `string` | The text content of the message as delivered. | | `status` | `string` | Delivery status at send time. Value: `SENT`. | | `sentBy` | `string` | Who sent the message. Value: `bot` for API sends. | | `isTemplateSentFromInbox` | `boolean` | `true` if this was a template sent from the inbox UI. `false` for API sends. | | `deliveryStatus` | `array` | Delivery receipt events from Meta. Empty at time of send; updated asynchronously. | | `isPaid` | `boolean` | Indicates whether this was a paid message under Meta's pricing model. | | `forwarded` | `boolean` | `true` if the message was forwarded. | | `starredBy` | `array` | List of user IDs who starred this message. Empty if none. | | `links` | `array` | URLs extracted from the message content, if any. | | `questionType` | `string` | Set when the message is part of a bot flow question. Empty for direct API sends. | | `mappedAttributeKeys` | `array` | Subscriber attribute keys mapped during this message. Empty for direct API sends. | | `senderInfo.userType` | `string` | Type of sender. Value: `BOT` for API sends. | | `isErrorMessage` | `boolean` | `true` if this message represents an error notification. | | `singleChoiceOptions` | `array` | Quick reply options, if the message contains them. Empty for plain sends. | | `medias` | `array` | Media attachments included in the message. Empty for text messages. | | `translatedMessages` | `array` | Translated versions of the message, if translation is enabled. | | `deletedBy` | `object` | *(Conditional)* Present only if the message has been deleted. Contains `userType` and `at` (deletion timestamp). | *** ### HTTP Status Codes | Code | Status | Meaning | | ----- | --------------------- | ------------------------------------------------------------------------ | | `200` | OK | Message sent successfully. | | `400` | Bad Request | Missing or invalid parameters. Check `wa_id` format and required fields. | | `401` | Unauthorized | API key is missing, invalid, or expired. | | `403` | Forbidden | Valid key but account lacks WhatsApp send permissions. | | `404` | Not Found | Bot or subscriber not found for the given credentials. | | `429` | Too Many Requests | Rate limit exceeded. Retry after the indicated window. | | `500` | Internal Server Error | Server-side error. Contact support if it persists. | *** ### Error Handling Errors on this endpoint originate from **Meta's WhatsApp Cloud API**. When a message fails to send, the error code and message are returned directly from Meta's infrastructure. For the full list of Meta WhatsApp error codes, their meanings, and recommended resolutions, refer to the official Meta documentation: 📄 [WhatsApp On-Premises Error Codes — Meta for Developers](https://developers.facebook.com/docs/whatsapp/on-premises/errors) *** ### Rate Limits This endpoint is limited to **100 requests per minute** per API key, across all plans. Exceeding this returns `429 Too Many Requests`. Use the `Retry-After` response header (in seconds) to schedule your retry. *** ### Related APIs {% content-ref url="/pages/R57I56HtVGIHIq7oAH9i" %} [POST WhatsApp Template Message](/api-documentation/whatsapp-cloud-api/post-whatsapp-template-message.md) {% endcontent-ref %} {% content-ref url="/pages/3sEKIiAP3jQ7YKjbpyLy" %} [GET — Templates List](/api-documentation/whatsapp-cloud-api/get-templates-list.md) {% endcontent-ref %} {% content-ref url="/pages/FbSqv0h0CyVYiQGR5XW4" %} [API Key Settings](/bots/whatsapp-bot/whatapp-chatbot-settings/api-key-settings.md) {% endcontent-ref %} *For questions or issues, contact* [*support@botpenguin.com*](mailto:support@botpenguin.com)