Handoff Configuration

El Human Handoff permite a tu Agente de IA transferir automáticamente conversaciones a operadores humanos cuando detecta situaciones que requieren un toque personal. El handoff lo dirige la IA: la IA evalúa continuamente la conversación frente a directrices configurables y activa un handoff cuando es apropiado, sin ninguna intervención manual.

Cómo funciona el handoff automático:

1. Durante una conversación, la IA evalúa cada mensaje frente a tus directrices genéricas (p. ej., frustración del usuario, falta de conocimiento) y las directrices personalizadas que definas
2. Cuando una directriz se activa, la IA muestra al visitante un mensaje de confirmación preguntándole si desea hablar con una persona
3. Si el visitante confirma, la conversación se transfiere a un operador humano, con un resumen opcional de la conversación generado por IA hasta ese momento
4. Si hay horario laboral configurado y la solicitud cae fuera de él, se muestra un mensaje personalizado en su lugar

Métodos de handoff adicionales:

• Activadores por palabra clave — Los visitantes pueden escribir frases concretas (p. ej., “speak to human”, “agent”) para solicitar el handoff directamente
• Handoff manual desde el Dashboard — Los operadores pueden hacerse cargo de cualquier conversación desde la Inbox cambiando la asignación de la conversación

El Enrutamiento por tema permite a la IA asignar un handoff a un compañero según la descripción de enrutamiento de ese compañero. Cada perfil pertenece a un único usuario y es independiente de las categorías de temas de Insights. Configura los perfiles mediante routing_profiles en la petición PUT. La asignación y los destinatarios de las notificaciones por correo son ajustes independientes.

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

La respuesta contiene varios objetos anidados:

settings — Configuración principal del handoff:

Field	Description
is_active boolean	Si el human handoff está activado
keywords array of strings	Palabras clave activadoras que provocan un handoff (p. ej., ["speak to human", "agent"])
ai_summary_active boolean	Enviar al operador humano un resumen de la conversación generado por IA cuando se produce el handoff
topic_based_routing_active boolean	Si el enrutamiento por tema a operadores concretos está activado (solo lectura, se configura mediante los perfiles de enrutamiento)
question_message string	Mensaje mostrado al visitante preguntándole si quiere conectar con una persona
confirmation_message string	Mensaje mostrado después de que el visitante confirme el handoff (máx. 500 caracteres)
confirmation_outside_working_hours_message string	Mensaje mostrado cuando se solicita un handoff fuera del horario laboral (máx. 500 caracteres)
working_hours_active boolean	Restringir el handoff únicamente al horario laboral
timezone string	Zona horaria del horario laboral (p. ej., "Europe/London")
send_email_notification boolean	Enviar notificaciones por correo a los operadores en el handoff
emails array of strings	Direcciones de correo a las que notificar

availability — Calendario de horario laboral (array de franjas):

Field	Description
id integer	ID de la franja de disponibilidad
day_span string	Día o rango de días (p. ej., "monday", "monday-friday")
start_time string	Hora de inicio en formato "HH:MM"
end_time string	Hora de fin en formato "HH:MM"

generic_guidelines — Reglas predefinidas que activan el handoff (array):

Field	Description
name string	Tipo de directriz: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description string	Descripción de cuándo se activa esta directriz
is_active boolean	Si esta directriz está activada

custom_guidelines — Reglas definidas por el usuario que activan el handoff (array):

Field	Description
id integer	ID de la directriz
name string	Nombre de la directriz personalizada (máx. 100 caracteres)
description string	Cuándo debe esta directriz activar el handoff (máx. 2000 caracteres)
is_active boolean	Si esta directriz está activada

routing_profiles — El enrutamiento por tema dirige los handoffs a los operadores adecuados según el tema de la conversación.

Cuando la IA inicia un handoff, puede seleccionar un compañero entre los perfiles de enrutamiento activos. La conversación se asigna a ese usuario si la selección es válida; de lo contrario, queda sin asignar. Otros activadores de handoff también pueden dejarla sin asignar. Las notificaciones por correo utilizan settings.send_email_notification y settings.emails de forma independiente de la elección de enrutamiento.

Ejemplo: Asigna a un compañero de finanzas la descripción de enrutamiento “Billing and invoice questions” y a un ingeniero, “Technical support”. Ante una pregunta sobre una factura, la IA puede asignar el handoff al compañero de finanzas. La lista configurada de destinatarios de correo no cambia por esa asignación.

Configura los perfiles en Acciones & MCPs > Transferencia a humano > Editar acción > Enrutamiento por tema, o mediante la petición PUT.

Field	Description
user_id integer	ID de usuario del compañero; el usuario debe tener acceso a este Agente de IA
routing_description string	Conversaciones que debería atender este compañero (máx. 150 caracteres; no puede estar vacía cuando el perfil está activo)
is_active boolean	Si este perfil de enrutamiento está activado
email, first_name, last_name strings	Datos del usuario devueltos por GET; no son obligatorios en PUT

Update Handoff Configuration

Scope: write_all

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

Precaución

PUT reemplaza toda la configuración del handoff de forma atómica. Incluye settings, availability, generic_guidelines y custom_guidelines. Incluye routing_profiles para conservar el enrutamiento: si lo omites, se utiliza una lista vacía por defecto y se eliminan los perfiles existentes. Para hacer cambios incrementales, primero haz un GET de la configuración actual, modifica los campos que necesites y haz un PUT del objeto completo de vuelta. Cada perfil de enrutamiento utiliza user_id, routing_description e 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 — Devuelve la configuración del handoff actualizada.

---