Messages

Overview

The Messages API allows you to send various types of WhatsApp messages including text, media, templates, and interactive messages.

Get Messages

Retrieve messages for a specific contact.

GET /api/contacts/{id}/messages

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 50, max: 100)
before	string	Get messages before this message ID
after	string	Get messages after this message ID

Response

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "wa_message_id": "wamid.xxx",
        "contact_id": "uuid",
        "direction": "incoming",
        "type": "text",
        "content": {
          "text": "Hello!"
        },
        "status": "delivered",
        "timestamp": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 50
  }
}

Send Text Message

Send a text message to a contact.

POST /api/contacts/{id}/messages

Request Body

{
  "type": "text",
  "text": "Hello! How can I help you today?"
}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "wa_message_id": "wamid.xxx",
    "status": "sent",
    "timestamp": "2024-01-01T12:00:00Z"
  }
}

Send Template Message

Send a pre-approved template message.

POST /api/messages/template

Request Body

Field	Type	Required	Description
contact_id	string	One of contact_id or phone_number	UUID of existing contact
phone_number	string	One of contact_id or phone_number	Phone number (creates contact if not exists)
template_name	string	One of template_name or template_id	Name of the template
template_id	string	One of template_name or template_id	UUID of the template
template_params	object	No	Named or positional parameters
account_name	string	No	Specific WhatsApp account to use

Examples

Using phone number (creates contact if needed):

curl -X POST "http://your-server:8080/api/messages/template" \
  -H "X-API-Key: whm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "919876543210",
    "template_name": "hello_world"
  }'

{
  "phone_number": "919876543210",
  "template_name": "hello_world"
}

With named parameters:

If your template has placeholders like Hello {{name}}, your order {{order_id}} is ready:

{
  "contact_id": "uuid",
  "template_name": "order_confirmation",
  "template_params": {
    "name": "John",
    "order_id": "12345"
  }
}

With positional parameters:

{
  "phone_number": "919876543210",
  "template_name": "order_confirmation",
  "template_params": {
    "1": "John",
    "2": "12345"
  }
}

Response

{
  "status": "success",
  "data": {
    "message_id": "uuid",
    "phone_number": "919876543210",
    "status": "pending",
    "template_name": "order_confirmation"
  }
}

Tip

When using phone_number, a new contact is automatically created if one doesn’t exist for that number.

Caution

If required template parameters are missing, you’ll receive an error: "Missing template parameters: name, order_id. Expected parameters: [name, order_id]"

Send Media Message

Send an image, video, document, or audio message.

POST /api/messages/media

Request Body

{
  "contact_id": "uuid",
  "type": "image",
  "media_url": "https://example.com/image.jpg",
  "caption": "Check out this product!"
}

Supported Media Types

Type	Formats	Max Size
image	JPEG, PNG	5 MB
video	MP4, 3GPP	16 MB
audio	AAC, MP3, OGG	16 MB
document	PDF, DOC, XLS, PPT	100 MB

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "wa_message_id": "wamid.xxx",
    "status": "sent"
  }
}

Send Interactive Message

Send interactive messages with buttons or CTA URLs.

POST /api/contacts/{id}/messages

Button Message

Send a message with up to 3 quick reply buttons:

curl -X POST "http://your-server:8080/api/contacts/{contact_id}/messages" \
  -H "X-API-Key: whm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": "How would you like to proceed?",
      "buttons": [
        { "id": "yes", "title": "Yes" },
        { "id": "no", "title": "No" }
      ]
    }
  }'

{
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": "How would you like to proceed?",
    "buttons": [
      { "id": "yes", "title": "Yes" },
      { "id": "no", "title": "No" }
    ]
  }
}

CTA URL Button

Send a message with a call-to-action URL button:

curl -X POST "http://your-server:8080/api/contacts/{contact_id}/messages" \
  -H "X-API-Key: whm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "interactive",
    "interactive": {
      "type": "cta_url",
      "body": "Click below to view your order details",
      "button_text": "View Order",
      "url": "https://example.com/orders/12345"
    }
  }'

{
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": "Click below to view your order details",
    "button_text": "View Order",
    "url": "https://example.com/orders/12345"
  }
}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "wa_message_id": "wamid.xxx",
    "status": "sent"
  }
}

Note

Button titles have a maximum length of 20 characters. Button IDs are returned when the user clicks a button.

Mark Message as Read

Mark a message as read.

PUT /api/messages/{id}/read

Response

{
  "status": "success",
  "data": null
}

Message Status

Messages go through the following status flow:

Status	Description
pending	Message queued for sending
sent	Message sent to WhatsApp servers
delivered	Message delivered to recipient’s device
read	Message read by recipient
failed	Message failed to send

Note

Status updates are delivered via webhooks in real-time. Configure your webhook endpoint to receive these updates.

Message Types

Text

Plain text messages

Image

JPEG, PNG images with optional caption

Video

MP4 videos with optional caption

Document

PDF, Word, Excel, and other documents

Audio

Voice messages and audio files

Template

Pre-approved message templates

Interactive

Buttons, lists, and reply buttons

Flow

WhatsApp Flows