POST — Send WhatsApp Message

Use this API to send a WhatsApp message to a specific user — either a plain text message or a media message with an image and caption. The recipient is identified by their WhatsApp number with country

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

🔑 Where to get your API Key: Navigate to Dashboard → Settings → API Access. For full auth setup, see the API Authentication Guide.

---

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

{
  "userName": "Test",
  "wa_id": "910987654321",
  "type": "text",
  "message": {
    "text": "Hi, how can we help you today?"
  },
  "tags": ["support", "inbound"]
}

Media Message (Image)

{
  "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

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

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

{
  "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

---

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

POST WhatsApp Template MessageGET — Templates ListAPI Key Settings

For questions or issues, contact [e-mail]