ChatLoopHQ Developer Hub

WhatsApp API Documentation

Connect, send, and receive WhatsApp messages programmatically. Use channel API keys to send text and media, manage groups, and receive webhook events in your application.

Personalize Code Examples

Snippets below update in real time

Your Secret API Key

Target Endpoint Base URL

Authentication

Authenticate requests using your ChatLoopHQ Live API Key. Keys are scoped per WhatsApp channel/session and grant programmatic access to send messages, read contacts, and control your channel.

Required Authorization HeaderAuthorization: Bearer YOUR_API_KEY

Alternatively, you may provide the key via the x-api-key HTTP header.

Where to find your key:Dashboard → Channel Control Hub → API Key Modal

Base URL & Network Routing

All production API requests must target HTTPS. Submitting requests over unencrypted HTTP will fail.

Global Production API

https://api.chatloophq.com

High-availability REST endpoints behind global Cloudflare CDN.

Local Dev / Staginghttp://localhost:3003

When developing and testing backend integrations on your machine.

Rate Limits & Quotas

ChatLoopHQ protects your WhatsApp number reputation through smart queuing and plan-based quotas. Exceeding limits returns an HTTP 429 Too Many Requests.

Free Tier (Evaluation)

Free

Active Conversations:Up to 5 / month
Outbound Messages:Up to 150 / day
API Invocations:Up to 1,000 / month

Pro Channel Subscription

Pro

Active Conversations:Unlimited
Outbound Messages:Full Channel Capacity
Priority Queue:Dedicated Redis Workers

HTTP Response Codes

Status	Meaning	Description
200 OK	Success	The request was successfully processed.
201 Created	Created	Resource (message, group) was generated.
202 Accepted	Queued / Deferred	Message was accepted into the safety queue with warmup jitter.
400 Bad Request	Validation Error	Malformed JSON, missing fields, or invalid restricted media URL.
401 Unauthorized	Invalid Credentials	Missing or expired API key header.
403 Forbidden	Access Denied	Subscription inactive or channel ownership mismatch.
429 Rate Limited	Too Many Requests	Daily or monthly request limit exceeded for this plan.

Inbound Webhooks & Events

When WhatsApp users reply to your channel or send inbound media, ChatLoopHQ sends an HTTP POST event to your configured webhook URL in real time.

Sample Webhook Event Payload

{
  "event": "messages.upsert",
  "channelId": "session_671b4a9...",
  "timestamp": 1729864200,
  "data": {
    "messageId": "3EB0ABC123456789",
    "from": "[email protected]",
    "fromMe": false,
    "pushName": "Sarah Connor",
    "type": "text",
    "body": "Hi, I would like to confirm my order #9821."
  }
}

API Endpoints Reference

Showing 23 endpoints across 5 categories

Messaging

7 endpoints

Send Text Message

Send a plain text message to a WhatsApp number. The recipient number should not include a + sign.

POST/api/send/text

Request JSON Body

{
  "to": "14155552671",
  "text": "Hello from ChatLoopHQ!"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/send/text" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"14155552671","text":"Hello from ChatLoopHQ!"}'

Expected Webhook Event

{
  "messages": [
    {
      "id": "AC8930E467AB6FC89EF277929EE0D22B",
      "from_me": true,
      "chat_id": "[email protected]",
      "timestamp": 1672531200,
      "channel_id": "session_123",
      "from": "14155552671",
      "from_name": "User",
      "type": "text",
      "body": {
        "text": "Hello from ChatLoopHQ!"
      }
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "session_123"
}

Send Media

Send an image, video, audio, or document using a publicly accessible URL or base64 string.

POST/api/send/media

Request JSON Body

{
  "to": "14155552671",
  "url": "https://example.com/document.pdf",
  "caption": "Check this out!"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/send/media" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"14155552671","url":"https://example.com/document.pdf","caption":"Check this out!"}'

Expected Webhook Event

{
  "messages": [
    {
      "id": "AC8930E467AB6FC89EF277929EE0D22B",
      "from_me": true,
      "chat_id": "[email protected]",
      "timestamp": 1672531200,
      "channel_id": "session_123",
      "from": "14155552671",
      "from_name": "User",
      "type": "document",
      "body": {
        "file_name": "document.pdf",
        "file_size": 102400,
        "mimetype": "application/pdf"
      }
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "session_123"
}

Send Voice Note

Send an audio file as a voice note (Push-To-Talk).

POST/api/send/voice

Request JSON Body

{
  "to": "14155552671",
  "media": "https://example.com/audio.ogg"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/send/voice" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"14155552671","media":"https://example.com/audio.ogg"}'

Expected Webhook Event

{
  "messages": [
    {
      "id": "AC8930E467AB6FC89EF277929EE0D22B",
      "from_me": true,
      "chat_id": "[email protected]",
      "timestamp": 1672531200,
      "channel_id": "session_123",
      "from": "14155552671",
      "from_name": "User",
      "type": "audio",
      "body": {
        "file_size": 51200,
        "mimetype": "audio/ogg",
        "seconds": 12,
        "voice_note": true
      }
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "session_123"
}

Send Location

Send a geographical location pin.

POST/api/send/location

Request JSON Body

{
  "to": "14155552671",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "name": "San Francisco",
  "address": "548 Market St, San Francisco, CA"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/send/location" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"14155552671","latitude":37.7749,"longitude":-122.4194,"name":"San Francisco","address":"548 Market St, San Francisco, CA"}'

Expected Webhook Event

{
  "messages": [
    {
      "id": "AC8930E467AB6FC89EF277929EE0D22B",
      "from_me": true,
      "chat_id": "[email protected]",
      "timestamp": 1672531200,
      "channel_id": "session_123",
      "from": "14155552671",
      "from_name": "User",
      "type": "location",
      "body": {
        "latitude": 37.7749,
        "longitude": -122.4194,
        "address": "548 Market St, San Francisco, CA",
        "name": "San Francisco"
      }
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "session_123"
}

Send Contact

Send a vCard containing contact details.

POST/api/send/contact

Request JSON Body

{
  "to": "14155552671",
  "contactNumbers": [
    "14155550001",
    "14155550002"
  ],
  "contactName": "John Doe",
  "organization": "Acme Corp"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/send/contact" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"14155552671","contactNumbers":["14155550001","14155550002"],"contactName":"John Doe","organization":"Acme Corp"}'

Expected Webhook Event

{
  "messages": [
    {
      "id": "AC8930E467AB6FC89EF277929EE0D22B",
      "from_me": true,
      "chat_id": "[email protected]",
      "timestamp": 1672531200,
      "channel_id": "session_123",
      "from": "14155552671",
      "from_name": "User",
      "type": "contact",
      "body": {
        "display_name": "John Doe",
        "vcard": "BEGIN:VCARD\\nVERSION:3.0\\nFN:John Doe\\nORG:Acme Corp;\\nTEL;type=CELL;type=VOICE;waid=14155550001:+1 415 555 0001\\nEND:VCARD"
      }
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "session_123"
}

Send Reaction

React to a specific message using an emoji.

POST/api/send/reaction

Request JSON Body

{
  "chatId": "[email protected]",
  "messageId": "BAE5...",
  "reaction": "👍"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/send/reaction" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","messageId":"BAE5...","reaction":"👍"}'

Expected Webhook Event

{
  "messages": [
    {
      "id": "AC8930E467AB6FC89EF277929EE0D22B",
      "from_me": true,
      "chat_id": "[email protected]",
      "timestamp": 1672531200,
      "channel_id": "session_123",
      "from": "14155552671",
      "from_name": "User",
      "type": "reaction",
      "body": {
        "message_id": "BAE5...",
        "emoji": "👍"
      }
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "session_123"
}

Download Media

Download the media content from a specific message ID.

GET/api/download/media/:messageId

Path & Query Parameters

messageId(string)
Required
The ID of the message containing media

Code Example

curl -X GET "https://api.chatloophq.com/api/download/media/:messageId" \
  -H "Authorization: Bearer YOUR_API_KEY" \

Sample Response (200 OK)

{
  "success": true,
  "url": "https://..."
}

Chat & Message Info

5 endpoints

Get Chats

Retrieve a list of all active chats.

GET/api/chats

Code Example

curl -X GET "https://api.chatloophq.com/api/chats" \
  -H "Authorization: Bearer YOUR_API_KEY" \

Sample Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "[email protected]",
      "name": "John Doe",
      "unreadCount": 2
    }
  ]
}

Get Messages

Retrieve message history for a specific chat.

POST/api/messages

Request JSON Body

{
  "chatId": "[email protected]",
  "limit": 20
}

Code Example

curl -X POST "https://api.chatloophq.com/api/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","limit":20}'

Sample Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "BAE5...",
      "text": "Hello",
      "fromMe": false,
      "timestamp": 1672531200
    }
  ]
}

Mark Messages as Read

Mark specific messages as read using their keys.

POST/api/messages/read

Request JSON Body

{
  "keys": [
    {
      "id": "BAE5...",
      "remoteJid": "[email protected]",
      "fromMe": false
    }
  ]
}

Code Example

curl -X POST "https://api.chatloophq.com/api/messages/read" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys":[{"id":"BAE5...","remoteJid":"[email protected]","fromMe":false}]}'

Sample Response (200 OK)

{
  "success": true
}

Check Number

Check if a phone number exists on WhatsApp.

POST/api/check-number

Request JSON Body

{
  "number": "14155552671"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/check-number" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"14155552671"}'

Sample Response (200 OK)

{
  "success": true,
  "exists": true,
  "jid": "[email protected]"
}

Get Contacts

Get all synchronized contacts.

GET/api/contacts

Code Example

curl -X GET "https://api.chatloophq.com/api/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \

Sample Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "[email protected]",
      "name": "John Doe"
    }
  ]
}

Group Management

5 endpoints

Get Groups

Get all groups the session is participating in.

GET/api/groups

Code Example

curl -X GET "https://api.chatloophq.com/api/groups" \
  -H "Authorization: Bearer YOUR_API_KEY" \

Sample Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "[email protected]",
      "subject": "My Group",
      "participants": []
    }
  ]
}

Create Group

Create a new WhatsApp group with participants. Use phone numbers without the @s.whatsapp.net suffix.

POST/api/groups

Request JSON Body

{
  "name": "My New Group",
  "participants": [
    "14155552671",
    "14155552672"
  ]
}

Code Example

curl -X POST "https://api.chatloophq.com/api/groups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My New Group","participants":["14155552671","14155552672"]}'

Sample Response (200 OK)

{
  "success": true,
  "groupId": "[email protected]"
}

Update Participants

Add, remove, promote, or demote group participants.

POST/api/groups/participants

Request JSON Body

{
  "groupId": "[email protected]",
  "participants": [
    "14155552671",
    "14155552672"
  ],
  "action": "add"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/groups/participants" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"groupId":"[email protected]","participants":["14155552671","14155552672"],"action":"add"}'

Sample Response (200 OK)

{
  "success": true
}

Get Invite Code

Get the invite link code for a group.

GET/api/groups/:groupId/invite-code

Path & Query Parameters

groupId(string)
Required
The JID of the group

Code Example

curl -X GET "https://api.chatloophq.com/api/groups/:groupId/invite-code" \
  -H "Authorization: Bearer YOUR_API_KEY" \

Sample Response (200 OK)

{
  "success": true,
  "code": "INVITE_CODE_XYZ"
}

Leave Group

Leave a WhatsApp group.

DELETE/api/groups/:groupId/leave

Path & Query Parameters

groupId(string)
Required
The JID of the group

Code Example

curl -X DELETE "https://api.chatloophq.com/api/groups/:groupId/leave" \
  -H "Authorization: Bearer YOUR_API_KEY" \

Sample Response (200 OK)

{
  "success": true
}

Status & Presence

3 endpoints

Update Presence

Update the presence status (e.g., typing, recording).

POST/api/presence

Request JSON Body

{
  "to": "14155552671",
  "presence": "composing"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/presence" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"14155552671","presence":"composing"}'

Sample Response (200 OK)

{
  "success": true
}

Post Text Status

Post a text status update (story).

POST/api/status/text

Request JSON Body

{
  "text": "Good morning ☀️",
  "backgroundColor": "#25D366"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/status/text" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Good morning ☀️","backgroundColor":"#25D366"}'

Sample Response (200 OK)

{
  "success": true
}

Post Media Status

Post a media status update (image/video).

POST/api/status/media

Request JSON Body

{
  "media": "https://example.com/image.jpg",
  "caption": "My new status"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/status/media" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media":"https://example.com/image.jpg","caption":"My new status"}'

Sample Response (200 OK)

{
  "success": true
}

User Operations

3 endpoints

Get Profile Picture

Get a user or group profile picture URL.

GET/api/user/:jid/profile-picture

Path & Query Parameters

jid(string)
Required
The JID of the user or group

Code Example

curl -X GET "https://api.chatloophq.com/api/user/:jid/profile-picture" \
  -H "Authorization: Bearer YOUR_API_KEY" \

Sample Response (200 OK)

{
  "success": true,
  "url": "https://..."
}

Get Business Profile

Get business profile info (description, category, etc).

GET/api/user/:jid/business-profile

Path & Query Parameters

jid(string)
Required
The JID of the business account

Code Example

curl -X GET "https://api.chatloophq.com/api/user/:jid/business-profile" \
  -H "Authorization: Bearer YOUR_API_KEY" \

Sample Response (200 OK)

{
  "success": true,
  "data": {
    "description": "Business info",
    "category": "Software"
  }
}

Block / Unblock User

Block or unblock a user.

POST/api/user/block

Request JSON Body

{
  "jid": "14155552671",
  "action": "block"
}

Code Example

curl -X POST "https://api.chatloophq.com/api/user/block" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jid":"14155552671","action":"block"}'

Sample Response (200 OK)

{
  "success": true
}