Handoff Configuration

Human Handoff gör det möjligt för din AI Agent att automatiskt överföra konversationer till mänskliga operatörer när den upptäcker situationer som behöver en personlig touch. Handoff är AI-driven — AI:n utvärderar kontinuerligt konversationen mot konfigurerbara riktlinjer och utlöser en handoff när det är lämpligt, utan någon manuell inblandning.

Så fungerar automatisk handoff:

1. Under en konversation utvärderar AI:n varje meddelande mot dina generiska riktlinjer (t.ex. användarfrustration, kunskapsbrist) och anpassade riktlinjer som du definierar
2. När en riktlinje utlöses visar AI:n besökaren ett bekräftelsemeddelande som frågar om de vill prata med en människa
3. Om besökaren bekräftar överförs konversationen till en mänsklig operatör, med en valfri AI-genererad sammanfattning av konversationen så långt
4. Om arbetstider är konfigurerade och förfrågan faller utanför dem visas i stället ett anpassat meddelande

Ytterligare handoff-metoder:

• Nyckelordsutlösare — Besökare kan skriva specifika fraser (t.ex. “speak to human”, “agent”) för att begära handoff direkt
• Manuell handoff från Dashboard — Operatörer kan ta över valfri konversation från Inbox genom att ändra konversationens ansvarige

Ämnesbaserad dirigering låter AI:n tilldela en överlämning till en teammedlem utifrån teammedlemmens dirigeringsbeskrivning. Varje profil hör till en användare och är separat från ämneskategorierna i Insikter. Konfigurera profiler via routing_profiles i PUT-requesten. Tilldelning och mottagare av e-postaviseringar är separata inställningar.

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

Svaret innehåller flera nästlade objekt:

settings — Grundläggande handoff-konfiguration:

Field	Description
is_active boolean	Om human handoff är aktiverat
keywords array of strings	Utlösande nyckelord som föranleder en handoff (t.ex. ["speak to human", "agent"])
ai_summary_active boolean	Skicka en AI-genererad konversationssammanfattning till den mänskliga operatören när handoff sker
topic_based_routing_active boolean	Om ämnesbaserad routing till specifika operatörer är aktiverad (skrivskyddad, konfigureras via routingprofiler)
question_message string	Meddelande som visas för besökaren och frågar om de vill kopplas till en människa
confirmation_message string	Meddelande som visas efter att besökaren bekräftat handoff (max 500 tecken)
confirmation_outside_working_hours_message string	Meddelande som visas när handoff begärs utanför arbetstid (max 500 tecken)
working_hours_active boolean	Begränsa handoff till endast arbetstid
timezone string	Tidszon för arbetstider (t.ex. "Europe/London")
send_email_notification boolean	Skicka e-postnotiser till operatörer vid handoff
emails array of strings	E-postadresser att notifiera

availability — Arbetstidsschema (array av tidsluckor):

Field	Description
id integer	ID för tillgänglighetslucka
day_span string	Dag eller dagintervall (t.ex. "monday", "monday-friday")
start_time string	Starttid i formatet "HH:MM"
end_time string	Sluttid i formatet "HH:MM"

generic_guidelines — Fördefinierade utlösningsregler för handoff (array):

Field	Description
name string	Riktlinjetyp: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description string	Beskrivning av när denna riktlinje utlöses
is_active boolean	Om denna riktlinje är aktiverad

custom_guidelines — Användardefinierade utlösningsregler för handoff (array):

Field	Description
id integer	Riktlinje-ID
name string	Namn på anpassad riktlinje (max 100 tecken)
description string	När denna riktlinje ska utlösa handoff (max 2000 tecken)
is_active boolean	Om denna riktlinje är aktiverad

routing_profiles — Ämnesbaserad routing dirigerar handoffs till rätt operatörer baserat på vad konversationen handlar om.

När AI:n initierar en överlämning kan den välja en teammedlem bland de aktiva dirigeringsprofilerna. Om valet är giltigt tilldelas konversationen den användaren; annars förblir den otilldelad. Även andra utlösare för överlämning kan lämna den otilldelad. E-postaviseringar använder settings.send_email_notification och settings.emails oberoende av dirigeringsvalet.

Exempel: Ge en teammedlem på ekonomiavdelningen dirigeringsbeskrivningen “Billing and invoice questions” och en ingenjör “Technical support”. Vid en fakturafråga kan AI:n tilldela överlämningen till teammedlemmen på ekonomiavdelningen. Den konfigurerade listan över e-postmottagare ändras inte av den tilldelningen.

Konfigurera profiler under Åtgärder & MCPs > Överlämning till människa > Redigera åtgärd > Ämnesbaserad dirigering eller via PUT-requesten.

Field	Description
user_id integer	Teammedlemmens användar-ID; användaren måste ha åtkomst till denna AI-agent
routing_description string	Konversationer som teammedlemmen ska hantera (max 150 tecken; får inte vara tom när profilen är aktiv)
is_active boolean	Om denna routingprofil är aktiverad
email, first_name, last_name strings	Användaruppgifter som returneras av GET; krävs inte i PUT

Update Handoff Configuration

Scope: write_all

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

Caution

PUT ersätter hela handoff-konfigurationen atomärt. Inkludera settings, availability, generic_guidelines och custom_guidelines. Inkludera routing_profiles för att behålla dirigeringen: om fältet utelämnas används en tom lista som standard och befintliga profiler tas bort. För att göra inkrementella ändringar, hämta först den aktuella konfigurationen med GET, ändra de fält du behöver och skicka tillbaka hela objektet med PUT. Varje dirigeringsprofil använder user_id, routing_description och 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 — Returnerar den uppdaterade handoff-konfigurationen.

---