Human-in-the-Loop: Approvals and Assistant Handoffs

Not every decision should be left to an AI. Feather’s Human-in-the-Loop (HITL) system lets you define exactly when a human needs to be in the conversation — whether that’s approving a high-stakes action before the assistant executes it, or handing the entire thread to a live support agent. Both modes keep the customer experience coherent: the user sees consistent messages and the operator has full context from the start.

Two HITL modes

Approvals

The assistant pauses mid-conversation before executing a tool call or workflow action. A human operator reviews the pending action, then approves or denies it. The assistant automatically resumes with the decision and continues the conversation.

Handoffs

The assistant transfers the entire conversation to a human operator. The operator sends messages that are relayed directly to the end user. When the issue is resolved, the operator closes the handoff and the session ends gracefully.

Handling approvals

When a conversation reaches an action that requires sign-off, the assistant enters awaiting_approval status and waits — it will not proceed until a decision is recorded.

List pending approval requests

Poll this endpoint from your operator dashboard or webhook handler to surface requests that need attention.

curl "https://api-sandbox.featherhq.com/v1/hitl/approvals?status=pending" \
  -H "x-api-key: <your_api_key>"

import requests

response = requests.get(
    "https://api-sandbox.featherhq.com/v1/hitl/approvals",
    headers={"x-api-key": "<your_api_key>"},
    params={"status": "pending"}
)
print(response.json())

const response = await fetch(
  "https://api-sandbox.featherhq.com/v1/hitl/approvals?status=pending",
  { headers: { "x-api-key": "<your_api_key>" } }
);
const data = await response.json();

The response lists approval summaries including the subject_ref, approver_role, and the suspend_message shown to the user.

Fetch full approval detail

Retrieve the complete record for a specific approval — including the action payload the assistant wants to execute.

curl "https://api-sandbox.featherhq.com/v1/hitl/approvals/<approval_id>" \
  -H "x-api-key: <your_api_key>"

ApprovalRequestDetail fields:

Field	Type	Description
`id`	string	Unique approval request ID
`conversation_id`	string	The conversation this approval belongs to
`subject_kind`	enum	`workflow_node` or `tool_call`
`subject_ref`	string	Identifier of the node or tool awaiting approval
`payload`	object	The full action payload the assistant intends to execute
`approver_role`	string	The operator role required to approve this action
`suspend_message`	string	Message currently displayed to the end user
`timeout_at`	ISO 8601	When the request auto-expires if no decision is made

Submit your decision

Approve or deny the pending action. Include a note when denying so the assistant can explain the outcome to the user.

curl -X POST \
  "https://api-sandbox.featherhq.com/v1/hitl/approvals/<approval_id>/decide" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"decision": "approve"}'

curl -X POST \
  "https://api-sandbox.featherhq.com/v1/hitl/approvals/<approval_id>/decide" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "deny",
    "note": "This refund amount exceeds the policy limit. Escalate to manager."
  }'

Once the decision is submitted, the conversation automatically resumes. If approved, the assistant executes the action. If denied, the assistant receives the denial note and responds to the user accordingly.

Handling handoffs

When an assistant triggers a handoff, the conversation transitions to waiting_for_human status. The assistant is no longer generating responses — a human operator takes over completely.

List pending handoffs

curl "https://api-sandbox.featherhq.com/v1/hitl/handoffs?status=requested" \
  -H "x-api-key: <your_api_key>"

requests.get(
    "https://api-sandbox.featherhq.com/v1/hitl/handoffs",
    headers={"x-api-key": "<your_api_key>"},
    params={"status": "requested"}
)

Review the handoff context

Fetch the full handoff record to understand why the assistant escalated and what the customer’s situation is before you write your first message.

curl "https://api-sandbox.featherhq.com/v1/hitl/handoffs/<handoff_id>" \
  -H "x-api-key: <your_api_key>"

The packet field contains everything the assistant prepared for the handoff:

{
  "id": "hoff_01hxd4p6ns9qr7u1bgkm",
  "conversation_id": "conv_01hxd3m5mr8qp6t0zdfh",
  "status": "requested",
  "packet": {
    "static_text": "The customer is experiencing a billing discrepancy on their last invoice.",
    "reason": "Issue requires access to billing backend — outside assistant permissions.",
    "summary": "Customer Alex reported a $50 overcharge on invoice #INV-2024-0891. They have already tried self-service and need manual correction.",
    "transcript_ptr": {
      "conversation_id": "conv_01hxd3m5mr8qp6t0zdfh",
      "up_to_seq": 12
    }
  }
}

Packet field	Description
`static_text`	A short briefing sentence visible at the top of the handoff card.
`reason`	Why the assistant decided to escalate.
`summary`	A longer AI-generated summary of the conversation so far.
`transcript_ptr`	Watermark pointer `{conversation_id, up_to_seq}` indicating the conversation message `seq` up to which the transcript had been captured at handoff time.

Relay a message to the user

Send messages as the human operator. They appear in the customer’s conversation thread immediately.

curl -X POST \
  "https://api-sandbox.featherhq.com/v1/hitl/handoffs/<handoff_id>/messages" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hi, I'\''m Sarah from support. I can see the billing issue on your account — let me get that corrected for you right now."
  }'

requests.post(
    f"https://api-sandbox.featherhq.com/v1/hitl/handoffs/<handoff_id>/messages",
    headers={"x-api-key": "<your_api_key>"},
    json={"content": "Hi, I'm Sarah from support. I can see the billing issue on your account — let me get that corrected for you right now."}
)

You can send as many messages as needed. The customer replies are visible by polling GET /v1/conversations/{id}/messages.

Resolve the handoff

When the issue is resolved, close the handoff. The conversation is marked HANDOFF_RESOLVED and the session ends.

curl -X POST \
  "https://api-sandbox.featherhq.com/v1/hitl/handoffs/<handoff_id>/resolve" \
  -H "x-api-key: <your_api_key>"

Poll GET /v1/conversations/{id}/messages?since_seq={n} to receive the end user’s replies in real time during an active handoff. Pass the sequence number of the last message you’ve read as since_seq to receive only new messages.

Custom approval messages

While a conversation is paused waiting for approval, the end user sees a holding message. You can customize both the initial holding message and the follow-up patience message to match your brand voice.

curl -X PUT https://api-sandbox.featherhq.com/v1/hitl/approval-messages \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "holding_line": "Let me connect you with a specialist. One moment please.",
    "waiting_reply": "I'\''m still working on connecting you. Thank you for your patience."
  }'

requests.put(
    "https://api-sandbox.featherhq.com/v1/hitl/approval-messages",
    headers={"x-api-key": "<your_api_key>"},
    json={
        "holding_line": "Let me connect you with a specialist. One moment please.",
        "waiting_reply": "I'm still working on connecting you. Thank you for your patience."
    }
)

Field	When it’s shown
`holding_line`	Sent to the user immediately when the conversation enters `awaiting_approval`.
`waiting_reply`	Sent if the user sends another message while still waiting (the “still here” acknowledgement).

Configuring HITL in workflows

Approval and handoff behaviors are configured as nodes in your assistant’s workflow graph. Here’s how both node types look in a workflow definition:

{
  "id": "approve_refund",
  "type": "approval",
  "condition": {
    "type": "expression",
    "expression": "refund_amount > 100"
  },
  "approver_role": "billing_manager",
  "suspend_message": "I'm reviewing your refund request with our billing team. This usually takes just a moment.",
  "timeout_seconds": 300,
  "on_approve": "process_refund",
  "on_deny": "explain_denial"
}

{
  "id": "handoff_to_support",
  "type": "handoff",
  "static_text": "Transferring to a live support agent."
}

An Approval Node’s condition is a deterministic expression: when it evaluates to false the node is a pass-through and no approval is requested. When it’s true, the runtime suspends and emits an approval request. On resume, on_approve and on_deny each name the next node to route to for that decision — a timeout is recorded as a deny, so it follows the on_deny path.

Get Started

Core Concepts

Guides

Channels

Human-in-the-Loop: Approvals and Assistant Handoffs

Two HITL modes

Approvals

Handoffs

Handling approvals

Handling handoffs

Custom approval messages

Configuring HITL in workflows

​Two HITL modes

Approvals

Handoffs

​Handling approvals

​Handling handoffs

​Custom approval messages

​Configuring HITL in workflows

Two HITL modes

Handling approvals

Handling handoffs

Custom approval messages

Configuring HITL in workflows