Chatmaid Developers

Send Message

Current base URL: https://developers-api.chatmaid.net.

POST/v1/messages/sendAuth: API key

Send text or media WhatsApp message from a connected phone.

Request

Body: fromPhoneId, to
Optional: content, mediaUrls

Response

data.id
data.status
data.environment
data.sentAt

Send Request Contract

Parameter	In	Type	Required	Rules
`fromPhoneId`	Body	`string`	Yes	Must belong to your account.
`to`	Body	`string`	Yes	E.164 format (example: +15557654321).
`content`	Body	`string`	No	Max length 4096. Required if mediaUrls is empty.
`mediaUrls`	Body	`string[]`	No	Public HTTPS URLs. Required if content is empty.
`idempotencyKey`	Body	`string`	No	Max length 64. Same key returns original message.

Send Auth and Status Codes

Item	Value
Required scope	`messages:send`
Alternative scope	`messages:write`
Success code	`201`
Error codes	`400, 401, 403, 404, 429`

Initial status is typically sent, then progresses to delivered and read.

Send Message

curl -X POST https://developers-api.chatmaid.net/v1/messages/send \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fromPhoneId": "507f1f77bcf86cd799439011",
    "to": "+15557654321",
    "content": "Order received. We will update you soon."
  }'

Expected Send Response (201)

{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "content": "Order received. We will update you soon.",
    "environment": "test",
    "status": "sent",
    "createdAt": "2026-02-06T14:18:33.000Z"
  }
}

List and Read

GET/v1/messagesAuth: API key

List messages with pagination and optional filters.

Request

Query: phoneNumberId?, status?, page?, limit?

Response

data.data[]
data.pagination.page/limit/total/totalPages

GET/v1/messages/:messageIdAuth: API key

Get full message detail and status timestamps.

List Request Contract

Parameter	In	Type	Required	Rules
`phoneNumberId`	Query	`string`	No	Filter by sender phone ID.
`status`	Query	`string`	No	pending \| sent \| delivered \| read \| failed
`environment`	Query	`string`	No	live \| test. Defaults to API key environment.
`page`	Query	`number`	No	Integer >= 1. Default 1.
`limit`	Query	`number`	No	Integer 1..100. Default 20.

Get Request Contract

Parameter	In	Type	Required	Rules
`messageId`	Path	`string`	Yes	Message identifier (msg_*).
Required scope	-	`messages:read`	Yes	Required for both list and get endpoints.
Status codes	-	`200 \| 401 \| 403 \| 404 \| 429`	Yes	Common read endpoint responses.

List Messages

curl -X GET "https://developers-api.chatmaid.net/v1/messages?status=delivered&page=1&limit=20" \
  -H "Authorization: Bearer sk_test_xxx"

Expected List Response (200)

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "msg_abc123def456",
        "to": "+15557654321",
        "status": "delivered",
        "createdAt": "2026-02-06T14:18:33.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}

Get Message Status

curl -X GET https://developers-api.chatmaid.net/v1/messages/msg_abc123def456 \
  -H "Authorization: Bearer sk_test_xxx"

Expected Get Response (200)

{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "status": "read",
    "environment": "test",
    "createdAt": "2026-02-06T14:18:33.000Z",
    "sentAt": "2026-02-06T14:18:34.000Z",
    "deliveredAt": "2026-02-06T14:19:12.000Z",
    "readAt": "2026-02-06T14:20:03.000Z",
    "failedAt": null
  }
}

Status Lifecycle

Message states typically progress in this order:

pending
sent
delivered
read
failed (terminal failure path)

Media and Idempotency Notes

Use mediaUrls with public HTTPS links for media messages.
Send content + mediaUrls for media with caption.
Optionally include idempotencyKey (max 64 characters) when your client retries requests. Keys are scoped per account. Reusing a key returns the original message with its current data.

Dashboard Setup Prerequisite

Phone registration, WhatsApp connection, and API key creation are handled in dashboard UI. At runtime, integration clients can fetch connected phone IDs via /v1/phone-numbers.