Handoff Configuration

Human Handoff enables your AI Agent to automatically transfer conversations to human operators when it detects situations that need a personal touch. Handoff is AI-driven — the AI continuously evaluates the conversation against configurable guidelines and triggers a handoff when appropriate, without any manual intervention.

How automatic handoff works:

1. During a conversation, the AI evaluates each message against your generic guidelines (e.g., user frustration, lack of knowledge) and custom guidelines you define
2. When a guideline triggers, the AI shows the visitor a confirmation message asking if they’d like to speak with a human
3. If the visitor confirms, the conversation is transferred to a human operator, with an optional AI-generated summary of the conversation so far
4. If working hours are configured and the request falls outside them, a custom message is shown instead

Additional handoff methods:

• Keyword triggers — Visitors can type specific phrases (e.g., “speak to human”, “agent”) to request handoff directly
• Manual handoff from Dashboard — Operators can take over any conversation from the Inbox by changing the conversation assignee

Topic-based routing lets the AI assign a handoff to one teammate based on that teammate’s routing description. Each profile belongs to one user; it is separate from topic categories in Insights. Configure profiles through routing_profiles in the PUT request. Assignment and email notification recipients are separate settings.

Get Handoff Configuration

Scope: read_all

GET https://app.quickchat.ai/v1/api/human_handoff/configuration

Shell

curl https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

The response contains several nested objects:

settings — Core handoff configuration:

Field	Description
is_active boolean	Whether human handoff is enabled
keywords array of strings	Trigger keywords that prompt a handoff (e.g., ["speak to human", "agent"])
ai_summary_active boolean	Send an AI-generated conversation summary to the human operator when handoff occurs
topic_based_routing_active boolean	Whether topic-based routing to specific operators is enabled (read-only, configured via routing profiles)
question_message string	Message shown to the visitor asking if they want to be connected to a human
confirmation_message string	Message shown after the visitor confirms handoff (max 500 chars)
confirmation_outside_working_hours_message string	Message shown when handoff is requested outside working hours (max 500 chars)
working_hours_active boolean	Restrict handoff to working hours only
timezone string	Timezone for working hours (e.g., "Europe/London")
send_email_notification boolean	Send email notifications to operators on handoff
emails array of strings	Email addresses to notify

availability — Working hours schedule (array of slots):

Field	Description
id integer	Availability slot ID
day_span string	Day or day range (e.g., "monday", "monday-friday")
start_time string	Start time in "HH:MM" format
end_time string	End time in "HH:MM" format

generic_guidelines — Predefined handoff trigger rules (array):

Field	Description
name string	Guideline type: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description string	Description of when this guideline triggers
is_active boolean	Whether this guideline is enabled

custom_guidelines — User-defined handoff trigger rules (array):

Field	Description
id integer	Guideline ID
name string	Custom guideline name (max 100 chars)
description string	When this guideline should trigger handoff (max 2000 chars)
is_active boolean	Whether this guideline is enabled

routing_profiles — Topic-based routing directs handoffs to the right operators based on what the conversation is about.

When the AI initiates a handoff, it can select a teammate from the active routing profiles. The conversation is assigned to that user if the selection is valid; otherwise it remains unassigned. Other handoff triggers can also leave it unassigned. Email notifications use settings.send_email_notification and settings.emails independently of the routing choice.

Example: Give a finance teammate the routing description “Billing and invoice questions” and an engineer “Technical support”. For an invoice question, the AI can assign the handoff to the finance teammate. The configured email recipient list does not change because of that assignment.

Configure profiles under Actions & MCPs > Human Handoff > Edit Action > Topic-based routing, or through the PUT request.

Field	Description
user_id integer	Teammate’s user ID; the user must have access to this AI Agent
routing_description string	Conversations this teammate should handle (max 150 characters; must be non-empty when active)
is_active boolean	Whether this routing profile is enabled
email, first_name, last_name strings	User details returned by GET; not required in PUT

Update Handoff Configuration

Scope: write_all

PUT https://app.quickchat.ai/v1/api/human_handoff/configuration

Caution

PUT replaces the entire handoff configuration atomically. Include settings, availability, generic_guidelines, and custom_guidelines. Include routing_profiles to preserve routing: omitting it defaults to an empty list and removes the existing profiles. To make incremental changes, first GET the current configuration, modify the fields you need, and PUT the full object back. Each routing profile uses user_id, routing_description, and is_active.

Shell

# First, fetch the current configuration
CONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>')

# Modify and PUT back (example: enable handoff)
echo "$CONFIG" | jq '.settings.is_active = true' | \
curl -X PUT https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @-

Python

import requests

headers = {"Authorization": "Bearer <API_TOKEN>"}

# Fetch current configuration
config = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
).json()

# Modify and PUT back
config["settings"]["is_active"] = True

response = requests.put(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
    json=config,
)
data = response.json()

Response 200 OK — Returns the updated handoff configuration.

---