Conversaciones

Lo que aprenderás: Esta página explica cómo funcionan las conversaciones en ZappWay, cómo enumerarlas y administrarlas, cómo actualizar su estado de forma masiva, cómo exportarlas y cómo usar la función de resumen de IA.

🔢 Tabla de contenidos

Overview
Endpoint Reference
Listing Conversations
Managing a Conversation
Bulk Status Update
Export Conversations
Evaluating Answers
Response Format
Best Practices
Troubleshooting

1. Descripción general

¿Qué es una conversación?

Una Conversación en ZappWay es un hilo completo de mensajes entre un contacto y su organización, mediado por un empleado de IA, un agente humano o ambos. Las conversaciones pueden originarse en:

💬 WhatsApp (API empresarial)
📧 Bandeja de entrada de correo electrónico
🌐 Widget (chat del sitio web)
📱 DM de TikTok
🔌 Cualquier integración conectada

Cada conversación tiene:

Un contacto: con quién es la conversación.
Un canal: donde se desarrolla la conversación.
Un estado: open, resolved o snoozed
Una asignación de Empleado AI (opcional)
Un hilo de mensajes completo con marcas de tiempo

IA y colaboración humana

Las conversaciones admiten un modelo híbrido: el empleado de IA puede manejar los mensajes automáticamente y un agente humano puede hacerse cargo en cualquier momento. Los mensajes de la IA y los mensajes humanos aparecen en el mismo hilo.

2. Referencia de punto final

Método	Punto final	Descripción	Autenticación
`GET`	`/api/conversations`	Listar conversaciones con filtros	Autenticación opcional (soporte de widgets)
`HEAD`	`/api/conversations`	Comprobación previa de CORS	Ninguno
`GET`	`/api/conversations/[conversationId]`	Obtener una conversación específica	Sesión de organización
`PATCH`	`/api/conversations/[conversationId]`	Actualizar conversación (asignar agente, establecer estado)	Sesión de organización
`DELETE`	`/api/conversations/[conversationId]`	Eliminar una conversación	Sesión de organización
`POST`	`/api/conversations/update-status`	Actualización masiva de estados de conversación	Sesión de organización
`POST`	`/api/conversations/bulk-unread`	Marcar conversaciones como no leídas de forma masiva	Sesión de organización
`GET`	`/api/conversations/export`	Exportar conversaciones a un archivo	Sesión de organización
`POST`	`/api/conversations/[conversationId]/eval-answer`	Evaluar la calidad de las respuestas de la IA	Sesión de organización

3. Listado de conversaciones

Listar conversaciones

GET /api/conversations

Admite autenticación opcional: las solicitudes autenticadas devuelven conversaciones de la organización; Las solicitudes no autenticadas pueden devolver conversaciones de widgets públicos. Parámetros de consulta:

Parámetro	Tipo	Descripción
`status`	`"open" \| "resolved" \| "snoozed"`	Filtrar por estado de conversación
`agentId`	`string`	Filtrar por empleado de IA asignado
`contactId`	`string`	Filtrar por contacto
`channel`	`string`	Filtrar por canal (por ejemplo, `whatsapp`, `email`, `widget`)
`page`	`number`	Número de página para paginación
`limit`	`number`	Número de resultados por página
`search`	`string`	Búsqueda de texto completo en el contenido de la conversación
`dateFrom`	`ISO 8601`	Filtrar conversaciones después de esta fecha
`dateTo`	`ISO 8601`	Filtrar conversaciones anteriores a esta fecha

Ejemplo: CÓDIGO_BLOQUE_1 Respuesta: CÓDIGO_BLOQUE_2 rizo: CÓDIGO_BLOQUE_3 Mecanografiado: CÓDIGO_BLOQUE_4

4. Gestionar una conversación

Obtener una conversación

GET /api/conversations/{conversationId}

Devuelve el objeto de conversación completo, incluidos todos los mensajes y detalles de contacto.

Actualizar una conversación

PATCH /api/conversations/{conversationId}
Content-Type: application/json

Cuerpo de la solicitud:

Campo	Tipo	Descripción
`status`	`"open" \| "resolved" \| "snoozed"`	Actualizar el estado de la conversación
`agentId`	`string \| null`	Asignar o desasignar un empleado de IA
`assignedUserId`	`string \| null`	Asignar a un miembro del equipo humano
`note`	`string`	Añadir una nota interna
`snoozeUntil`	`ISO 8601`	Posponer hasta una fecha específica

Ejemplo: resolver una conversación: CÓDIGO_BLOQUE_7 Ejemplo: Asignar a un empleado de IA: CÓDIGO_BLOQUE_8 Ejemplo: Posponer: CÓDIGO_BLOQUE_9

Eliminar una conversación

DELETE /api/conversations/{conversationId}

⚠️ Al eliminar una conversación se eliminan permanentemente todos los mensajes asociados. Esta acción es irreversible.

5. Actualización de estado masiva

Actualiza el estado de varias conversaciones a la vez.

POST /api/conversations/update-status
Content-Type: application/json

Cuerpo de la solicitud:

Campo	Tipo	Requerido	Descripción
`conversationIds`	`string[]`	✅	Conjunto de ID de conversación para actualizar
`status`	`"open" \| "resolved" \| "snoozed"`	✅	Nuevo estado para todas las conversaciones especificadas

Ejemplo: resolver varias conversaciones: CÓDIGO_BLOQUE_12 rizo: CÓDIGO_BLOQUE_13

Marcar como no leído en masa

POST /api/conversations/bulk-unread
Content-Type: application/json

Cuerpo de la solicitud: CÓDIGO_BLOQUE_15

6. Exportar conversaciones

Descargue conversaciones como un archivo para informes, cumplimiento o análisis.

GET /api/conversations/export

Parámetros de consulta:

Parámetro	Tipo	Descripción
`status`	`string`	Filtrar por estado antes de exportar
`dateFrom`	`ISO 8601`	Exportar conversaciones desde esta fecha
`dateTo`	`ISO 8601`	Exportar conversaciones hasta esta fecha
`format`	`"csv" \| "json"`	Formato de exportación (predeterminado: `csv`)

Ejemplo: CÓDIGO_BLOQUE_17 La respuesta contiene el archivo como un archivo adjunto descargable.

7. Evaluación de respuestas

Utilice el punto final de evaluación para calificar la calidad de las respuestas generadas por IA. Esta retroalimentación se utiliza para mejorar el rendimiento de la IA con el tiempo.

POST /api/conversations/{conversationId}/eval-answer
Content-Type: application/json

Cuerpo de la solicitud:

Campo	Tipo	Requerido	Descripción
`messageId`	`string`	✅	El ID del mensaje de IA a evaluar
`rating`	`"positive" \| "negative"`	✅	Su calificación de calidad
`feedback`	`string`	❌	Comentarios escritos opcionales

Ejemplo: CÓDIGO_BLOQUE_19

8. Formato de respuesta

Objeto de conversación

Campo	Tipo	Descripción
`id`	`string`	ID de conversación única
`contactId`	`string`	ID del contacto
`contact`	`Contact`	Objeto de contacto completo
`channel`	`string`	Canal de origen
`status`	`string`	Estado actual: `open`, `resolved`, `snoozed`
`agentId`	`string \| null`	ID de empleado de IA asignado
`assignedUserId`	`string \| null`	ID de usuario humano asignado
`lastMessageAt`	`ISO 8601`	Marca de tiempo del último mensaje
`lastMessagePreview`	`string`	Vista previa del último mensaje
`unreadCount`	`number`	Número de mensajes no leídos
`createdAt`	`ISO 8601`	Cuando se creó la conversación

Códigos de estado

Estado	Significado
`200`	Solicitud exitosa
`204`	Eliminado con éxito
`400`	Cuerpo o parámetros de solicitud no válidos
`401`	No autenticado
`403`	Permisos insuficientes
`404`	Conversación no encontrada
`500`	Error interno del servidor

9. Mejores prácticas

Gestión de estado

Estado	Usar cuando
`open`	La conversación es activa y requiere atención
`resolved`	El problema se ha solucionado por completo: la conversación ha finalizado
`snoozed`	La conversación necesita seguimiento más tarde: se reabre automáticamente en `snoozeUntil`

Consejos:

Utilice actualización de estado masiva para la gestión de colas al final del día
Establezca snoozeUntil para el siguiente día hábil para conversaciones de baja prioridad
Resuelva las conversaciones con prontitud para mantener su cola limpia

Filtrado y búsqueda

Combine filtros (por ejemplo, status=open&channel=whatsapp&agentId=agent_123) para obtener resultados precisos
Utilice search para buscar palabras clave cuando recuerde el contenido de la conversación pero no el contacto.
Exportar subconjuntos filtrados para necesidades de informes específicas.

Evaluación de respuestas de IA

Califique las respuestas de IA con regularidad para mejorar el rendimiento del modelo.
Proporcione feedback escrito para calificaciones negativas; esto ayuda a identificar patrones
Centrarse en calificar las respuestas en las que la IA cometió un error factual o no cumplió con la intención.

10. Solución de problemas

Problema	Posible causa	Solución
La conversación no aparece en la lista	Se aplicó un filtro incorrecto	Intente eliminar filtros y buscar por contacto o palabra clave
La actualización de estado masiva falla parcialmente	Algunas identificaciones no pertenecen a su organización	Verifique que todos los ID de conversación sean correctos y de su organización
La exportación devuelve un archivo vacío	Ninguna conversación coincide con el filtro de fecha/estado	Ampliar el rango de fechas o eliminar el filtro de estado
No se puede eliminar una conversación	La conversación está vinculada a una sesión de widget activa	Espere a que finalice la sesión o comuníquese con el soporte
Evaluación de respuesta de IA rechazada	`messageId` no es un mensaje generado por IA	Solo se pueden evaluar mensajes generados por IA

Agent Skills

Agent Cortex

Livia - 360 Assistant

Conversations

Access Groups

🔢 Tabla de contenidos

1. Descripción general

¿Qué es una conversación?

IA y colaboración humana

2. Referencia de punto final

3. Listado de conversaciones

Listar conversaciones

4. Gestionar una conversación

Obtener una conversación

Actualizar una conversación

Eliminar una conversación

5. Actualización de estado masiva

Marcar como no leído en masa

6. Exportar conversaciones

7. Evaluación de respuestas

8. Formato de respuesta

Objeto de conversación

Códigos de estado

9. Mejores prácticas

Gestión de estado

Filtrado y búsqueda

Evaluación de respuestas de IA

10. Solución de problemas

​🔢 Tabla de contenidos

​1. Descripción general

​¿Qué es una conversación?

​IA y colaboración humana

​2. Referencia de punto final

​3. Listado de conversaciones

​Listar conversaciones

​4. Gestionar una conversación

​Obtener una conversación

​Actualizar una conversación

​Eliminar una conversación

​5. Actualización de estado masiva

​Marcar como no leído en masa

​6. Exportar conversaciones

​7. Evaluación de respuestas

​8. Formato de respuesta

​Objeto de conversación

​Códigos de estado

​9. Mejores prácticas

​Gestión de estado

​Filtrado y búsqueda

​Evaluación de respuestas de IA

​10. Solución de problemas

🔢 Tabla de contenidos

1. Descripción general

¿Qué es una conversación?

IA y colaboración humana

2. Referencia de punto final

3. Listado de conversaciones

Listar conversaciones

4. Gestionar una conversación

Obtener una conversación

Actualizar una conversación

Eliminar una conversación

5. Actualización de estado masiva

Marcar como no leído en masa

6. Exportar conversaciones

7. Evaluación de respuestas

8. Formato de respuesta

Objeto de conversación

Códigos de estado

9. Mejores prácticas

Gestión de estado

Filtrado y búsqueda

Evaluación de respuestas de IA

10. Solución de problemas