contact-human

Este tool permite solicitar la intervención de un humano en una conversación, proporcionando un mensaje, detalles de contacto y un resumen opcional del contexto.

Descripción

Notifica a los administradores del sitio para que intervengan en una conversación activa, enviando notificaciones en la plataforma y/o correos electrónicos con la información proporcionada.

Parámetros

Probar API

Utiliza el API Tester integrado para probar este endpoint de manera interactiva:

Características del API Tester:

• Campos preconfigurados: Incluye todos los parámetros necesarios con ejemplos realistas
• Validación automática: Verifica que los campos obligatorios estén completos
• Selector de prioridad: Dropdown con las opciones disponibles (low, normal, high, urgent)
• Generación de código: Ejemplos automáticos en cURL, JavaScript, Python y PHP
• Respuesta en tiempo real: Muestra la respuesta del servidor inmediatamente
• Estadísticas de notificación: Información sobre cuántas notificaciones y emails fueron enviados

Campos del formulario:

Obligatorios:

• conversation_id: ID de la conversación (formato UUID)
• message: Mensaje de solicitud de intervención
• priority: Nivel de prioridad de la solicitud

Opcionales:

• agent_id: ID del agente que solicita la intervención
• summary: Resumen o contexto adicional
• name: Nombre de la persona de contacto
• email: Email de la persona de contacto

Respuesta

{
  "success": true,
  "intervention_id": "f87bdc7f-0efe-4aa5-b499-49d85be4b154",
  "conversation_id": "89a9e1f8-d23f-499d-ab42-606e9bb2c71b",
  "agent_id": "a6c4e791-8c6d-4a04-b912-9fd71bf4d9c3",
  "status": "pending",
  "message": {
    "content": "El cliente tiene problemas con la integración y requiere ayuda técnica especializada.",
    "priority": "high"
  },
  "summary": "Cliente de nivel Enterprise con problemas en la API de pagos.",
  "contact_name": "Juan Pérez",
  "contact_email": "juan.perez@empresa.com",
  "requested_at": "2023-11-15T14:30:42.123Z"
}

Códigos de respuesta

Ejemplo de uso

const result = await agent.useTools([
  {
    name: "contact-human",
    input: {
      conversation_id: "89a9e1f8-d23f-499d-ab42-606e9bb2c71b",
      message: "Cliente con problemas técnicos en la integración de la API. Ha intentado las soluciones básicas sin éxito y necesita ayuda especializada.",
      priority: "high",
      summary: "Cliente Premium con 3 tickets previos sobre el mismo tema. Ha expresado frustración con el soporte.",
      name: "María González",
      email: "maria.gonzalez@empresa.com"
    }
  }
]);
 
if (result.success) {
  console.log(`Solicitud de intervención creada. ID: ${result.intervention_id}. Estado: ${result.status}`);
}

Consulta del estado de intervención

También es posible consultar el estado de una intervención mediante el endpoint GET.

Parámetros de consulta

*Al menos uno de estos parámetros debe ser proporcionado.

Ejemplo de respuesta de consulta

{
  "success": true,
  "interventions": [
    {
      "id": "f87bdc7f-0efe-4aa5-b499-49d85be4b154",
      "conversation_id": "89a9e1f8-d23f-499d-ab42-606e9bb2c71b",
      "agent_id": "a6c4e791-8c6d-4a04-b912-9fd71bf4d9c3",
      "message": "El cliente tiene problemas con la integración y requiere ayuda técnica especializada.",
      "priority": "high",
      "status": "pending",
      "requested_at": "2023-11-15T14:30:42.123Z",
      "resolved_at": null,
      "resolved_by": null,
      "summary": "Cliente Premium con 3 tickets previos sobre el mismo tema.",
      "contact_name": "María González",
      "contact_email": "maria.gonzalez@empresa.com"
    }
  ]
}

API Tester

Puedes probar este endpoint usando el componente integrado de API Tester. Este componente está disponible en la interfaz de administración y permite:

• Configurar todos los parámetros del endpoint de manera interactiva
• Enviar solicitudes de prueba con datos reales o de ejemplo
• Ver las respuestas en tiempo real
• Generar código de ejemplo en múltiples lenguajes (cURL, JavaScript, Python, PHP)
• Validar el comportamiento del sistema de notificaciones al equipo

El API Tester incluye:

• Campos obligatorios: conversation_id, message, priority
• Campos opcionales: agent_id, summary, name, email
• Selector de prioridad: con opciones low, normal, high, urgent
• Notas informativas: sobre el comportamiento de las notificaciones por email
• Estadísticas de respuesta: muestra cuántas notificaciones y emails fueron enviados

Notas adicionales

• Al crear una solicitud de intervención, se genera automáticamente un mensaje en la conversación indicando que se ha solicitado intervención humana.
• Se envían notificaciones por correo electrónico solo a los miembros del equipo que tienen habilitadas las notificaciones por email (profile.notifications.email === true).
• Los administradores sin configuración de notificaciones se incluyen por defecto.
• Si se proporciona información de contacto (nombre y email), esta se incluirá en las notificaciones.
• El sistema utiliza SendGrid para el envío de correos y crea notificaciones internas simultáneamente.