Asistente de chat por API

Última actualización: 2026-10-034 min de lectura

El mismo asesor que trabaja en el panel está disponible desde su aplicación. Crea una sesión, abre el flujo, envía un mensaje y recibe la respuesta por partes. Requiere el ámbito tools:chat.

Cómo funciona

Crear una sesión: guarda el contexto de la conversación.
Abrir el flujo de eventos de la sesión.
Enviar un mensaje.
La respuesta llega por el flujo en partes hasta completarse.

Abra el flujo antes de enviar el mensaje; si no, se perderá las primeras partes de la respuesta.

Sesiones

Solicitud	Qué hace
`POST /chat/sessions`	crear una sesión
`GET /chat/sessions`	sus sesiones: `limit` 1-50 (20 por defecto; más es `400`), `cursor`, `q` (búsqueda en títulos), `projectId`, `archivedOnly`, `sort` (`recent`, `title`)
`PATCH /chat/sessions/{id}`	cambiar una sesión; al menos un campo
`DELETE /chat/sessions/{id}`	archivar

Cuerpo de POST /chat/sessions (todo opcional):

Campo	Descripción
`title`	nombre de la sesión, hasta 200 caracteres
`projectId`	proyecto al que pertenece la sesión
`mode`	`chat_consult` (por defecto); cualquier otro valor se sustituye por `chat_consult`

Campos de PATCH /chat/sessions/{id}:

Campo	Descripción
`title`	nombre nuevo, hasta 200 caracteres
`projectId`	mover a un proyecto; `null`, sacar del proyecto
`isPinned`	fijar o desfijar
`isUnread`	marcar como no leída o leída
`isArchived`	solo `false`: restaurar una sesión archivada; se archiva con `DELETE`

curl -X POST https://developers.grem.capital/api/v1/chat/sessions \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Pregunta de un cliente sobre la hipoteca"}'

La respuesta contiene sessionId: páselo en todas las llamadas siguientes. Para crear una sesión, el perfil de la cuenta debe estar completo; si no, 400.

La API ofrece el modo de asesor general. El modo de respuesta automática que funciona en el CRM del panel no se puede activar desde fuera.

Enviar un mensaje

curl -X POST https://developers.grem.capital/api/v1/chat/messages \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"SESSION_ID","text":"¿Cuánto cuesta un piso de 2 habitaciones en Podil?","clientMessageId":"msg-0001"}'

clientMessageId: su id del mensaje, obligatorio. El mismo id se responde y se cobra una sola vez: reutilícelo al repetir; es el Idempotency-Key del chat.
style (opcional): longitud de la respuesta, short, normal o detailed.

La respuesta es solo un acuse de recibo; la respuesta del asistente llega por el flujo.

Flujo de respuesta

GET /chat/stream?sessionId=SESSION_ID
Authorization: Bearer gsk_live_xxx
Accept: text/event-stream

La conexión es de larga duración; los eventos llegan a medida que se genera la respuesta:

Evento	Significado
`assistant.started`	el asistente ha empezado a responder
`assistant.delta`	el siguiente fragmento de texto, en `delta`
`assistant.done`	la respuesta está completa, el texto entero está en `text`

Si la conexión se corta, vuelva a conectarse con el mismo sessionId: el servidor reproduce la respuesta actual desde el principio. Por eso, al recibir assistant.started, borre el texto acumulado para este mensaje; si no, se duplicará.

Historial

GET /chat/history?sessionId=SESSION_ID&limit=50: los mensajes guardados de la sesión, del más antiguo al más reciente. limit de 1 a 200 (50 por defecto); la página siguiente, con cursor igual al nextCursor de la respuesta anterior. Úselo para restaurar la conversación tras recargar su interfaz.

Cobro

Acción	Cobro
`POST /chat/messages`	llamada a la API + precio del mensaje
`POST`, `PATCH`, `DELETE` sobre sesiones	llamada a la API
`GET` lista, historial, flujo	gratis

El plan Free tiene un límite diario de mensajes. Después llega 429: continúe mañana o cambie de plan. La respuesta lleva code: free_daily_limit y Retry-After hasta las 00:00 UTC, cuando el límite se reinicia.