API Documentation

WhatsApp Messages

Messages are the core functionality of the WhatsApp API, allowing you to send various types of content to recipients.

Sending Messages

You can send different types of messages using our API, including text, media, and interactive messages.

Send Text Message

POST /api/v1/messages/text

Sends a simple text message to a WhatsApp recipient.

Request Parameters

Parameter Type Required Description
sessionId string Required ID of the WhatsApp session to use
to string Required Recipient's phone number in international format (e.g., 14155552671)
text string Required The text message to send
quotedMessageId string Optional ID of a message to quote/reply to

Response

{
  "success": true,
  "data": {
    "messageId": "msg_abc123",
    "status": "sent",
    "timestamp": "2025-09-14T15:45:30Z"
  }
}

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_123abc",
    "to": "14155552671",
    "text": "Hello from the WhatsApp API!"
  }' \
  https://api.messaging.com/v1/messages/text

Send Media Message

POST /api/v1/messages/media

Sends a media message (image, video, document, audio) to a WhatsApp recipient.

Request Parameters

Parameter Type Required Description
sessionId string Required ID of the WhatsApp session to use
to string Required Recipient's phone number in international format
mediaType string Required Type of media: image, video, document, audio
media string Required URL or base64 data of the media
caption string Optional Caption for the media (not applicable for audio)
filename string Optional Filename for document type

Response

{
  "success": true,
  "data": {
    "messageId": "msg_def456",
    "status": "sent",
    "timestamp": "2025-09-14T15:50:00Z",
    "mediaType": "image"
  }
}

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_123abc",
    "to": "14155552671",
    "mediaType": "image",
    "media": "https://example.com/image.jpg",
    "caption": "Check out this image!"
  }' \
  https://api.messaging.com/v1/messages/media

Send Location Message

POST /api/v1/messages/location

Sends a location message to a WhatsApp recipient.

Request Parameters

Parameter Type Required Description
sessionId string Required ID of the WhatsApp session to use
to string Required Recipient's phone number in international format
latitude number Required Latitude coordinate
longitude number Required Longitude coordinate
name string Optional Name of the location
address string Optional Address of the location

Response

{
  "success": true,
  "data": {
    "messageId": "msg_ghi789",
    "status": "sent",
    "timestamp": "2025-09-14T15:55:00Z"
  }
}

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_123abc",
    "to": "14155552671",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "San Francisco",
    "address": "San Francisco, CA, USA"
  }' \
  https://api.messaging.com/v1/messages/location

Send Button Message

POST /api/v1/messages/buttons

Sends an interactive button message to a WhatsApp recipient.

Request Parameters

Parameter Type Required Description
sessionId string Required ID of the WhatsApp session to use
to string Required Recipient's phone number in international format
text string Required Message text
buttons array Required Array of button objects (max 3)
footer string Optional Footer text for the message

Button Object

Parameter Type Required Description
id string Required Unique identifier for the button
text string Required Button text (max 20 characters)

Response

{
  "success": true,
  "data": {
    "messageId": "msg_jkl012",
    "status": "sent",
    "timestamp": "2025-09-14T16:00:00Z"
  }
}

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_123abc",
    "to": "14155552671",
    "text": "Please select an option:",
    "buttons": [
      {"id": "btn1", "text": "Yes"},
      {"id": "btn2", "text": "No"},
      {"id": "btn3", "text": "Maybe"}
    ],
    "footer": "Powered by WhatsApp API"
  }' \
  https://api.messaging.com/v1/messages/buttons

Message Status

Messages can have the following statuses:

  • sent: Message has been sent from your WhatsApp client
  • delivered: Message has been delivered to the recipient's device
  • read: Message has been read by the recipient
  • failed: Message failed to send

Get Message Status

GET /api/v1/messages/{messageId}

Retrieves the current status of a message.

Path Parameters

Parameter Type Required Description
messageId string Required ID of the message to check

Response

{
  "success": true,
  "data": {
    "messageId": "msg_abc123",
    "status": "delivered",
    "timestamp": "2025-09-14T15:45:30Z",
    "deliveredAt": "2025-09-14T15:45:35Z",
    "readAt": null
  }
}

cURL Example

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.messaging.com/v1/messages/msg_abc123

Message Limits

The number of messages you can send depends on your subscription plan:

Plan Daily Message Limit
Free 50
Basic 1,000
Premium 10,000
Enterprise Unlimited

Important Notes

  • Messages can only be sent to numbers that have WhatsApp installed
  • The recipient must have your number saved in their contacts to receive messages if you're using a personal WhatsApp account
  • Media messages have size limits: Images (5MB), Videos (16MB), Documents (100MB), Audio (16MB)
  • WhatsApp may block accounts that send spam or unwanted messages