Настройка передачи оператору

Передача оператору позволяет 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 логическое значение	Включена ли передача оператору
keywords массив строк	Ключевые фразы, запускающие передачу (например, ["speak to human", "agent"])
ai_summary_active логическое значение	Отправлять оператору созданное AI краткое изложение при передаче
topic_based_routing_active логическое значение	Включена ли маршрутизация конкретным операторам по темам (только чтение, настраивается профилями маршрутизации)
question_message строка	Сообщение посетителю с предложением связаться с человеком
confirmation_message строка	Сообщение после подтверждения передачи посетителем (до 500 символов)
confirmation_outside_working_hours_message строка	Сообщение при запросе передачи вне рабочих часов (до 500 символов)
working_hours_active логическое значение	Ограничить передачу рабочими часами
timezone строка	Часовой пояс рабочих часов (например, "Europe/London")
send_email_notification логическое значение	Отправлять операторам email-уведомления при передаче
emails массив строк	Email-адреса для уведомлений

availability: расписание рабочих часов (массив интервалов):

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

generic_guidelines: стандартные правила запуска передачи (массив):

Поле	Описание
name строка	Тип правила: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description строка	Описание условий срабатывания правила
is_active логическое значение	Включено ли правило

custom_guidelines: пользовательские правила запуска передачи (массив):

Поле	Описание
id целое число	ID правила
name строка	Название пользовательского правила (до 100 символов)
description строка	Когда правило должно запускать передачу (до 2 000 символов)
is_active логическое значение	Включено ли правило

routing_profiles: маршрутизация по темам направляет передачи подходящим операторам в зависимости от содержания разговора.

Когда AI инициирует передачу, он может выбрать участника команды из активных профилей маршрутизации. Если выбор корректен, разговор назначается этому пользователю; иначе остаётся неназначенным. Другие способы запуска передачи также могут оставить его неназначенным. Email-уведомления используют settings.send_email_notification и settings.emails независимо от выбора маршрутизации.

Пример: задайте сотруднику финансового отдела описание «Вопросы об оплате и счетах», а инженеру «Техническая поддержка». При вопросе о счёте AI может назначить разговор сотруднику финансового отдела. Настроенный список получателей email от этого не меняется.

Настройте профили в Действия и MCP > Передача оператору > Изменить действие > Маршрутизация по темам или через PUT-запрос.

Поле	Описание
user_id целое число	ID пользователя команды; он должен иметь доступ к этому AI-агенту
routing_description строка	Разговоры, которыми должен заниматься этот участник (до 150 символов; непустое значение при активном профиле)
is_active логическое значение	Включён ли профиль маршрутизации
email, first_name, last_name строки	Данные пользователя, возвращаемые 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: возвращает обновлённую конфигурацию передачи.

---