Conversación

Chatea con la IA en tu propia app o sistema de atención al cliente, con respuestas en streaming y opciones para transferir la conversación a un agente humano, finalizarla y valorarla.

POST /v1/chat

{
  "message": "有没有 400 美元以内的潜水表？",
  "conversation_id": null,
  "user": {"id": "u_123", "name": "李四", "email": "li@example.com", "ip": "85.214.132.117", "language": null},
  "stream": false
}

Si no envías conversation_id, se crea una conversación nueva; la respuesta te la devuelve y debes incluirla en los mensajes siguientes.
El objeto user lo envía tu servidor directamente (quien llama con la API Key es de confianza); solo si lo incluyes se pueden consultar pedidos.
Idioma de respuesta predeterminado: si envías user.language (por ejemplo de, zh-CN, pt-BR), se usa ese; si no, envía user.ip y lo determinamos según la ubicación; si no envías ninguno, se usa el idioma predeterminado del panel. Si el cliente pide cambiar de idioma durante la conversación, se respeta su petición.
Con stream: false se devuelve {"conversation_id", "message", "status", "products"}; si message es null, significa que la conversación está siendo atendida por una persona y el mensaje ya se le ha transferido.
Con stream: true se devuelve SSE; los eventos se describen en la tabla siguiente.

`type` del evento	Contenido
`user_message`	Mensaje del usuario ya guardado
`delta`	Un fragmento de texto `text` de la respuesta; se concatenan en orden
`products`	Tarjetas de productos encontradas por la IA
`language`	El cliente pidió cambiar el idioma de respuesta; `language` es el nuevo código de idioma
`status`	Cambio de estado de la conversación (por ejemplo, transferencia a una persona)
`replace`	Reemplaza por completo la respuesta recibida con `text` (si hay un error, se sustituye por un mensaje de respaldo)
`queued_for_human`	La conversación está siendo atendida por una persona; no hay respuesta de la IA
`done`	Mensaje final guardado y estado de la conversación
`error`	Error

Otras interfaces

Método	Ruta	Descripción
GET	`/v1/conversations`	Lista de conversaciones, `?status=&end_user_id=`
GET	`/v1/conversations/{id}/messages`	Conversación y todos sus mensajes
POST	`/v1/conversations/{id}/messages`	Tu sistema de atención al cliente responde como agente humano: `{"content", "agent_name"}`; la conversación pasa inmediatamente al estado de atención humana
POST	`/v1/conversations/{id}/status`	Acción del lado del servicio de atención: `{"status": "ai"}` la devuelve a la IA, `{"status": "closed"}` finaliza la conversación
POST	`/v1/conversations/{id}/close`	El cliente finaliza la conversación en tu app; si ya estaba finalizada, también devuelve éxito
POST	`/v1/conversations/{id}/rating`	Valoración del cliente tras finalizar la conversación: `{"rating": "good" \| "bad", "comment": "opcional, máximo 500 caracteres"}`; se puede modificar

Estados de la conversación: ai (responde la IA), pending_human (esperando a una persona), human (siendo atendida por una persona), closed (finalizada).

En la conversación también hay: closed_by, quién la finalizó (customer el cliente, agent el agente, ai la IA cuando el cliente indica que no tiene más dudas), y rating / rating_comment / rated_at con la valoración del cliente.

Finalizar la conversación: en la cabecera de la ventana web hay un botón «Finalizar conversación» (con confirmación); en el mini programa de WeChat, el cliente también puede finalizarla enviando «结束»; si en «Configuración del bot» está activada la opción «La IA finaliza la conversación automáticamente», cuando el cliente indica claramente que no tiene más dudas, la IA se despide y finaliza la conversación. Al finalizar, en la ventana web se pide al cliente que valore si quedó satisfecho o insatisfecho y puede dejar un comentario; en WeChat se le pide que responda 1 o 2; después de eso, si el cliente vuelve a escribir, se inicia una conversación nueva.

Asignación tras la transferencia a una persona: en «Configuración del bot» se elige el modo de asignación: al agente con menos conversaciones activas (predeterminado), por turnos rotativos, o que los agentes la tomen ellos mismos. La asignación automática solo se hace a agentes que hayan seleccionado «En línea» y tengan abierta la página del panel; cada uno tiene un límite de conversaciones simultáneas (se configura en la página «Equipo»); si el agente asignado no responde en el tiempo establecido (2 minutos por defecto), se reasigna. En la conversación, assigned_member_id es el agente asignado, assigned_at es la hora de asignación y handoff_at es la hora de la transferencia a una persona. Cuando todos están ocupados, los clientes hacen cola y la ventana web muestra cuántas personas hay delante.

Horario de atención y mensajes: si se activa el horario de atención en «Configuración del bot», fuera del horario las transferencias a una persona no entran en cola y en la ventana web se muestra un formulario de mensaje (nombre, correo electrónico o teléfono, consulta); en WeChat y en las conversaciones de la API abierta, la IA pide al cliente que deje un mensaje; lo mismo ocurre dentro del horario si no hay ningún agente en línea. Los mensajes generan tickets; cuando el agente responde, si la conversación original aún no ha finalizado, la respuesta se envía en esa conversación, y si el cliente dejó un correo electrónico, también se envía un email en nombre de la tienda. Cuando solo se envía a tu sistema (modo de transferencia «Enviar a mi sistema»), no se tiene en cuenta el horario de atención.

¿Te ha resultado útil esta página?

Última actualización: 31 de octubre de 2026