Skip to main content

FAQ

Frequently asked questions about HueChat API.

General​

What is HueChat?​

HueChat is a customer communication platform that unifies WhatsApp, Instagram, SMS, and Email into a single API. It helps businesses manage all customer conversations from one place.

What channels does HueChat support?​

  • WhatsApp Business - Full messaging support including templates
  • Instagram - Direct messages and story replies
  • SMS - Text messaging via Twilio/MessageBird
  • Email - Transactional and support emails

Is there a free tier?​

Yes! The free tier includes:

  • 100 API requests per minute
  • 1,000 messages per month
  • 2 connected channels
  • Basic analytics

Authentication​

What authentication methods are supported?​

HueChat uses API keys only. We don't support OAuth or JWT for API access. This keeps integration simple and secure for server-to-server communication.

How do I get an API key?​

  1. Log into app.huechat.ai
  2. Go to Settings > API Keys
  3. Click Create API Key
  4. Copy your key (shown only once!)

What's the difference between live and test keys?​

Key TypePrefixEnvironmentReal Messages?
Livesk_live_ProductionYes
Testsk_test_SandboxNo (simulated)

Test keys work with sandbox.huechat.ai and don't send real messages - perfect for development.

Can I rotate my API keys?​

Yes! Create a new key, update your application, then delete the old key. We recommend rotating keys every 90 days.

Messaging​

What's the WhatsApp 24-hour window?​

WhatsApp requires businesses to use template messages to initiate conversations. Once a customer replies, you have a 24-hour window to send free-form messages.

Inside window (24 hours after customer message):

  • Send any message type (text, image, document)

Outside window:

  • Must use approved template messages

How do I send template messages?​

curl -X POST https://api.huechat.ai/v2/contact/cnt_123/message \
  -H "X-API-Key: sk_live_your_key" \
  -d '{
    "channel": "whatsapp",
    "message_type": "template",
    "template_name": "order_confirmation",
    "template_parameters": {"order_id": "12345"}
  }'

Why did my message fail?​

Common reasons:

  • Window expired: Use a template message
  • Invalid phone: Check E.164 format (+1234567890)
  • Channel disconnected: Reconnect in dashboard
  • Rate limited: Wait and retry

Can I send media files?​

Yes! Supported types:

  • Images: JPEG, PNG (max 5MB)
  • Documents: PDF, DOC, XLS (max 100MB)
  • Video: MP4 (max 16MB)
  • Audio: MP3, AAC (max 16MB)

Contacts​

What format should phone numbers be in?​

Always use E.164 format: + followed by country code and number.

CorrectIncorrect
+12345678901234567890
+44791112345607911123456

Can I store custom data on contacts?​

Yes! Use the metadata field to store any JSON data:

{
  "metadata": {
    "customer_id": "cust_123",
    "plan": "premium",
    "tags": ["vip", "enterprise"]
  }
}

How do I prevent duplicate contacts?​

The API returns a 409 Conflict error if a contact with the same phone or email exists. Use the existing contact ID from the error response:

{
  "error": "duplicate_contact",
  "details": {
    "existing_contact_id": "cnt_abc123"
  }
}

Webhooks​

How do I receive real-time updates?​

Register a webhook to receive HTTP POST requests when events happen:

curl -X POST https://api.huechat.ai/v2/webhooks \
  -H "X-API-Key: sk_live_your_key" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["message.received"]
  }'

Are webhooks secure?​

Yes! All webhooks are signed with HMAC-SHA256. Always verify the signature before processing:

const isValid = HueChat.Webhook.verify(
  body,
  headers['x-huechat-signature'],
  headers['x-huechat-timestamp'],
  webhookSecret
);

What if my webhook endpoint is down?​

We retry failed deliveries with exponential backoff:

  • Attempt 1: Immediate
  • Attempt 2: 1 minute
  • Attempt 3: 2 minutes
  • ... up to 8 attempts over ~3 hours

Can I test webhooks locally?​

Yes! Use ngrok or similar tools:

ngrok http 3000
# Use the ngrok URL for your webhook

Rate Limits​

What are the rate limits?​

PlanRequests/Minute
Free100
Pro1,000
EnterpriseCustom

How do I know if I'm rate limited?​

Check the response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706215260

A 429 Too Many Requests response means you've hit the limit.

How do I handle rate limits?​

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(retryAfter * 1000);
  // Retry request
}

SDKs​

What SDKs are available?​

Can I use the API without an SDK?​

Absolutely! The API is RESTful and works with any HTTP client. SDKs just make it easier.

Troubleshooting​

My API requests are failing​

  1. Check your API key - Is it valid and not revoked?
  2. Check the environment - Using sandbox URL with test key?
  3. Check the error response - What does error say?
  4. Check rate limits - Are you sending too many requests?

Messages aren't being delivered​

  1. Check channel status - Is it connected in the dashboard?
  2. Check the 24-hour window - Use templates if expired
  3. Check the phone number - Valid E.164 format?
  4. Check message status - What does the API return?

Webhooks aren't working​

  1. Check the URL - Is it HTTPS and publicly accessible?
  2. Check your server - Is it returning 200 status?
  3. Verify signatures - Are you verifying correctly?
  4. Check webhook logs - View delivery status in dashboard

Support​

How do I get help?​

How do I report a bug?​

Email support@huechat.ai with:

  • Your request ID (from error response)
  • Steps to reproduce
  • Expected vs actual behavior
  • Code samples if applicable