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

Topic-based Routing är en avancerad funktion som dirigerar handoffs till specifika operatörer baserat på konversationens ämne. Varje routingprofil definierar ett ämne, en beskrivning av när det gäller och en lista över operatörer som hanterar det ämnet. När en handoff utlöses matchar AI:n konversationen mot den mest relevanta routingprofilen och meddelar de tilldelade operatörerna. Konfigurera routingprofiler via arrayen routing_profiles i PUT-requesten.

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 en handoff utlöses utvärderar AI:n konversationen mot alla aktiva routingprofiler och matchar den mot det mest relevanta ämnet. Operatörerna som listas i den profilen notifieras sedan. Om ingen routingprofil matchar används standardnotifieringsbeteendet (e-postlistan i settings.emails).

Exempel: Du har en “Billing”-routingprofil tilldelad ditt finansteam och en “Technical Support”-profil tilldelad ingenjörer. När en kund frågar om en faktura och utlöser en handoff matchar AI:n konversationen mot “Billing” och notifierar endast finansteamet — inte ingenjörerna.

Konfigurera routingprofiler i Dashboard under Handoff > Topic-based Routing, eller via arrayen routing_profiles i PUT-requesten.

Field	Description
id integer	Routingprofil-ID
name string	Ämnesnamn (t.ex. “Billing”, “Technical Support”) (max 100 tecken)
description string	När denna profil ska matcha — beskriv de typer av konversationer som ska dirigeras till dessa operatörer (max 2000 tecken)
is_active boolean	Om denna routingprofil är aktiverad
user_ids array of integers	ID:n för operatörer som ska notifieras när denna profil matchar

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. Du måste inkludera alla sektioner (settings, availability, generic_guidelines, custom_guidelines, routing_profiles) i request-bodyn. Att utelämna en sektion eller ange partiell data leder till valideringsfel. För att göra inkrementella ändringar, gör först en GET av den aktuella konfigurationen, ändra de fält du behöver och PUT:a tillbaka hela objektet.

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.

---