Messages API

List messages

GET /api/whatsapp/messages?conversationId=uuid

Query parameters:

Parameter	Type	Description
conversationId	string	Required — conversation to fetch messages for
limit	number	Results per page (default: 50)
before	string	Cursor for pagination (message ID)

Response:

{
  "data": [
    {
      "id": "msg_abc123",
      "waMessageId": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYZ...",
      "conversationId": "conv_def456",
      "direction": "inbound",
      "type": "text",
      "content": {
        "text": "Hi, I'd like to check my order status"
      },
      "status": "delivered",
      "timestamp": "2026-05-16T10:30:00.000Z",
      "senderId": "contact_789"
    },
    {
      "id": "msg_abc124",
      "waMessageId": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYY...",
      "conversationId": "conv_def456",
      "direction": "outbound",
      "type": "text",
      "content": {
        "text": "Hello! I'd be happy to help. Could you provide your order number?"
      },
      "status": "read",
      "timestamp": "2026-05-16T10:30:05.000Z",
      "senderId": null
    }
  ],
  "total": 48,
  "page": 1,
  "hasNext": false
}

Message types and content shapes:

Text message:

{
  "type": "text",
  "content": {
    "text": "Hello, how can I help?"
  }
}

Image message:

{
  "type": "image",
  "content": {
    "url": "https://cdn.example.com/media/img_001.jpg",
    "mimeType": "image/jpeg",
    "caption": "Product photo"
  }
}

Document message:

{
  "type": "document",
  "content": {
    "url": "https://cdn.example.com/media/doc_001.pdf",
    "mimeType": "application/pdf",
    "filename": "invoice_2026.pdf"
  }
}

Audio message:

{
  "type": "audio",
  "content": {
    "url": "https://cdn.example.com/media/audio_001.ogg",
    "mimeType": "audio/ogg"
  }
}

Video message:

{
  "type": "video",
  "content": {
    "url": "https://cdn.example.com/media/video_001.mp4",
    "mimeType": "video/mp4",
    "caption": "Demo video"
  }
}

Location message:

{
  "type": "location",
  "content": {
    "latitude": 25.2048,
    "longitude": 55.2708,
    "name": "Dubai Mall",
    "address": "Financial Centre Rd, Dubai"
  }
}

Message statuses:

Status	Description
sent	Message sent to WhatsApp servers
delivered	Message delivered to recipient's device
read	Message read by recipient
failed	Message delivery failed

---

Send message

POST /api/whatsapp/messages/send

Send text message

Request:

{
  "to": "+1234567890",
  "type": "text",
  "text": "Hello! How can I help you?"
}

Response (success):

{
  "success": true,
  "data": {
    "vendorMessageId": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYZ...",
    "waMessageId": "msg_abc125",
    "status": "sent",
    "conversationId": "conv_def456",
    "contactId": "contact_789"
  }
}

Send template message

Request:

{
  "to": "+1234567890",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": "en",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "ORD-456" }
        ]
      }
    ]
  }
}

Response (success):

{
  "success": true,
  "data": {
    "vendorMessageId": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYY...",
    "waMessageId": "msg_abc126",
    "status": "sent",
    "conversationId": "conv_def456",
    "contactId": "contact_789"
  }
}

Send media message

Request (image):

{
  "to": "+1234567890",
  "type": "image",
  "image": {
    "url": "https://example.com/product.jpg",
    "caption": "Here's the product you asked about"
  }
}

Response (success):

{
  "success": true,
  "data": {
    "vendorMessageId": "wamid.HBgLMTIzNDU2Nzg5MBUCABIZZ...",
    "waMessageId": "msg_abc127",
    "status": "sent",
    "conversationId": "conv_def456",
    "contactId": "contact_789"
  }
}

---

Error responses

Validation error (400):

{
  "success": false,
  "error": "Missing required field: to"
}

Contact not found (404):

{
  "success": false,
  "error": "Contact not found for the given phone number"
}

Rate limited (429):

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 60 seconds."
}

WhatsApp API error (502):

{
  "success": false,
  "error": "WhatsApp API error: Message failed to send",
  "details": {
    "code": 131047,
    "title": "Re-engagement message"
  }
}