Servicio humano

Cuando se elige Webhook como método de acceso al servicio humano, primero se debe crear un servicio Webhook en el entorno del servidor. Se deben proporcionar las tres interfaces siguientes según las especificaciones para recibir solicitudes de servicio humano, mensajes de usuario y mensajes de respuesta del servicio de atención al cliente humana. GPTBots también proporciona dos interfaces para recibir mensajes de respuesta del servicio de atención al cliente e instrucciones de cierre de conversación.

Notas importantes:

1. Se debe garantizar que el servicio Webhook funcione correctamente, ya que afecta directamente al funcionamiento del servicio de soporte humano.

• Si se muestra «Busy» tras iniciar el soporte humano, indica que el servicio Webhook no funciona correctamente.
• Si se muestra «Connecting» tras iniciar el soporte humano, indica que el servicio Webhook funciona con normalidad.

2. Después de iniciar correctamente una solicitud de servicio de soporte humano:

• Se debe llamar a la interfaz Reply to User Message (https://api.gptbots.ai/v1/human/message/receive) para responder al usuario con, al menos, un mensaje, a fin de establecer la conexión de la conversación.
• Si no se responde al mensaje del usuario dentro del período de waiting timeout configurado (valor predeterminado: 60 segundos), la conversación de soporte humano se finalizará automáticamente.

Recepción de la solicitud de conversación de servicio humano

Cuando un usuario final inicia una solicitud de servicio humano, GPTBots reenvía dicha solicitud al servicio Webhook. Un código de estado de respuesta 200 devuelto por el servicio de interfaz indica que la conversación del servicio humano se ha creado correctamente.

Método de solicitud

POST

Endpoint

https://YOUR_DOMAIN/human/service/conversation/establish

Ejemplo de solicitud

                      
                      curl -X POST 'https://YOUR_DOMAIN/human/service/conversation/establish' \
-H 'Content-Type: application/json' \
-d '{
  "body": [
    {
      "text": "human service",
      "message_type": "QUESTION"
    },
    {
      "text": "content",
      "message_type": "ANSWER"
    },
    {
      "text": "content",
      "files": {
        "content_type":"Image",
        "url":"http://gptbots.ai/example.jpg"
      },
      "message_type": "QUESTION"
    }
  ],
  "timestamp": 1742265090895,
  "email": "bob@gmail.com",
  "conversation_id": "67d8db020fa31d1ef64f53dg",
  "bot_id": "665d88b03ce2b13cf2d573454",
  "user_info": {
    "phone": null,
    "email": "bob@gmail.com",
    "user_id": "KDslas",
    "anonymous_id": "652face5184b30540a6ea7fe"
  }
}'

                    

Nota: El conversation_id de este cuerpo de solicitud solo se utiliza para identificar el ID único de la conversación en escenarios de conversación de servicio humano, que es diferente del ID único generado por Crear ID de conversación (Create Conversation ID) para escenarios de conversación del agente.

Parámetros de la solicitud

Notas sobre el campo email:

• Al iniciar el servicio humano mediante iframe/Share/Bubble Widget, el usuario debe completar su correo electrónico. También se permite a los desarrolladores personalizar el correo electrónico del usuario para evitar que el usuario tenga que introducir un correo electrónico.
• Al solicitar el servicio humano a través de plataformas de terceros como WhatsApp/Telegram/livechat, el correo electrónico predeterminado utilizado es support@gptbots.ai. Para livechat, se puede personalizar el correo electrónico del usuario.
• Al solicitar el servicio humano mediante API, el campo email puede estar vacío. Si está vacío, el correo electrónico predeterminado utilizado es support@gptbots.ai.

Respuesta

Interfaz de chat

Con el conversation_id creado, se envía el mensaje del usuario al servicio de atención al cliente humana.

Método de solicitud

POST

Endpoint

https://your_domain/chat

Ejemplo de solicitud

                      
                      {
  "conversation_id": "conv_xxx",
  "message_id": "msg_abc124",
  "create_time": 1750000005000,
  "agent_id": "bot_xxx",
  "body": "Esta es la captura de pantalla de mi pedido",
  "timestamp": 1750000005200,
  "files": [
    {
      "content_type": "Image",
      "url": "https://files.gptbots.ai/xxx/order.png",
      "name": "order.png",
      "format": "png"
    }
  ]
}

                    

Parámetros de la solicitud

Respuesta

Interfaz para cerrar la conversación

Cuando se agota el tiempo de espera de una conversación de usuario o el agente cierra la conversación de forma activa, se llama a esta interfaz para cerrar la conversación.

Método de solicitud

POST

Endpoint

https://your_domain/conversation/close

Cabecera de la solicitud

Parámetros de la solicitud

Respuesta

Responder a mensajes del usuario

Cuando se elige webhook como método de integración de servicio humano, GPTBots proporciona una interfaz para responder a mensajes de usuario. Esta interfaz permite a los agentes de atención al cliente humanos enviar el contenido del mensaje de vuelta a los usuarios.

Método de solicitud

POST

Endpoint

https://api-${endpoint}.gptbots.ai/v1/human/message/receive

Cabecera de la solicitud

Ejemplo de solicitud

                      
                      {
  "conversation_id": "conv_xxx",
  "timestamp": 1750000000000,
  "body": "Aquí está la factura que solicitó",
  "files": [
    { "content_type": "Document", "url": "https://your-cdn.com/files/invoice.pdf", "name": "invoice.pdf", "format": "pdf" },
    { "content_type": "Image", "url": "https://your-cdn.com/files/screenshot.png", "name": "screenshot.png", "format": "png" }
  ]
}

                    

Parámetros de la solicitud

Respuesta

El servicio de atención al cliente humana cierra la conversación

Cuando se elige webhook como método de acceso al servicio humano, el servicio de atención al cliente humana proporcionado por GPTBots puede cerrar activamente la conversación cuando sea necesario. Tras el cierre, el usuario ya no recibirá mensajes del servicio de atención al cliente, a menos que el usuario inicie de nuevo una conversación de atención al cliente humana.

Método de solicitud

POST

Endpoint

https://api-${endpoint}.gptbots.ai/v1/human/close

Cabecera de la solicitud

Parámetros de la solicitud

Respuesta

Detección del estado del servicio de GPTBots

GPTBots proporciona una interfaz de comprobación de estado (health check) para detectar su propio servicio humano. Los desarrolladores pueden llamarla para comprobar si el servicio humano de GPTBots está disponible. Si devuelve el código de estado HTTP 200 y el cuerpo de la respuesta es el indicador de servicio normal en texto plano (por ejemplo, service is normal), el servicio humano de GPTBots está disponible. Esta interfaz no requiere autenticación y devuelve texto plano.

Método de solicitud

GET

Endpoint

https://api.gptbots.ai/v1/human/health

Ejemplo de solicitud

                      
                      curl -X GET 'https://api.gptbots.ai/v1/human/health'

                    

Respuesta

Cuando el servicio de GPTBots está disponible, devuelve el código de estado HTTP 200 y un indicador de servicio normal en texto plano.

                      
                      service is normal

                    

Recomendación para evaluar la disponibilidad

El llamador solo necesita el código de estado HTTP como criterio:

Establezca un tiempo de espera de solicitud razonable (por ejemplo, de 3 a 5 segundos) y realice el sondeo a una frecuencia fija (QPM: 3). Esta interfaz no requiere autenticación; no se necesita ninguna API Key.