Devir yapılandırması

İnsana devir, kişisel yaklaşım gerektiren durumları algıladığında AI Temsilcinizin konuşmaları otomatik olarak insan operatörlere aktarmasını sağlar. Devri AI yönetir: AI, konuşmayı sürekli olarak yapılandırılabilir yönergelere göre değerlendirir ve uygun olduğunda manuel müdahale gerektirmeden devri tetikler.

Otomatik devir nasıl çalışır?

1. Konuşma sırasında AI, her mesajı genel yönergelerinize (örneğin kullanıcının hayal kırıklığı, bilgi eksikliği) ve tanımladığınız özel yönergelere göre değerlendirir
2. Bir yönerge tetiklendiğinde AI, ziyaretçiye bir insanla görüşmek isteyip istemediğini soran onay mesajı gösterir
3. Ziyaretçi onaylarsa konuşma, o ana kadarki konuşmanın isteğe bağlı AI özetiyle birlikte insan operatöre devredilir
4. Çalışma saatleri yapılandırılmışsa ve istek bu saatlerin dışındaysa bunun yerine özel mesaj gösterilir

Diğer devir yöntemleri:

• Anahtar kelime tetikleyicileri: Ziyaretçiler devri doğrudan istemek için belirli ifadeler yazabilir (örneğin “bir insanla görüşmek istiyorum”, “temsilci”)
• Kontrol panelinden manuel devir: Operatörler konuşmanın atandığı kişiyi değiştirerek Gelen Kutusundaki herhangi bir konuşmayı devralabilir

Konuya göre yönlendirme, AI’ın ekip arkadaşının yönlendirme açıklamasına göre devri o kişiye atamasını sağlar. Her profil bir kullanıcıya aittir ve İçgörülerdeki konu kategorilerinden ayrıdır. Profilleri PUT isteğindeki routing_profiles ile yapılandırın. Atama ve e-posta bildirimi alıcıları ayrı ayarlardır.

İsteğe bağlı örnek kontrolleri

• Bir API Eylemi isteğini önizleyin. Verilen istek şablonunu göndermeden sentetik örnek değerlerle oluşturun. Kimlik bilgisi içeren üstbilgileri eklemeyin.

• Bir test veri kümesini doğrulayın. Verilen küçük veri kümesinin desteklenen biçime uygunluğunu AI Temsilcinizi çalıştırmadan kontrol edin.

Devir yapılandırmasını alma

Kapsam: 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()

Yanıt 200 OK

Yanıt, birkaç iç içe nesne içerir:

settings: temel devir yapılandırması:

Alan	Açıklama
is_active mantıksal değer	İnsana devrin etkin olup olmadığı
keywords dize dizisi	Devri başlatan anahtar kelimeler (örneğin ["speak to human", "agent"])
ai_summary_active mantıksal değer	Devir sırasında insan operatöre AI tarafından oluşturulmuş konuşma özeti gönderir
topic_based_routing_active mantıksal değer	Belirli operatörlere konuya göre yönlendirmenin etkin olup olmadığı (salt okunur, yönlendirme profilleriyle yapılandırılır)
question_message dize	Ziyaretçiye bir insana bağlanmak isteyip istemediğini soran mesaj
confirmation_message dize	Ziyaretçi devri onayladıktan sonra gösterilen mesaj (en fazla 500 karakter)
confirmation_outside_working_hours_message dize	Çalışma saatleri dışında devir istendiğinde gösterilen mesaj (en fazla 500 karakter)
working_hours_active mantıksal değer	Devri yalnızca çalışma saatleriyle sınırlar
timezone dize	Çalışma saatlerinin saat dilimi (örneğin "Europe/London")
send_email_notification mantıksal değer	Devirde operatörlere e-posta bildirimi gönderir
emails dize dizisi	Bildirim gönderilecek e-posta adresleri

availability: çalışma saatleri programı (zaman aralıkları dizisi):

Alan	Açıklama
id tamsayı	Müsaitlik zaman aralığının kimliği
day_span dize	Gün veya gün aralığı (örneğin "monday", "monday-friday")
start_time dize	"HH:MM" biçiminde başlangıç saati
end_time dize	"HH:MM" biçiminde bitiş saati

generic_guidelines: önceden tanımlanmış devir tetikleme kuralları (dizi):

Alan	Açıklama
name dize	Yönerge türü: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description dize	Bu yönergenin ne zaman tetikleneceğinin açıklaması
is_active mantıksal değer	Bu yönergenin etkin olup olmadığı

custom_guidelines: kullanıcının tanımladığı devir tetikleme kuralları (dizi):

Alan	Açıklama
id tamsayı	Yönerge kimliği
name dize	Özel yönerge adı (en fazla 100 karakter)
description dize	Bu yönergenin hangi durumda devri tetiklemesi gerektiği (en fazla 2000 karakter)
is_active mantıksal değer	Bu yönergenin etkin olup olmadığı

routing_profiles: konuya göre yönlendirme, konuşmanın konusuna göre devirleri doğru operatörlere yöneltir.

AI bir devir başlattığında etkin yönlendirme profillerinden bir ekip arkadaşı seçebilir. Seçim geçerliyse konuşma bu kullanıcıya atanır; aksi hâlde atanmamış kalır. Diğer devir tetikleyicileri de konuşmayı atanmamış bırakabilir. E-posta bildirimleri, yönlendirme seçiminden bağımsız olarak settings.send_email_notification ve settings.emails ayarlarını kullanır.

Örnek: Finans ekibinden bir kişiye “Faturalandırma ve fatura soruları”, bir mühendise ise “Teknik destek” yönlendirme açıklamasını verin. AI, bir fatura sorusunda devri finans ekibindeki kişiye atayabilir. Yapılandırılmış e-posta alıcı listesi bu atama nedeniyle değişmez.

Profilleri Eylemler ve MCP’ler > İnsana devir > Eylemi düzenle > Konuya göre yönlendirme altında veya PUT isteği üzerinden yapılandırın.

Alan	Açıklama
user_id tamsayı	Ekip arkadaşının kullanıcı kimliği; kullanıcının bu AI Temsilcisine erişimi olmalıdır
routing_description dize	Ekip arkadaşının ele alması gereken konuşmalar (en fazla 150 karakter; etkinken boş olmamalıdır)
is_active mantıksal değer	Bu yönlendirme profilinin etkin olup olmadığı
email, first_name, last_name dizeler	GET tarafından döndürülen kullanıcı ayrıntıları; PUT için gerekli değildir

Devir yapılandırmasını güncelleme

Kapsam: write_all

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

Dikkat

PUT, tüm devir yapılandırmasını atomik olarak değiştirir. settings, availability, generic_guidelines ve custom_guidelines alanlarını ekleyin. Yönlendirmeyi korumak için routing_profiles ekleyin; gönderilmezse boş liste varsayılır ve mevcut profiller kaldırılır. Kademeli değişiklikler için önce mevcut yapılandırmayı GET ile alın, gerekli alanları değiştirin ve tam nesneyi PUT ile geri gönderin. Her yönlendirme profili user_id, routing_description ve is_active kullanır.

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()

Yanıt 200 OK: güncellenmiş devir yapılandırmasını döndürür.

---