ChatmaidChatmaid DevelopersChatmaid Dev
Docs
DashboardStart Building
Get Started

Getting Started

End-to-end quickstart from account creation to first message.

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.

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

4. Send your first message.

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": "Hello from Chatmaid"
  }'
Expected Send Response (201)
{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "content": "Hello from Chatmaid",
    "mediaUrls": [],
    "environment": "test",
    "status": "sent",
    "createdAt": "2026-02-06T14:18:33.000Z",
    "sentAt": "2026-02-06T14:18:33.120Z",
    "deliveredAt": null,
    "readAt": null,
    "failedAt": null,
    "errorCode": null,
    "errorMessage": null
  }
}

5. Poll status until terminal state.

Get Message Status
curl -X GET https://developers-api.chatmaid.net/v1/messages/msg_abc123def456 \
  -H "Authorization: Bearer sk_test_xxx"
Expected Status Response (200)
{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "status": "delivered",
    "environment": "test",
    "sentAt": "2026-02-06T14:18:34.000Z",
    "deliveredAt": "2026-02-06T14:19:10.000Z",
    "readAt": null,
    "failedAt": null,
    "errorCode": null,
    "errorMessage": null
  }
}
Retry Safety (Optional)
If your app retries failed HTTP requests aggressively, include an idempotencyKeygenerated from your own operation ID to avoid duplicate sends.

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.
On This Page