API Reference

Base URL:

https://developers-api.chatmaid.net

Integration host: https://developers-api.chatmaid.net.

POST /v1/messages/send

Create a new outbound message.

Request Contract

Parameter	In	Type	Required	Rules
`fromPhoneId`	Body	`string`	Yes	Sender phone, given as its E.164 number (recommended) or its dashboard ID.
`to`	Body	`string`	Yes	E.164 phone number (example: +15551234567), or a group JID (example: 120363043211234567@g.us) from GET /v1/groups.
`content`	Body	`string`	No	Max length 4096. Required if mediaUrls is empty.
`mediaUrls`	Body	`string[]`	No	Public HTTPS URLs only. Required if content is empty.
`idempotencyKey`	Body	`string`	No	Max length 64. Reuse returns the original message.

Authorization and Scopes

Requirement	Value
Auth header	`Authorization: Bearer sk_test_* \| sk_live_*`
Any required scope	`messages:send`
Alternative accepted scope	`messages:write`

Status Codes

Code	Meaning
`201`	Message accepted.
`400`	Validation error or phone not connected for live key.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`404`	fromPhoneId not found in account.
`429`	Rate limit exceeded for this API key.

Response Fields

Field	Type	Notes
`data.id`	`string`	Message ID (msg_*).
`data.isGroup`	`boolean`	True when the recipient is a WhatsApp group.
`data.groupId`	`string \| null`	Full group JID when isGroup is true.
`data.status`	`pending\|sent\|delivered\|read\|failed`	Status after a successful send is sent; transitions to delivered/read as WhatsApp receipts arrive. Failed sends are marked failed.
`data.sentAt`	`string \| null`	Set when message is marked sent.
`data.deliveredAt`	`string \| null`	Set when WhatsApp confirms delivery to the recipient.
`data.readAt`	`string \| null`	Set when the recipient reads the message (requires read receipts).
`data.errorCode`	`string \| null`	Stable error code, populated when status is failed. See Error codes.
`data.errorMessage`	`string \| null`	Human-readable explanation, populated when status is failed.

When a message ends in failed, errorCode is one of the following stable values. errorMessage provides a human-readable explanation. These are the only values that will ever appear — internal service details are never surfaced.

`errorCode`	Meaning
`NOT_CONNECTED`	The sending phone number is not connected to WhatsApp.
`INVALID_RECIPIENT`	The recipient is not a valid WhatsApp user or group.
`RECIPIENT_NOT_REACHABLE`	The message could not be delivered. The recipient may need to message you first, or may not be reachable on WhatsApp.
`NOT_GROUP_MEMBER`	The sender is not a member of the group or is not allowed to post in it.
`RATE_LIMITED`	Sending is temporarily rate-limited by WhatsApp. Retry later.
`NOT_AUTHORIZED`	The WhatsApp session is no longer authorized. Reconnect the phone number.
`MEDIA_ERROR`	The media could not be fetched or is not a supported type.
`TIMEOUT`	WhatsApp did not respond in time; delivery is indeterminate.
`SERVICE_UNAVAILABLE`	The WhatsApp service is temporarily unavailable. Retry shortly.
`INTERNAL_ERROR`	An unexpected error occurred.

curl -X POST https://developers-api.chatmaid.net/v1/messages/send \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"fromPhoneId":"+15551234567","to":"+15557654321","content":"Hello"}'

{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "isGroup": false,
    "groupId": null,
    "content": "Hello",
    "mediaUrls": [],
    "status": "sent",
    "createdAt": "2026-02-06T14:18:33.000Z",
    "sentAt": "2026-02-06T14:18:33.120Z",
    "failedAt": null,
    "errorCode": null,
    "errorMessage": null
  }
}

For live keys, the response is returned with status: "pending" and is updated to sent or failed once the WhatsApp microservice confirms delivery, then to delivered / read as recipient receipts arrive (track via webhooks or by polling GET /v1/messages/:messageId).

GET /v1/messages

Paginated list of messages for the authenticated account.

Request Contract

Parameter	In	Type	Required	Rules
`phoneNumberId`	Query	`string`	No	Filter by sender phone ID.
`status`	Query	`string`	No	One of pending, sent, delivered, read, failed.
`page`	Query	`number`	No	Integer >= 1. Default 1.
`limit`	Query	`number`	No	Integer 1..100. Default 20.

Results are scoped to the API key's environment (sk_live_ or sk_test_) automatically.

Authorization and Scopes

Requirement	Value
Auth header	`Authorization: Bearer sk_test_* \| sk_live_*`
Required scope	`messages:read`

Status Codes

Code	Meaning
`200`	Page returned.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`429`	Rate limit exceeded for this API key.

Response Fields

Field	Type	Notes
`data.data[]`	`Message[]`	Array sorted by createdAt desc.
`data.pagination.page`	`number`	Current page index (1-based).
`data.pagination.limit`	`number`	Requested page size.
`data.pagination.total`	`number`	Total matching messages.
`data.pagination.totalPages`	`number`	Computed page count.

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

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

GET /v1/messages/:messageId

Get one message and its lifecycle timestamps.

Request Contract

Parameter	In	Type	Required	Rules
`messageId`	Path	`string`	Yes	Message ID returned by send endpoint (msg_*).

Authorization and Scopes

Requirement	Value
Auth header	`Authorization: Bearer sk_test_* \| sk_live_*`
Required scope	`messages:read`

Status Codes

Code	Meaning
`200`	Message returned.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`404`	Message ID not found in this account.
`429`	Rate limit exceeded for this API key.

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

{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "isGroup": false,
    "groupId": null,
    "content": "Hello",
    "mediaUrls": [],
    "status": "delivered",
    "errorCode": null,
    "errorMessage": null,
    "createdAt": "2026-02-06T14:18:33.000Z",
    "sentAt": "2026-02-06T14:18:33.120Z",
    "deliveredAt": "2026-02-06T14:18:35.000Z",
    "readAt": null,
    "failedAt": null
  }
}

GET /v1/messages/inbound

Paginated list of messages received by the account's connected phone numbers. Inbound messages exist for live connections only — sandbox (sk_test_*) keys always receive an empty list.

Request Contract

Parameter	In	Type	Required	Rules
`phoneNumberId`	Query	`string`	No	Filter by receiving phone ID.
`page`	Query	`number`	No	Integer >= 1. Default 1.
`limit`	Query	`number`	No	Integer 1..100. Default 20.

Authorization and Scopes

Requirement	Value
Auth header	`Authorization: Bearer sk_live_*`
Required scope	`messages:read`

Status Codes

Code	Meaning
`200`	Page returned.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`429`	Rate limit exceeded for this API key.

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

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "inmsg_abc123def456",
        "from": "+15557654321",
        "to": "+15551234567",
        "content": "Thanks, got it!",
        "type": "text",
        "isGroup": false,
        "groupId": null,
        "receivedAt": "2026-02-06T14:21:08.000Z",
        "createdAt": "2026-02-06T14:21:09.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}

GET /v1/messages/inbound/:messageId

Get one inbound message by its identifier.

Request Contract

Parameter	In	Type	Required	Rules
`messageId`	Path	`string`	Yes	Inbound message ID (inmsg_*).

Status Codes

Code	Meaning
`200`	Inbound message returned.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`404`	Inbound message ID not found in this account.
`429`	Rate limit exceeded for this API key.

curl -X GET https://developers-api.chatmaid.net/v1/messages/inbound/inmsg_abc123def456 \
  -H "Authorization: Bearer sk_live_xxx"

GET /v1/groups

List the WhatsApp groups a sender phone can post to. Each id is a full group JID, valid as to in POST /v1/messages/send. See Groups for details.

Request Contract

Parameter	In	Type	Required	Rules
`fromPhoneId`	Query	`string`	Yes	Sender phone, given as its E.164 number (recommended) or its dashboard ID.

Authorization and Scopes

Requirement	Value
Auth header	`Authorization: Bearer sk_test_* \| sk_live_*`
Any required scope	`groups:read`
Alternative accepted scopes	`messages:read`, `messages:send`, `messages:write`

Status Codes

Code	Meaning
`200`	Group list returned.
`400`	Phone not connected for live key.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`404`	fromPhoneId not found in account.
`429`	Rate limit exceeded for this API key.
`502`	WhatsApp group fetch failed — retry after a moment.

curl -X GET "https://developers-api.chatmaid.net/v1/groups?fromPhoneId=%2B15551234567" \
  -H "Authorization: Bearer sk_live_xxx"

{
  "success": true,
  "data": [
    {
      "id": "120363043211234567@g.us",
      "name": "Team Updates",
      "isCommunityAnnounce": false
    }
  ]
}

GET /v1/phone-numbers

List phone numbers available to this account.

Authorization and Scopes

Requirement	Value
Auth header	`Authorization: Bearer sk_test_* \| sk_live_*`
Recommended scope	`phone_numbers:read`
Backward-compatible scope accepted	`phone-numbers:read`

Status Codes

Code	Meaning
`200`	Phone list returned.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`429`	Rate limit exceeded for this API key.

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

{
  "success": true,
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "phoneNumber": "+15551234567",
      "displayName": "Primary Sender",
      "connectionStatus": "connected",
      "lastConnectedAt": "2026-02-06T14:10:00.000Z",
      "lastDisconnectedAt": null,
      "createdAt": "2026-02-01T10:20:00.000Z",
      "updatedAt": "2026-02-06T14:10:00.000Z"
    }
  ]
}

GET /v1/phone-numbers/:id

Get one phone number by internal ID or URL-encoded E.164 value.

Request Contract

Parameter	In	Type	Required	Rules
`id`	Path	`string`	Yes	Accepts phone ID or URL-encoded E.164 value (example: %2B15551234567).

Status Codes

Code	Meaning
`200`	Phone returned.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`404`	Phone reference not found in this account.
`429`	Rate limit exceeded for this API key.

curl -X GET "https://developers-api.chatmaid.net/v1/phone-numbers/%2B15551234567" \
  -H "Authorization: Bearer sk_test_xxx"

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "phoneNumber": "+15551234567",
    "displayName": "Primary Sender",
    "connectionStatus": "connected",
    "lastConnectedAt": "2026-02-06T14:10:00.000Z",
    "lastDisconnectedAt": null,
    "createdAt": "2026-02-01T10:20:00.000Z",
    "updatedAt": "2026-02-06T14:10:00.000Z"
  }
}

GET /v1/phone-numbers/:id/status

Get live connection state by internal ID or URL-encoded E.164 value.

Request Contract

Parameter	In	Type	Required	Rules
`id`	Path	`string`	Yes	Accepts phone ID or URL-encoded E.164 value (example: %2B15551234567).

Status Codes

Code	Meaning
`200`	Status returned.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`404`	Phone reference not found in this account.
`429`	Rate limit exceeded for this API key.

curl -X GET "https://developers-api.chatmaid.net/v1/phone-numbers/%2B15551234567/status" \
  -H "Authorization: Bearer sk_test_xxx"

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "phoneNumber": "+15551234567",
    "connectionStatus": "connected",
    "lastConnectedAt": "2026-02-06T14:10:00.000Z",
    "lastDisconnectedAt": null,
    "updatedAt": "2026-02-06T14:10:00.000Z"
  }
}

GET /v1/account

Read account profile and aggregate counters.

Authorization and Scopes

Requirement	Value
Auth header	`Authorization: Bearer sk_test_* \| sk_live_*`
Recommended scope	`account:read`
Other accepted scopes	`messages:read, messages:send, messages:write`

Status Codes

Code	Meaning
`200`	Account data returned.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`429`	Rate limit exceeded for this API key.

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

{
  "success": true,
  "data": {
    "accountId": "acc_abc123def456",
    "name": "Acme Inc",
    "email": "developer@acme.com",
    "subscriptionStatus": "active",
    "stats": {
      "apiKeys": 2,
      "phoneNumbers": 1,
      "messages": 328
    }
  }
}

GET /v1/account/usage

Read account usage metrics for day, week, or month.

Request Contract

Parameter	In	Type	Required	Rules
`period`	Query	`string`	No	One of day, week, month. Default month.

Status Codes

Code	Meaning
`200`	Usage returned.
`401`	Missing/invalid/expired API key.
`403`	API key does not include required scope.
`429`	Rate limit exceeded for this API key.

curl -X GET "https://developers-api.chatmaid.net/v1/account/usage?period=month" \
  -H "Authorization: Bearer sk_test_xxx"

{
  "success": true,
  "data": {
    "period": "month",
    "startDate": "2026-01-07T14:20:00.000Z",
    "endDate": "2026-02-06T14:20:00.000Z",
    "messages": {
      "total": 328,
      "pending": 0,
      "sent": 314,
      "failed": 14
    },
    "apiRequests": {
      "total": 1242,
      "successful": 1221,
      "failed": 21
    }
  }
}

Response Schema

{
  "success": true,
  "data": {}
}

{
  "success": false,
  "error": "Unauthorized",
  "message": ["Invalid API key"],
  "statusCode": 401,
  "timestamp": "2026-02-06T14:22:30.000Z",
  "path": "/v1/messages"
}

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": ["Rate limit exceeded"],
  "statusCode": 429,
  "timestamp": "2026-02-06T14:22:30.000Z",
  "path": "/v1/messages/send",
  "retryAfter": 60
}

API Reference

On this page