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

Routing tematyczny pozwala AI przypisać handoff do jednego członka zespołu na podstawie jego opisu routingu. Każdy profil należy do jednego użytkownika i jest niezależny od kategorii tematów w Analityce. Skonfiguruj profile przez routing_profiles w żądaniu PUT. Przypisanie i odbiorcy powiadomień e-mail to osobne ustawienia.

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 AI inicjuje handoff, może wybrać członka zespołu spośród aktywnych profili routingu. Rozmowa zostaje przypisana do tego użytkownika, jeśli wybór jest prawidłowy; w przeciwnym razie pozostaje nieprzypisana. Inne wyzwalacze handoffu również mogą pozostawić ją nieprzypisaną. Powiadomienia e-mail korzystają z settings.send_email_notification i settings.emails niezależnie od wyboru routingu.

Przykład: Przypisz członkowi zespołu finansowego opis routingu “Billing and invoice questions”, a inżynierowi “Technical support”. W przypadku pytania o fakturę AI może przypisać handoff członkowi zespołu finansowego. Skonfigurowana lista odbiorców e-maili nie zmienia się w wyniku tego przypisania.

Profile konfiguruj w sekcji Akcje & MCPs > Przekazanie do człowieka > Edytuj akcję > Routing tematyczny lub za pomocą żądania PUT.

Field	Description
user_id integer	ID użytkownika z zespołu; musi on mieć dostęp do tego Agenta AI
routing_description string	Rozmowy, które powinien obsługiwać ten członek zespołu (maks. 150 znaków; opis nie może być pusty, gdy profil jest aktywny)
is_active boolean	Czy ten profil routingu jest włączony
email, first_name, last_name strings	Dane użytkownika zwracane przez GET; niewymagane w PUT

Update Handoff Configuration

Scope: write_all

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

Uwaga

PUT zastępuje całą konfigurację handoffu atomowo. Dołącz settings, availability, generic_guidelines i custom_guidelines. Dołącz routing_profiles, aby zachować routing: pominięcie tego pola ustawia domyślnie pustą listę i usuwa istniejące profile. Aby wprowadzić zmiany przyrostowe, najpierw pobierz (GET) bieżącą konfigurację, zmodyfikuj potrzebne pola i odeślij (PUT) pełny obiekt z powrotem. Każdy profil routingu używa user_id, routing_description i 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 — Zwraca zaktualizowaną konfigurację handoffu.

---