Construye un chat con /v3/chats y /v3/messages
Cómo se relacionan /v3/chats y el envío de mensajes a un agente, y el error más común al integrar: crear un chat nuevo en cada mensaje sin darte cuenta.
Un chat en Arko no es un concepto abstracto: es un recurso con su propio ciclo de vida, expuesto en /v3/chats, y el endpoint de mensajes es la puerta por la que entran y salen los mensajes que lo llenan. Entender cómo se relacionan los dos evita el error más común al integrar: crear un chat nuevo en cada mensaje sin darte cuenta.
Dos formas de empezar una conversación
El endpoint de mensajes acepta cid, el identificador de un chat existente, o aid, el identificador del agente con el que quieres crear uno nuevo. Si mandas ambos, cid gana: el mensaje se agrega a ese chat, no crea uno nuevo. Guarda el cid que te devuelve la primera respuesta y reutilízalo en los mensajes siguientes de la misma conversación.
Qué pasa la primera vez
Cuando no existe un chat todavía, Arko lo crea con un nombre provisional —los primeros cincuenta caracteres de tu mensaje— y genera un título más descriptivo en segundo plano poco después. Si tu interfaz muestra el nombre del chat, conviene refrescarlo pasado ese momento en vez de asumir que el provisional es el definitivo.
Listar y gestionar chats existentes
- Listar chats: los del usuario, ordenados por actividad reciente, con filtros por nombre y por archivado.
- Detalle de un chat: el mismo formato que el listado, para uno puntual.
- Actualizar un chat: renombrarlo o archivarlo/desarchivarlo.
- Eliminar un chat: se borra junto con sus mensajes y las llamadas a herramientas asociadas.
El mensaje del usuario nunca se pierde
Arko persiste el mensaje del usuario antes de llamar al modelo, no después. Si el stream de la respuesta falla a mitad de camino —una desconexión, un error del proveedor—, el mensaje ya quedó guardado; lo único que falta es la respuesta del agente, que puedes reintentar sin duplicar lo que el usuario escribió.
Un chat que pierde el mensaje del usuario cuando algo falla del lado del modelo rompe la confianza más rápido que una respuesta lenta.
Cuidado con la cuota por chat
El límite de mensajes por chat cuenta solo los mensajes de rol usuario en un chat existente. Si tu integración simula «reintentos» creando mensajes de usuario repetidos en el mismo chat en vez de reintentar la llamada, gastas cuota más rápido de lo que tu propio flujo necesita.
Lleva esto a producción con Arko
Crea tu agente, conéctale tus APIs con Powers y publícalo en tu producto desde un solo panel. Empieza gratis hoy mismo.
Crear cuenta gratis
