Handoff Configuration

Human Handoff umożliwia Twojemu AI Agentowi automatyczne przekazywanie rozmów ludzkim operatorom, gdy wykryje sytuacje wymagające osobistego kontaktu. Handoff jest sterowany przez AI — AI nieustannie ocenia rozmowę względem konfigurowalnych wytycznych i wyzwala handoff w odpowiednim momencie, bez jakiejkolwiek ręcznej interwencji.

Jak działa automatyczny handoff:

1. Podczas rozmowy AI ocenia każdą wiadomość względem Twoich generic guidelines (np. frustracja użytkownika, brak wiedzy) oraz custom guidelines, które definiujesz
2. Gdy wytyczna się wyzwala, AI pokazuje odwiedzającemu wiadomość z potwierdzeniem, pytając, czy chciałby porozmawiać z człowiekiem
3. Jeśli odwiedzający potwierdzi, rozmowa jest przekazywana ludzkiemu operatorowi, wraz z opcjonalnym podsumowaniem dotychczasowej rozmowy wygenerowanym przez AI
4. Jeśli skonfigurowano godziny pracy i żądanie wykracza poza nie, zamiast tego wyświetlana jest niestandardowa wiadomość

Dodatkowe metody handoffu:

• Keyword triggers — Odwiedzający mogą wpisać określone frazy (np. “speak to human”, “agent”), aby bezpośrednio poprosić o handoff
• Ręczny handoff z Dashboardu — Operatorzy mogą przejąć dowolną rozmowę z Inboksa, zmieniając osobę przypisaną do rozmowy

Topic-based Routing to zaawansowana funkcja kierująca handoffy do określonych operatorów na podstawie tematu rozmowy. Każdy profil routingu definiuje temat, opis tego, kiedy ma zastosowanie, oraz listę operatorów obsługujących ten temat. Gdy wyzwala się handoff, AI dopasowuje rozmowę do najbardziej trafnego profilu routingu i powiadamia przypisanych operatorów. Profile routingu konfiguruje się za pomocą tablicy routing_profiles w żądaniu PUT.

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

Odpowiedź zawiera kilka zagnieżdżonych obiektów:

settings — Podstawowa konfiguracja handoffu:

Field	Description
is_active boolean	Czy human handoff jest włączony
keywords array of strings	Słowa kluczowe wyzwalające handoff (np. ["speak to human", "agent"])
ai_summary_active boolean	Wysyłaj ludzkiemu operatorowi podsumowanie rozmowy wygenerowane przez AI, gdy nastąpi handoff
topic_based_routing_active boolean	Czy routing tematyczny do określonych operatorów jest włączony (tylko do odczytu, konfigurowany przez profile routingu)
question_message string	Wiadomość pokazywana odwiedzającemu z pytaniem, czy chce zostać połączony z człowiekiem
confirmation_message string	Wiadomość pokazywana po potwierdzeniu handoffu przez odwiedzającego (maks. 500 znaków)
confirmation_outside_working_hours_message string	Wiadomość pokazywana, gdy handoff zostaje zażądany poza godzinami pracy (maks. 500 znaków)
working_hours_active boolean	Ogranicz handoff tylko do godzin pracy
timezone string	Strefa czasowa dla godzin pracy (np. "Europe/London")
send_email_notification boolean	Wysyłaj operatorom powiadomienia e-mail przy handoffie
emails array of strings	Adresy e-mail do powiadamiania

availability — Harmonogram godzin pracy (tablica slotów):

Field	Description
id integer	ID slotu dostępności
day_span string	Dzień lub zakres dni (np. "monday", "monday-friday")
start_time string	Czas rozpoczęcia w formacie "HH:MM"
end_time string	Czas zakończenia w formacie "HH:MM"

generic_guidelines — Predefiniowane reguły wyzwalające handoff (tablica):

Field	Description
name string	Typ wytycznej: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description string	Opis tego, kiedy ta wytyczna się wyzwala
is_active boolean	Czy ta wytyczna jest włączona

custom_guidelines — Reguły wyzwalające handoff zdefiniowane przez użytkownika (tablica):

Field	Description
id integer	ID wytycznej
name string	Nazwa niestandardowej wytycznej (maks. 100 znaków)
description string	Kiedy ta wytyczna powinna wyzwolić handoff (maks. 2000 znaków)
is_active boolean	Czy ta wytyczna jest włączona

routing_profiles — Routing tematyczny kieruje handoffy do właściwych operatorów na podstawie tego, czego dotyczy rozmowa.

Gdy wyzwala się handoff, AI ocenia rozmowę względem wszystkich aktywnych profili routingu i dopasowuje ją do najbardziej trafnego tematu. Operatorzy wymienieni w tym profilu są następnie powiadamiani. Jeśli żaden profil routingu nie pasuje, używane jest domyślne zachowanie powiadamiania (lista e-mail w settings.emails).

Przykład: Masz profil routingu “Billing” przypisany do swojego zespołu finansowego oraz profil “Technical Support” przypisany do inżynierów. Gdy klient pyta o fakturę i wyzwala handoff, AI dopasowuje rozmowę do “Billing” i powiadamia tylko zespół finansowy — nie inżynierów.

Profile routingu konfiguruj w Dashboardzie w sekcji Handoff > Topic-based Routing lub za pomocą tablicy routing_profiles w żądaniu PUT.

Field	Description
id integer	ID profilu routingu
name string	Nazwa tematu (np. “Billing”, “Technical Support”) (maks. 100 znaków)
description string	Kiedy ten profil powinien pasować — opisz typy rozmów, które powinny trafiać do tych operatorów (maks. 2000 znaków)
is_active boolean	Czy ten profil routingu jest włączony
user_ids array of integers	ID operatorów, którzy powinni zostać powiadomieni, gdy ten profil pasuje

Update Handoff Configuration

Scope: write_all

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

Uwaga

PUT zastępuje całą konfigurację handoffu atomowo. Musisz dołączyć wszystkie sekcje (settings, availability, generic_guidelines, custom_guidelines, routing_profiles) w body żądania. Pominięcie sekcji lub podanie częściowych danych spowoduje błędy walidacji. Aby wprowadzić zmiany przyrostowe, najpierw pobierz (GET) bieżącą konfigurację, zmodyfikuj potrzebne pola i odeślij (PUT) pełny obiekt z powrotem.

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 — Zwraca zaktualizowaną konfigurację handoffu.

---