HitlChat Guides

https://www.hitlchat.io/guides
Admin
Step-by-step guides for connecting your Botpress and Voiceflow chatbots to WhatsApp and web chat —...
Tokens:29,042
Snippets:494
Trust Score:4.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Get Contact by Number

Source: https://www.hitlchat.io/guides/api

Retrieve a contact's information using their phone number.

```APIDOC
## GET /v1/public/contacts/{recipientNumber}

### Description
Retrieve a specific contact's details using their phone number.

### Method
GET

### Endpoint
/v1/public/contacts/{recipientNumber}

### Parameters
#### Path Parameters
- **recipientNumber** (string) - Required - The phone number of the contact to retrieve.
```

--------------------------------

### Invite a Client to Agency

Source: https://www.hitlchat.io/guides/api

Use the Agency API to invite new clients to your agency by providing their email address and name.

```bash
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"
  }'
```

--------------------------------

### Attaching Prior Chat History for Handoff Context

Source: https://www.hitlchat.io/guides/headless-human-handoff

Include the `prior_history` array as a top-level key alongside 'object' and 'entry' to provide context to agents. This is useful for both new and existing conversations and should be sent on every handoff.

```json
"prior_history": [
  { "direction": "inbound",  "text": "What are your hours?", "timestamp": "2026-06-08T09:14:00Z" },
  { "direction": "outbound", "text": "9am-5pm, Mon-Fri.",   "timestamp": "2026-06-08T09:14:05Z" }
]
```

--------------------------------

### Invite Client to Agency

Source: https://www.hitlchat.io/guides/api

Invite a new client to your agency by providing their email address and name.

```APIDOC
## POST /v1/public/agency/invite-client

### Description
Invite clients into your agency and manage agency relationships programmatically.

### Method
POST

### Endpoint
/v1/public/agency/invite-client

### Request Body
- **email_address** (string) - Required - The email address of the client to invite.
- **first_name** (string) - Required - The first name of the client.
- **last_name** (string) - Required - The last name of the client.

### Request Example
```json
{
  "email_address": "client@example.com",
  "first_name": "Sam",
  "last_name": "Lee"
}
```
```

--------------------------------

### Fetch Approved Templates

Source: https://www.hitlchat.io/guides/api

Retrieve your approved Meta message templates using the Templates API. These can be referenced by name when sending broadcasts.

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

--------------------------------

### Create and Tag a Contact

Source: https://www.hitlchat.io/guides/api

Use the Contacts API to create a new contact and assign tags. Assigning tags can trigger automations within HitlChat.

```bash
# 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"]
  }'
```

--------------------------------

### Fetch Approved Templates

Source: https://www.hitlchat.io/guides/api

Retrieve a list of your approved Meta message templates to reference them by name when sending broadcasts.

```APIDOC
## GET /v1/public/templates

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

### Method
GET

### Endpoint
/v1/public/templates

### Response
#### Success Response (200)
- **templates** (array of objects) - A list of approved templates.
  - **name** (string) - The name of the template.
  - **language** (string) - The language of the template.
```

--------------------------------

### Send WhatsApp Broadcast

Source: https://www.hitlchat.io/guides/api

Create and send WhatsApp broadcast campaigns using approved Meta templates. Omit `scheduled_datetime` to send immediately.

```bash
# 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%" }
    }
  }'
```

--------------------------------

### List Conversations

Source: https://www.hitlchat.io/guides/api

Use this cURL command to list your conversations and verify your API key. Ensure you replace 'YOUR_API_KEY' with your actual API key.

```bash
# List your conversations
curl https://api-portal.hitlchat.io/api/v1/public/conversationlist \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Optional: Prior Chat History (Handoff Context)

Source: https://www.hitlchat.io/guides/headless-human-handoff

Attach a `prior_history` array to any inbound message to provide agents with the earlier bot conversation context. This can be sent on every handoff.

```APIDOC
## Prior Chat History

### Description
Allows sending previous conversation turns as context when handing off to a human agent. This is useful for both new and existing conversations.

### Parameters
#### Request Body (Top-level addition)
- **prior_history** (array) - Optional - An array of past message objects.
  - **direction** (string) - Required - The direction of the message ('inbound' or 'outbound').
  - **text** (string) - Required - The content of the message. For past media turns, describe it here.
  - **timestamp** (string) - Required - The timestamp of the message in ISO 8601 format.

### Request Example
```json
{
  "prior_history": [
    { "direction": "inbound",  "text": "What are your hours?", "timestamp": "2026-06-08T09:14:00Z" },
    { "direction": "outbound", "text": "9am-5pm, Mon-Fri.",   "timestamp": "2026-06-08T09:14:05Z" }
  ]
}
```
```

--------------------------------

### Create and Tag Contact

Source: https://www.hitlchat.io/guides/api

Create a new contact and assign tags to it. Tags can trigger automations within HitlChat.

```APIDOC
## POST /v1/public/contacts

### Description
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).

### Method
POST

### Endpoint
/v1/public/contacts

### Request Body
- **recipientNumber** (string) - Required - The phone number of the recipient.
- **name** (string) - Required - The name of the contact.
- **tags** (array of strings) - Optional - A list of tags to assign to the contact.

### Request Example
```json
{
  "recipientNumber": "447700900123",
  "name": "Jane Doe",
  "tags": ["vip"]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **contact_id** (string) - The ID of the created contact.
```

--------------------------------

### Test Resolved Webhook Event

Source: https://www.hitlchat.io/guides/headless-human-handoff

Fire a sample conversation_resolved event to your webhook URL to test integration without a live gateway. Use a tool like webhook.site to inspect the payload.

```bash
curl -X POST https://api.hitlchat.io/v1/public/inbound/test-resolved-webhook
```

--------------------------------

### Manage Contacts

Source: https://www.hitlchat.io/guides/api

Add or update contacts, and assign tags. Trigger automations by assigning tags.

```APIDOC
## POST /v1/public/contacts

### Description
Manage contacts within HitlChat. This endpoint allows for adding new contacts or updating existing ones, including the ability to assign tags which can trigger automations.

### Method
POST

### Endpoint
https://api-portal.hitlchat.io/api/v1/public/contacts

### Parameters
#### Request Body
- **phone_number** (string) - Required - The phone number of the contact.
- **name** (string) - Optional - The name of the contact.
- **tags** (array of strings) - Optional - An array of tags to assign to the contact.

### Request Example
```json
{
  "phone_number": "+1234567890",
  "name": "Jane Doe",
  "tags": ["customer", "vip"]
}
```

### Response
#### Success Response (200)
- **contact_id** (string) - The unique identifier for the contact.
- **status** (string) - The status of the operation (e.g., 'created', 'updated').

#### Response Example
```json
{
  "contact_id": "con_xyz789abc",
  "status": "updated"
}
```
```

--------------------------------

### Fetch Conversation List

Source: https://www.hitlchat.io/guides/api

Retrieve a list of conversations with customer details, last message sender, and status using the Conversation Listings API.

```bash
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
```

--------------------------------

### Send Broadcast Message

Source: https://www.hitlchat.io/guides/api

Create and send WhatsApp broadcast campaigns using approved Meta templates. Can be sent immediately or scheduled.

```APIDOC
## POST /v1/public/broadcasts

### Description
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.

### Method
POST

### Endpoint
/v1/public/broadcasts

### Request Body
- **broadcast_name** (string) - Required - The name of the broadcast campaign.
- **meta_template_name** (string) - Required - The name of the approved Meta template to use.
- **recipient_numbers** (array of strings) - Optional - A list of recipient phone numbers.
- **contact_list_ids** (array of strings) - Optional - IDs of contact lists to send to.
- **tags** (array of strings) - Optional - Tags to filter recipients.
- **scheduled_datetime** (string) - Optional - The date and time to schedule the broadcast (ISO 8601 format).
- **broadcast_configuration** (object) - Optional - Configuration for the broadcast.
  - **variables** (object) - Key-value pairs for template variables.
```

--------------------------------

### Send Inbound Messages to HitlChat API

Source: https://www.hitlchat.io/guides/headless-human-handoff

Forward verbatim Meta webhook payloads, including text and media, to this endpoint. Optionally include a prior_history array for existing conversations.

```bash
curl -X POST \
  https://api.hitlchat.io/v1/public/inbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json
```

--------------------------------

### Send Message

Source: https://www.hitlchat.io/guides/api

Send individual text or media messages. This endpoint is used for QR code connected numbers.

```APIDOC
## POST /v1/public/messages/send

### Description
Send individual text or media messages through the HitlChat API. This endpoint is suitable for numbers connected via the QR code method.

### Method
POST

### Endpoint
https://api-portal.hitlchat.io/api/v1/public/messages/send

### Parameters
#### Request Body
- **recipient_number** (string) - Required - The phone number of the recipient.
- **message_text** (string) - Optional - The text content of the message.
- **media_url** (string) - Optional - The URL of the media to send (e.g., image, video).

### Request Example
```json
{
  "recipient_number": "+1234567890",
  "message_text": "Hello from HitlChat API!"
}
```

### Response
#### Success Response (200)
- **message_id** (string) - The unique identifier for the sent message.
- **status** (string) - The status of the message (e.g., 'sent', 'delivered').

#### Response Example
```json
{
  "message_id": "msg_12345abcde",
  "status": "sent"
}
```
```

--------------------------------

### Receive Agent Replies on Your Webhook

Source: https://www.hitlchat.io/guides/headless-human-handoff

HitlChat POSTs an `outbound_message` event to your Webhook URL when an agent replies. It includes `meta_payload`, which is the exact body to POST to Meta.

```APIDOC
## Event: outbound_message

### Description
This event is triggered when an agent replies from the HitlChat inbox. It provides the necessary payload to forward the reply to Meta.

### Event Type
outbound_message

### Parameters
#### Payload Received by Webhook
- **event** (string) - Required - The event type, 'outbound_message'.
- **contact_number** (string) - Required - The recipient's WhatsApp ID.
- **phone_number_id** (string) - Required - Your WhatsApp Business phone number ID.
- **meta_payload** (object) - Required - The payload to be sent to Meta.
  - **messaging_product** (string) - Required - The messaging product, e.g., 'whatsapp'.
  - **to** (string) - Required - The recipient's WhatsApp ID.
  - **type** (string) - Required - The message type (e.g., 'text', 'image').
  - **text** (object) - Required if type is 'text' - The text content.
    - **body** (string) - Required - The message body.
  - **image** (object) - Required if type is 'image' - Image details.
    - **link** (string) - Required - A public link to the image provided by Meta.

### Example Payload
```json
{
  "event": "outbound_message",
  "contact_number": "447700900123",
  "phone_number_id": "YOUR_PHONE_NUMBER_ID",
  "meta_payload": {
    "messaging_product": "whatsapp", "to": "447700900123",
    "type": "text", "text": { "body": "Hi John, happy to help!" }
  }
}
```
```

--------------------------------

### Forward Inbound Messages

Source: https://www.hitlchat.io/guides/headless-human-handoff

POST the verbatim Meta webhook payload to the inbound endpoint. The first message for a contact opens a conversation, and later messages append to it.

```APIDOC
## POST /v1/public/inbound

### Description
Forwards inbound messages from Meta to HitlChat. This endpoint handles both opening new conversations and appending to existing ones.

### Method
POST

### Endpoint
https://api-portal.hitlchat.io/api/v1/public/inbound

### Parameters
#### Request Body
- **object** (string) - Required - The object type from Meta.
- **entry** (array) - Required - An array containing message entry details.
  - **id** (string) - Required - The WhatsApp Business ID.
  - **changes** (array) - Required - An array of changes.
    - **field** (string) - Required - The field name, typically 'messages'.
    - **value** (object) - Required - The message value object.
      - **messaging_product** (string) - Required - The messaging product, e.g., 'whatsapp'.
      - **metadata** (object) - Required - Metadata about the message.
        - **phone_number_id** (string) - Required - The phone number ID.
      - **contacts** (array) - Required - Information about the contact.
        - **profile** (object) - Required - Contact profile information.
          - **name** (string) - Required - The contact's name.
        - **wa_id** (string) - Required - The WhatsApp ID of the contact.
      - **messages** (array) - Required - The actual message content.
        - **from** (string) - Required - The sender's WhatsApp ID.
        - **id** (string) - Required - The unique message ID.
        - **timestamp** (string) - Required - The message timestamp.
        - **type** (string) - Required - The message type (e.g., 'text', 'image').
        - **text** (object) - Required if type is 'text' - The text content.
          - **body** (string) - Required - The message body.
        - **image** (object) - Required if type is 'image' - Image details.
          - **mime_type** (string) - Required - The MIME type of the image.
          - **id** (string) - Required - The Meta media ID.
          - **caption** (string) - Optional - The image caption.

### Request Example
```json
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "YOUR_WHATSAPP_BUSINESS_ID",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "phone_number_id": "YOUR_PHONE_NUMBER_ID" },
            "contacts": [{ "profile": { "name": "John" }, "wa_id": "447700900123" }],
            "messages": [
              {
                "from": "447700900123", "id": "wamid.ABC", "timestamp": "1733670000",
                "type": "text", "text": { "body": "I need to speak to a human" }
              }
            ]
          }
        }
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
Indicates the message was successfully received and processed by HitlChat.

#### Response Example
(No specific response body is detailed in the source, typically an empty or success confirmation.)
```

--------------------------------

### Send Broadcast Message

Source: https://www.hitlchat.io/guides/api

Send template-based broadcast campaigns. This endpoint is for WhatsApp Business API connections.

```APIDOC
## POST /v1/public/broadcasts/send

### Description
Send template-based broadcast campaigns using the HitlChat API. This endpoint is designed for numbers connected via the WhatsApp Business API.

### Method
POST

### Endpoint
https://api-portal.hitlchat.io/api/v1/public/broadcasts/send

### Parameters
#### Request Body
- **recipient_numbers** (array of strings) - Required - An array of recipient phone numbers.
- **template_name** (string) - Required - The name of the approved Meta template.
- **template_data** (object) - Optional - Data to populate the template variables.
- **scheduled_datetime** (string) - Optional - The date and time to schedule the broadcast (ISO 8601 format).

### Request Example
```json
{
  "recipient_numbers": ["+1234567890", "+1987654321"],
  "template_name": "welcome_message",
  "template_data": {
    "name": "John Doe"
  },
  "scheduled_datetime": "2024-07-27T10:00:00Z"
}
```

### Response
#### Success Response (200)
- **broadcast_id** (string) - The unique identifier for the broadcast campaign.
- **status** (string) - The status of the broadcast (e.g., 'scheduled', 'processing').

#### Response Example
```json
{
  "broadcast_id": "brd_abc123def456",
  "status": "scheduled"
}
```
```
Tokens:
Raw