Skip to main content

Your First API Call

A step-by-step guide to making your first successful API call.

Before You Start​

Make sure you have:

  • A HueChat account
  • An API key (see API Keys)
  • cURL, Postman, or any HTTP client

Create a Contact​

Let's create your first contact. This is the foundation for sending messages.

Request​

curl -X POST https://api.huechat.ai/v2/contact \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1234567890",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com"
  }'

Response​

{
  "id": "cnt_abc123def456",
  "phone": "+1234567890",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "full_name": "Jane Smith",
  "preferred_channel": null,
  "status": "active",
  "metadata": {},
  "created_at": "2026-01-25T10:30:00Z",
  "updated_at": "2026-01-25T10:30:00Z",
  "last_contacted": null
}

Save the id value - you'll need it to send messages.

Send a Message​

Now let's send a message to your contact.

Request​

curl -X POST https://api.huechat.ai/v2/contact/cnt_abc123def456/message \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "message_type": "text",
    "content": "Hello Jane! Thanks for signing up."
  }'

Response​

{
  "id": "msg_xyz789ghi012",
  "conversation_id": "conv_mno345pqr678",
  "contact_id": "cnt_abc123def456",
  "channel": "whatsapp",
  "message_type": "text",
  "content": "Hello Jane! Thanks for signing up.",
  "status": "sent",
  "sent_by": "user",
  "sent_at": "2026-01-25T10:35:00Z",
  "delivered_at": null,
  "read_at": null
}

Check Message Status​

Messages go through several states:

StatusDescription
sentMessage sent to channel provider
deliveredMessage delivered to recipient's device
readRecipient opened/read the message
failedMessage failed to send

Retrieve the message to check its current status:

curl https://api.huechat.ai/v2/conversation/conv_mno345pqr678/messages \
  -H "X-API-Key: sk_live_your_api_key"

View the Conversation​

The message created a conversation. Let's view it:

curl https://api.huechat.ai/v2/conversation/conv_mno345pqr678 \
  -H "X-API-Key: sk_live_your_api_key"

Response​

{
  "id": "conv_mno345pqr678",
  "contact_id": "cnt_abc123def456",
  "contact": {
    "id": "cnt_abc123def456",
    "full_name": "Jane Smith",
    "phone": "+1234567890"
  },
  "channel": "whatsapp",
  "status": "open",
  "priority": "medium",
  "labels": [],
  "message_count": 1,
  "unread_count": 0,
  "created_at": "2026-01-25T10:35:00Z",
  "last_message_at": "2026-01-25T10:35:00Z"
}

Common Issues​

401 Unauthorized​

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "code": 401
}

Solution: Check that your API key is correct and included in the header.

400 Bad Request​

{
  "error": "invalid_input",
  "message": "Phone number must be in E.164 format",
  "code": 400
}

Solution: Phone numbers must include country code with + prefix (e.g., +1234567890).

429 Rate Limited​

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "code": 429
}

Solution: Wait and retry, or upgrade your plan for higher limits.

What's Next?​