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 | | header_params | object | No | Value for a TEXT header with a {{var}} (max 1). Keyed by the variable's name for named templates, or "1" for positional. Falls back to template_params if omitted. | | 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 a TEXT header variable:

Meta allows at most one variable in a TEXT header. If your template's header is Our {{season}} sale is on!, supply the value via header_params:

{
  "phone_number": "919876543210",
  "template_name": "seasonal_promotion",
  "header_params": {
    "season": "Summer"
  },
  "template_params": {
    "customer_name": "John",
    "discount": "25%"
  }
}

For a positional header (Our {{1}} sale is on!), use "1" as the key. If you omit header_params, the value is looked up in template_params by the same name — convenient for named templates where the header variable doesn't collide with a body variable.

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

Note

The button_params key corresponds to the button's position index in the template (zero-based). For example, if the first button is a URL button with {{1}}, use "0" as the key. The value replaces the dynamic part of the URL.

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