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
`limit`	integer	Items per page (default: 50, max: 100)
`before_id`	string	Load older messages before this message ID (cursor-based pagination)
`account`	string	Filter messages by a specific WhatsApp account

Response

Standard List Response (Default / Page 1)

{
  "status": "success",
  "data": {
    "messages": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "contact_id": "880e8400-e29b-41d4-a716-446655440000",
        "direction": "incoming",
        "message_type": "text",
        "content": {
          "body": "Hello! How can I help you?"
        },
        "status": "read",
        "wamid": "wamid.HBgLMTIzNDU2Nzg5MEUCGQYSFDM5...",
        "whatsapp_account": "default_account",
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:01:00Z"
      }
    ],
    "total": 245
  }
}

Cursor-Based Paginated Response (When using `before_id`)

{
  "status": "success",
  "data": {
    "messages": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "contact_id": "880e8400-e29b-41d4-a716-446655440000",
        "direction": "incoming",
        "message_type": "text",
        "content": {
          "body": "Older message content"
        },
        "status": "read",
        "wamid": "wamid.HBgLMTIzNDU2Nzg5MEUCGQYSFDM5...",
        "whatsapp_account": "default_account",
        "created_at": "2024-01-01T11:00:00Z",
        "updated_at": "2024-01-01T11:00:00Z"
      }
    ],
    "has_more": true
  }
}

Send Text Message

Send a text message to a contact.

POST /api/contacts/{id}/messages

Request Body

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

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "contact_id": "880e8400-e29b-41d4-a716-446655440000",
    "direction": "outgoing",
    "message_type": "text",
    "content": {
      "body": "Hello! How can I help you today?"
    },
    "status": "pending",
    "whatsapp_account": "default_account",
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Send Template Message

Send a pre-approved template message to a contact or phone number. Supports templates with optional header media (image, video, document), TEXT header variables, and dynamic URL buttons.

If including a raw media file for a template header, use multipart/form-data. Otherwise, use application/json.

POST /api/messages/template

Request Payload Fields

Field	Type	Required	Description
`contact_id`	string	One of contact_id or phone_number	UUID of the recipient 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	Key-value pairs for body parameters
`header_params`	object	No	Key-value pairs for TEXT header variables
`button_params`	object	No	Key-value pairs for dynamic URL buttons (button index → parameter value)
`account_name`	string	No	Specific WhatsApp account to use
`header_media_id`	string	No	Already-uploaded WhatsApp media ID for header
`header_media_url`	string	No	URL of media to download and upload to WhatsApp
`header_media_filename`	string	No	Filename (required for DOCUMENT headers)
`header_file`	file	No	Raw header media file (only when using `multipart/form-data`)

Examples

Using JSON:

curl -X POST "https://dashboard.cloudwa.net/api/messages/template" \
  -H "X-API-Key: whm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "1234567890",
    "template_name": "seasonal_promotion",
    "template_params": {
      "customer_name": "John",
      "discount": "20%"
    },
    "header_params": {
      "season": "Summer"
    },
    "button_params": {
      "0": "promo-2024"
    }
  }'

Using multipart/form-data (for raw file upload):

curl -X POST "https://dashboard.cloudwa.net/api/messages/template" \
  -H "X-API-Key: whm_your_api_key" \
  -F "phone_number=1234567890" \
  -F "template_name=order_receipt" \
  -F "template_params={\"customer_name\":\"John\"}" \
  -F "header_file=@/path/to/invoice.pdf" \
  -F "header_media_filename=invoice.pdf"

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "contact_id": "880e8400-e29b-41d4-a716-446655440000",
    "direction": "outgoing",
    "message_type": "template",
    "content": {
      "body": "Hello John, your Summer promo code is promo-2024!"
    },
    "status": "pending",
    "whatsapp_account": "default_account",
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Send Media Message

Upload and send a media message (image, video, document, or audio) directly. This endpoint accepts multipart/form-data request payloads.

POST /api/messages/media

Multipart Form Fields

Parameter	Type	Required	Description
`file`	file binary	Yes	The file payload to upload and send
`contact_id`	string	Yes	UUID of the recipient contact
`type`	string	No	Media type: `image`, `video`, `audio`, `document` (default: `image`)
`caption`	string	No	Optional caption for the media (images and videos only)
`whatsapp_account`	string	No	Specific WhatsApp account to use

Example

curl -X POST "https://dashboard.cloudwa.net/api/messages/media" \
  -H "X-API-Key: whm_your_api_key" \
  -F "contact_id=880e8400-e29b-41d4-a716-446655440000" \
  -F "type=image" \
  -F "caption=Here is your product image!" \
  -F "file=@/path/to/product.png"

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": "550e8400-e29b-41d4-a716-446655440000",
    "contact_id": "880e8400-e29b-41d4-a716-446655440000",
    "direction": "outgoing",
    "message_type": "image",
    "media_url": "/media/images/abcdef.png",
    "media_mime_type": "image/png",
    "media_filename": "product.png",
    "content": {
      "body": "Here is your product image!"
    },
    "status": "pending",
    "whatsapp_account": "default_account",
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Send Interactive Message

Send interactive messages with reply buttons or CTA (Call to Action) URL buttons.

POST /api/contacts/{id}/messages

Request Body (Button Message)

Send a message with up to 3 quick reply buttons:

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

Request Body (CTA URL Button Message)

Send a message with a Call to Action URL button:

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

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "contact_id": "880e8400-e29b-41d4-a716-446655440000",
    "direction": "outgoing",
    "message_type": "interactive",
    "interactive_data": {
      "type": "button",
      "body": "How would you like to proceed?",
      "buttons": [
        { "id": "yes", "title": "Yes" },
        { "id": "no", "title": "No" }
      ]
    },
    "status": "pending",
    "whatsapp_account": "default_account",
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Mark Message as Read

Mark a message as read.

PUT /api/messages/{id}/read

Response

{
  "status": "error",
  "message": "Not implemented yet"
}

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

Messages

Overview

Get Messages

Query Parameters

Response

Standard List Response (Default / Page 1)

Cursor-Based Paginated Response (When using before_id)

Send Text Message

Request Body

Response

Send Template Message

Request Payload Fields

Examples

Response

Send Media Message

Multipart Form Fields

Example

Supported Media Types

Response

Send Interactive Message

Request Body (Button Message)

Request Body (CTA URL Button Message)

Response

Mark Message as Read

Response

Message Status

Message Types

Cursor-Based Paginated Response (When using `before_id`)