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 body parameters
`button_params`	object	No	Dynamic URL button parameters (button index → value)
`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"
  }
}

With URL button parameters:

If your template has a URL button with a dynamic variable (e.g., https://example.com/track/{{1}}), provide the dynamic value via button_params. The key is the button index (starting from "0"):

{
  "contact_id": "uuid",
  "template_name": "order_shipped",
  "template_params": {
    "name": "John",
    "order_id": "12345"
  },
  "button_params": {
    "0": "12345"
  }
}

Response

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

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

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

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