Send WhatsApp Messages

Learn how to send WhatsApp messages through the HueChat API.

Prerequisites

• Connected WhatsApp Business account
• Verified phone number
• Approved message templates (for initiating conversations)

Message Types

Type	Use Case	24-Hour Window Required
Text	Reply to customer messages	Yes
Template	Initiate conversations, notifications	No
Image	Send photos, screenshots	Yes
Document	Send PDFs, files	Yes

WhatsApp 24-Hour Window

WhatsApp has a 24-hour messaging window rule:

• Inside window: Send any message type (text, image, document)
• Outside window: Must use approved template messages

The window opens when a customer sends you a message and stays open for 24 hours.

Sending Text Messages

Use text messages when replying within the 24-hour window:

curl -X POST https://api.huechat.ai/v2/contact/cnt_123/message \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "message_type": "text",
    "content": "Thanks for reaching out! How can I help you today?"
  }'

Response

{
  "id": "msg_abc123",
  "conversation_id": "conv_xyz789",
  "channel": "whatsapp",
  "message_type": "text",
  "content": "Thanks for reaching out! How can I help you today?",
  "status": "sent",
  "sent_at": "2026-01-25T10:30:00Z"
}

Sending Template Messages

Template messages are pre-approved by WhatsApp and can be sent anytime.

List Available Templates

curl https://api.huechat.ai/v2/channels/whatsapp/templates \
  -H "X-API-Key: sk_live_your_key"

Send Template Message

curl -X POST https://api.huechat.ai/v2/contact/cnt_123/message \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "message_type": "template",
    "template_name": "order_confirmation",
    "template_parameters": {
      "1": "John",
      "2": "ORD-12345",
      "3": "$99.99",
      "4": "January 27, 2026"
    }
  }'

Common Template Examples

Order Confirmation

{
  "channel": "whatsapp",
  "message_type": "template",
  "template_name": "order_confirmation",
  "template_parameters": {
    "customer_name": "John",
    "order_id": "ORD-12345",
    "total": "$99.99",
    "delivery_date": "January 27"
  }
}

Appointment Reminder

{
  "channel": "whatsapp",
  "message_type": "template",
  "template_name": "appointment_reminder",
  "template_parameters": {
    "customer_name": "Jane",
    "appointment_date": "January 28, 2026",
    "appointment_time": "2:00 PM",
    "location": "123 Main Street"
  }
}

Shipping Update

{
  "channel": "whatsapp",
  "message_type": "template",
  "template_name": "shipping_update",
  "template_parameters": {
    "order_id": "ORD-12345",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "estimated_delivery": "January 29"
  }
}

Sending Media Messages

Images

curl -X POST https://api.huechat.ai/v2/contact/cnt_123/message \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "message_type": "image",
    "media_url": "https://example.com/product.jpg",
    "content": "Here is the product you asked about!"
  }'

Documents

curl -X POST https://api.huechat.ai/v2/contact/cnt_123/message \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "message_type": "document",
    "media_url": "https://example.com/invoice.pdf",
    "content": "Please find your invoice attached."
  }'

Supported Media Types

Type	Formats	Max Size
Image	JPEG, PNG	5 MB
Document	PDF, DOC, DOCX, XLS, XLSX	100 MB
Video	MP4, 3GPP	16 MB
Audio	AAC, MP3, OGG	16 MB

Message Status Tracking

Track your message through delivery stages:

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

Status Values

Status	Description	WhatsApp Equivalent
sent	Message sent to WhatsApp	Single grey check
delivered	Delivered to recipient's phone	Double grey checks
read	Recipient opened the message	Double blue checks
failed	Message failed to send	Error

Handling Failures

Common Error Codes

Error	Cause	Solution
window_expired	24-hour window closed	Use template message
invalid_phone	Phone number not on WhatsApp	Verify number
template_not_found	Template doesn't exist	Check template name
rate_limited	Too many messages	Wait and retry

Error Response Example

{
  "error": "window_expired",
  "message": "The 24-hour messaging window has expired. Use a template message.",
  "code": 400,
  "details": {
    "window_closed_at": "2026-01-24T10:30:00Z",
    "suggested_action": "Send template message"
  }
}

Best Practices

Do

• Use templates for notifications (order updates, reminders)
• Reply quickly to keep the 24-hour window open
• Include opt-out instructions in marketing messages
• Personalize messages with customer names

Don't

• Send promotional messages without consent
• Spam customers with too many messages
• Use text messages outside the 24-hour window
• Include sensitive data in messages

Code Examples

Node.js

const HueChat = require('@huechat/sdk');

const client = new HueChat.Client({
  apiKey: process.env.HUECHAT_API_KEY
});

// Send text message
await client.messages.send('cnt_123', {
  channel: 'whatsapp',
  messageType: 'text',
  content: 'Hello! How can I help?'
});

// Send template
await client.messages.send('cnt_123', {
  channel: 'whatsapp',
  messageType: 'template',
  templateName: 'order_confirmation',
  templateParameters: {
    order_id: 'ORD-12345',
    total: '$99.99'
  }
});

Python

from huechat import Client

client = Client(api_key=os.environ['HUECHAT_API_KEY'])

# Send text message
client.messages.send('cnt_123', {
    'channel': 'whatsapp',
    'message_type': 'text',
    'content': 'Hello! How can I help?'
})

# Send template
client.messages.send('cnt_123', {
    'channel': 'whatsapp',
    'message_type': 'template',
    'template_name': 'order_confirmation',
    'template_parameters': {
        'order_id': 'ORD-12345',
        'total': '$99.99'
    }
})