Налаштування передавання

Передавання оператору дає AI-агенту змогу автоматично передавати розмови людям, коли він виявляє ситуації, що потребують особистої допомоги. Передаванням керує AI: він постійно оцінює розмову за налаштованими правилами та запускає передавання, коли це доречно, без ручного втручання.

Як працює автоматичне передавання:

1. Під час розмови AI оцінює кожне повідомлення за вашими загальними правилами (наприклад, невдоволення користувача чи брак знань) і визначеними вами власними правилами
2. Коли спрацьовує правило, AI запитує відвідувача, чи хоче він поспілкуватися з людиною
3. Якщо відвідувач погоджується, розмова передається оператору, за потреби разом зі згенерованим AI підсумком попередньої розмови
4. Якщо задано робочі години й запит надходить поза ними, натомість показується налаштоване повідомлення

Додаткові способи передавання:

• Ключові слова: відвідувачі можуть ввести певні фрази (наприклад, «поговорити з людиною», «оператор»), щоб безпосередньо попросити передавання
• Ручне передавання з панелі керування: оператори можуть узяти будь-яку розмову у Вхідних, змінивши її виконавця

Маршрутизація за темами дає AI змогу призначити передану розмову одному учаснику команди за його описом маршрутизації. Кожен профіль належить одному користувачу й не пов’язаний із категоріями тем в Аналітиці. Налаштовуйте профілі через routing_profiles у запиті PUT. Призначення виконавця й одержувачі сповіщень email налаштовуються окремо.

Необов’язкові перевірки прикладів

• Попередній перегляд запиту дії API. Побудуйте запит із наданого шаблону й синтетичних тестових значень без надсилання. Не додавайте заголовки з обліковими даними.

• Перевірка тестового набору даних. Перевірте невеликий наданий набір даних на відповідність підтримуваному формату без запуску AI-агента.

Отримання налаштувань передавання

Область доступу: 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()

Відповідь 200 OK

Відповідь містить кілька вкладених об’єктів:

settings: основні налаштування передавання:

Поле	Опис
is_active boolean	Чи ввімкнено передавання оператору
keywords array of strings	Ключові слова для запуску передавання (наприклад, ["speak to human", "agent"])
ai_summary_active boolean	Надсилати оператору підсумок розмови, створений AI, під час передавання
topic_based_routing_active boolean	Чи ввімкнено маршрутизацію до конкретних операторів за темами (лише читання, задається через профілі маршрутизації)
question_message string	Запитання відвідувачу, чи бажає він поспілкуватися з людиною
confirmation_message string	Повідомлення після підтвердження передавання (до 500 символів)
confirmation_outside_working_hours_message string	Повідомлення для запиту передавання поза робочими годинами (до 500 символів)
working_hours_active boolean	Обмежувати передавання робочими годинами
timezone string	Часовий пояс робочих годин (наприклад, "Europe/London")
send_email_notification boolean	Надсилати операторам сповіщення email під час передавання
emails array of strings	Адреси email одержувачів сповіщень

availability: розклад робочих годин (масив часових інтервалів):

Поле	Опис
id integer	ID інтервалу доступності
day_span string	День або діапазон днів (наприклад, "monday", "monday-friday")
start_time string	Час початку у форматі "HH:MM"
end_time string	Час завершення у форматі "HH:MM"

generic_guidelines: попередньо визначені правила запуску передавання (масив):

Поле	Опис
name string	Тип правила: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description string	Опис умов спрацьовування правила
is_active boolean	Чи ввімкнено правило

custom_guidelines: власні правила запуску передавання (масив):

Поле	Опис
id integer	ID правила
name string	Назва власного правила (до 100 символів)
description string	Коли правило має запускати передавання (до 2 000 символів)
is_active boolean	Чи ввімкнено правило

routing_profiles: маршрутизація за темами спрямовує розмови до потрібних операторів залежно від змісту.

Коли AI запускає передавання, він може вибрати учасника команди з активних профілів маршрутизації. Якщо вибір коректний, розмова призначається цьому користувачу; інакше вона залишається без виконавця. Інші тригери передавання також можуть залишити розмову непризначеною. Сповіщення email використовують settings.send_email_notification і settings.emails незалежно від вибору маршруту.

Приклад: задайте співробітнику фінансового відділу опис «Питання оплати й рахунків», а інженеру «Технічна підтримка». Для питання про рахунок AI може призначити розмову фінансовому співробітнику. Налаштований список одержувачів email від цього не змінюється.

Налаштуйте профілі в Дії та MCP > Передавання оператору > Редагувати дію > Маршрутизація за темами або через запит PUT.

Поле	Опис
user_id integer	ID учасника команди; користувач повинен мати доступ до цього AI-агента
routing_description string	Розмови, які має опрацьовувати цей учасник команди (до 150 символів; обов’язкове непорожнє значення для активного профілю)
is_active boolean	Чи ввімкнено цей профіль маршрутизації
email, first_name, last_name strings	Дані користувача у відповіді GET; не обов’язкові для PUT

Оновлення налаштувань передавання

Область доступу: write_all

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

Обережно

PUT атомарно замінює всі налаштування передавання. Додайте settings, availability, generic_guidelines і custom_guidelines. Щоб зберегти маршрутизацію, додайте routing_profiles: без цього поля використовується порожній список і наявні профілі видаляються. Для часткових змін спочатку отримайте поточні налаштування через GET, змініть потрібні поля та надішліть повний об’єкт через PUT. Кожен профіль містить user_id, routing_description і 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()

Відповідь 200 OK: повертає оновлені налаштування передавання.

---