Getting Started

Prerequisites

• Account setup completed in Chatmaid dashboard
• At least one connected sender phone in dashboard
• API key generated in dashboard with message scopes

First Message Flow

1. Store your API key in your server secrets.
2. Fetch available sender phone IDs from standard API endpoints.
3. Send a message with API key auth.

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

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

4. Send your first 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": "+15551234567",
    "to": "+15557654321",
    "content": "Hello from Chatmaid"
  }'

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

5. Poll status until terminal state.

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

{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "status": "sent",
    "sentAt": "2026-02-06T14:18:34.000Z",
    "failedAt": null,
    "errorCode": null,
    "errorMessage": null
  }
}

Production Checklist

• Keep the same base URL and switch to sk_live_* credentials in production.
• Use sk_live_* keys only in production systems.
• Configure webhook destination in dashboard and verify signatures in your receiver.
• Monitor failed delivery events and implement retries in your system.