Chatmaid Developers

Architecture

This cookbook covers the full runtime loop for an integration service using API-key auth only:

Load API key and set a single base URL.
Fetch connected sender phone numbers.
Send outbound message requests.
Track status via polling and optional webhooks.
Apply retry/idempotency strategy and promote to production.

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

Bootstrap Client

Standardize your HTTP client once and reuse it for all endpoints.

Client Bootstrap

export CHATMAID_BASE_URL="https://developers-api.chatmaid.net"
export CHATMAID_API_KEY="sk_test_xxx"

curl -X GET "$CHATMAID_BASE_URL/v1/account" \
  -H "Authorization: Bearer $CHATMAID_API_KEY"

Send and Track

Use this operational sequence inside your application flow.

1) Resolve Sender Phone ID

GET/v1/phone-numbersAuth: API key

Read available phone numbers and select a connected sender.

Fetch Phone Numbers

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

2) Send Message

POST/v1/messages/sendAuth: API key

Create outbound message. Use optional idempotency key only for retry-heavy workflows.

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 7784 confirmed"
  }'

Expected Send Response (201)

{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "status": "sent",
    "environment": "test",
    "createdAt": "2026-02-06T14:18:33.000Z"
  }
}

3) Poll Status Until Terminal

GET/v1/messages/:messageIdAuth: API key

Poll until status reaches delivered/read/failed.

Poll Message Status

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

Reliability Patterns

Treat messageId as your canonical correlation key across systems.
Use webhook events for push updates; keep polling as fallback.
Use idempotencyKey only when your retry policy can repeat sends.
Capture and alert on failed statuses with retry in your domain logic.

Recommended Retry Design

Retry only transport failures (timeout/network/5xx) with exponential backoff. Do not blindly retry business errors (4xx) without fixing request payload or permissions.

Go Live Runbook

Keep the same API host and verify all examples/routes still match your code.
Swap credentials to sk_live_* key in production secret store.
Validate connected production phone status via GET /v1/phone-numbers/:id/status.
Send a low-risk real message and verify status progression.
Enable webhook verification and alerting for failed deliveries.

Cookbook