How to Set Up Headless Human Handoff (API-Only Agent Inbox)

What is headless human handoff?

In a normal HitlChat setup, HitlChat connects to WhatsApp for you and receives the messages. In headless mode, your own system stays in charge of WhatsApp — HitlChat never becomes the webhook receiver for your number and never sends messages on its own. Instead:

• Inbound: your gateway forwards the WhatsApp message to our API, and it appears in the agent inbox.
• Outbound: when an agent replies, HitlChat sends the message to your webhook as a ready-to-send Meta payload — your gateway forwards it to WhatsApp.
• Resolved: when an agent closes the chat, HitlChat fires a conversation_resolved event to your webhook so you can clean up state.

Who it’s for

Use this mode when you already run your own WhatsApp gateway and just want a human agent inbox — for example:

• You receive WhatsApp via the Meta Cloud API into your own webhook (a custom backend, automation tool, etc.).
• Your bot logic (Voiceflow, Botpress, or a custom flow) lives outside HitlChat and you only want HitlChat for the live-agent step.
• You need your gateway to remain the single point that talks to Meta for sending and receiving.

If you’d rather HitlChat manage the WhatsApp connection for you, use one of the standard methods instead — see Connect to WhatsApp.

What you need

• A HitlChat account.
• Your own WhatsApp gateway already receiving Meta webhooks for your number.
• From Meta: your WhatsApp Business Account ID, Phone Number ID, and a permanent (system-user) access token.
• A webhook URL on your gateway that can receive HitlChat’s outbound events.
• Your HitlChat API key for the inbound endpoint — it’s your User ID, shown under My Account → API.

How the two-way flow works

1. A customer messages your number → Meta → your gateway (unchanged).
2. Your gateway POSTs the message to HitlChat’s inbound API → it appears in the agent inbox.
3. An agent replies → HitlChat sends the reply to your webhook as a ready-to-send Meta payload.
4. Your gateway forwards it to Meta → the customer receives it.
5. The agent resolves the chat → HitlChat fires conversation_resolved to your webhook.

The next section shows the exact API calls and payloads for each step.

Authentication & base URL

The inbound API is authenticated with your API key as a Bearer token. Your key is your User ID, shown inside HitlChat under My Account → API.

Step 4 · Forward inbound messages

From your gateway, POST the verbatim Meta webhook payload to the inbound endpoint — no reshaping. The first message for a contact opens a conversation (and creates the contact); later messages append to it.

# Forward a text message exactly as Meta sent it
curl -X POST https://api-portal.hitlchat.io/api/v1/public/inbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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" }
          }]
        }
      }]
    }]
  }'

Inbound media (images, video, files)

Forward media verbatim too — including the Meta media id, exactly as Meta sends it. HitlChat downloads the file from Meta using the access token you saved and renders it in the inbox. No transformation needed on your side.

# The messages[] entry for an inbound image (rest of the envelope is identical)
"messages": [{
  "from": "447700900123", "id": "wamid.IMG", "timestamp": "1733670200",
  "type": "image",
  "image": { "mime_type": "image/jpeg", "id": "META_MEDIA_ID", "caption": "Receipt" }
}]

Optional: prior chat history (handoff context)

On the message that opens a conversation, you can attach a top-level prior_history array so the agent sees the earlier bot conversation. It’s text-only — for a past media turn, describe it in text.

# Add this sibling key alongside "object" / "entry"
"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" }
]

Step 5 · Receive agent replies on your webhook

When an agent replies in the inbox, HitlChat POSTs an outbound_message event to your Webhook URL. It carries meta_payload — the exact body to POST to Meta. Your gateway just forwards it with your own token.

# What HitlChat sends to your webhook
{
  "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!" }
  }
}

Step 6 · Handle the resolved event

When an agent marks the chat Resolved by Human, HitlChat fires a conversation_resolved event to the same webhook so you can clear your session state.

{
  "event": "conversation_resolved",
  "contact_number": "447700900123",
  "resolved_status": "Resolved by Human",
  "resolved_datetime": "2026-06-09T10:05:00Z"
}

Every endpoint, field and response

The full interactive reference — auto-generated from the live API — documents every parameter and lets you try calls in the browser.

Open the full API reference →