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 Topic-based Routing es una funcionalidad avanzada que encamina los handoffs a operadores concretos según el tema de la conversación. Cada perfil de enrutamiento define un tema, una descripción de cuándo aplica y una lista de operadores que atienden ese tema. Cuando se activa un handoff, la IA empareja la conversación con el perfil de enrutamiento más relevante y notifica a los operadores asignados. Configura los perfiles de enrutamiento mediante el array routing_profiles en la petición PUT.

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 se activa un handoff, la IA evalúa la conversación frente a todos los perfiles de enrutamiento activos y la empareja con el tema más relevante. A continuación se notifica a los operadores listados en ese perfil. Si ningún perfil de enrutamiento coincide, se usa el comportamiento de notificación por defecto (la lista de correos en settings.emails).

Ejemplo: Tienes un perfil de enrutamiento “Billing” asignado a tu equipo financiero y un perfil “Technical Support” asignado a los ingenieros. Cuando un cliente pregunta por una factura y activa un handoff, la IA empareja la conversación con “Billing” y notifica únicamente al equipo financiero, no a los ingenieros.

Configura los perfiles de enrutamiento en el Dashboard, en Handoff > Topic-based Routing, o mediante el array routing_profiles en la petición PUT.

Field	Description
id integer	ID del perfil de enrutamiento
name string	Nombre del tema (p. ej., “Billing”, “Technical Support”) (máx. 100 caracteres)
description string	Cuándo debe coincidir este perfil: describe los tipos de conversaciones que deberían enrutarse a estos operadores (máx. 2000 caracteres)
is_active boolean	Si este perfil de enrutamiento está activado
user_ids array of integers	IDs de los operadores a los que se debe notificar cuando este perfil coincide

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. Debes incluir todas las secciones (settings, availability, generic_guidelines, custom_guidelines, routing_profiles) en el cuerpo de la petición. Omitir una sección o proporcionar datos parciales provocará errores de validación. 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.

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.

---