How to Use the HitlChat API

Before you start

• A HitlChat account with a connected WhatsApp number (Business API or QR connection).
• Your API key — see Authentication below for where to find it.
• Anything that can send an HTTP request (cURL, Postman, or your own backend). All examples use cURL.

Contacts API

Create and update contacts and assign tags. Assigning a tag can trigger automations you’ve set up in HitlChat (send a message, add to a list, start a workflow).

# Create a contact and tag it
curl -X POST https://api-portal.hitlchat.io/api/v1/public/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientNumber": "447700900123",
    "name": "Jane Doe",
    "tags": ["vip"]
  }'

Conversation Listings API

Fetch your conversations with customer details, the last message sender, status, and whether the bot is currently paused or was ever transferred to a human.

curl https://api-portal.hitlchat.io/api/v1/public/conversationlist \
  -H "Authorization: Bearer YOUR_API_KEY"

# Each item includes:
#   customer_name, customer_whatsapp_number,
#   last_message_sent_by, conversation_status,
#   bot_currently_paused, transferred_to_human_at_least_once

Agency API

Invite clients into your agency and manage agency relationships programmatically.

curl -X POST https://api-portal.hitlchat.io/api/v1/public/agency/invite-client \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "client@example.com",
    "first_name": "Sam",
    "last_name": "Lee"
  }'

Broadcasts API Business API only

Create and send WhatsApp broadcast campaigns using your approved Meta templates. Send immediately by omitting scheduled_datetime, or schedule it for the future. Target recipients by contact lists, tags, or an array of phone numbers.

# Send a broadcast now to specific numbers
curl -X POST https://api-portal.hitlchat.io/api/v1/public/broadcasts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcast_name": "May promo",
    "meta_template_name": "promo_may_2026",
    "recipient_numbers": ["447700900123"],
    "broadcast_configuration": {
      "variables": { "1": "Jane", "2": "20%" }
    }
  }'

Templates API Business API only

Fetch your approved Meta message templates so you can reference them by name when sending broadcasts.

curl https://api-portal.hitlchat.io/api/v1/public/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

Messages API QR connection only

Send WhatsApp messages — text, image, video, audio or file — when your number is connected via the WhatsApp Web / QR code method (not the Meta Business API).

# Send a text message
curl -X POST https://api-portal.hitlchat.io/api/v1/public/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "recipientNumber": "447700900123",
    "messageText": "Hi! A human will be with you shortly."
  }'

Every endpoint, field and response

The examples above are a starting point. The full interactive reference — auto-generated from the live API, so it’s always up to date — documents every parameter and lets you try calls in the browser.

Open the full API reference →