API de chat - Juryo

POST /api/v1/agent/chat ejecuta tu agente y responde en una sola llamada. Envías un mensaje con un identificador de conversación; Juryo guarda la conversación y responde. Sin sesión que crear, sin transcripción que gestionar, sin stream que interpretar salvo que quieras los tokens según llegan.

Base: https://chat.juryo.ai
Autenticación: Authorization: Bearer TU_CLAVE — consulta Autenticación y claves para saber qué clave usar y cómo cambiar a una nueva

Medido el 17 de agosto de 2026 con el agente en producción de un cliente: respuesta completa en unos 3 segundos (3,2 s en frío, 2,8–3,2 s en caliente), primer token en unos 2 segundos. La API de sesiones con el mismo agente: 6–11 s hasta la respuesta completa. Elige este endpoint cuando la latencia importa. Usa la API de sesiones cuando tu integración necesite que el agente te pregunte o pida aprobaciones a mitad de conversación, trabajos largos, o los controles de cancelar/limpiar/compactar/reiniciar — la tabla comparativa de esa página las muestra lado a lado.

La llamada

curl https://chat.juryo.ai/api/v1/agent/chat \
  -H 'Authorization: Bearer sk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"id": "conv-8841", "text": "Hola, quiero información sobre una reclamación por un accidente de tráfico."}'

{"id": "conv-8841", "text": "Hola, soy el asistente de tu despacho. Encantado de atenderte.\n\n¿Con quién tengo el gusto?"}

Envía el siguiente mensaje con el mismo id — el agente recuerda la conversación.

Campo	Reglas
`id`	Tu identificador de conversación, 1–200 caracteres. Mismo `id` = misma conversación. Usa uno por conversación de usuario final (un número de expediente, un id de chat, un hash del teléfono).
`text`	El mensaje del usuario, 1–20.000 caracteres. Envía o este campo o `message`, no ambos.
`message`	El mensaje como objeto estructurado, cuando quieras adjuntar campos propios. Envía o este campo o `text`, no ambos.

Juryo es dueño de la transcripción: envía solo el mensaje nuevo, nunca una lista de mensajes.

Campos propios (metadata)

Adjunta tus propios campos clave/valor a un mensaje usando la forma estructurada message. Sirve para registrar de dónde viene una conversación — una landing, una campaña, tu propia referencia — y arrastrarlo hasta el lead cuando se cualifica.

curl https://chat.juryo.ai/api/v1/agent/chat \
  -H 'Authorization: Bearer sk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{
        "id": "conv-8841",
        "message": {
          "id": "msg-1",
          "role": "user",
          "parts": [{ "type": "text", "text": "Hola, quiero información sobre un divorcio." }],
          "metadata": { "source": "landing-divorcio-es" }
        }
      }'

Campo	Reglas
`message.id`	Obligatorio. Tu identificador de este mensaje, único dentro de la conversación. Una petición sin él se rechaza con `400`.
`message.role`	Siempre `"user"`.
`message.parts`	El contenido del mensaje: `[{ "type": "text", "text": "…" }]`.
`metadata.source`	Opcional. Hasta 200 caracteres. La landing o campaña de la que viene esta conversación — el campo que necesitan la mayoría de integraciones.
cualquier otra clave	Opcional. Tus propios nombres de clave (hasta 64 caracteres) con valores de texto (hasta 500 caracteres). Máximo 20 claves en total.

Los valores deben ser texto — envía "42", no 42, y aplana cualquier estructura anidada. Una clave nueva que no hayas usado antes no requiere ningún cambio por nuestra parte. Qué ocurre con ello:

Se guarda en el contacto de la conversación y se muestra en Juryo, para que tu equipo vea de qué página o campaña viene cada conversación.
El agente puede leerlo a partir del mensaje siguiente. Los campos se guardan una vez generada la respuesta del mensaje que los trajo, así que un valor enviado en el primer mensaje está disponible para el agente desde el segundo. Si el agente debe reaccionar a ello ya en el primer mensaje, inclúyelo también en el texto.
La lectura está disponible en agentes configurados para usar datos del contacto; si el tuyo no parece verlos, pídenos que revisemos su configuración.
Cuando una conversación se cualifica como lead, viaja al registro del lead y se incluye cuando Juryo envía el lead de vuelta a tu sistema.

Los campos se fusionan clave a clave entre turnos. Enviar {"source": "landing-divorcio-es"} en el primer mensaje y {"case_ref": "A-119"} en uno posterior deja el contacto con ambos — una clave que dejas de enviar se conserva, no se borra. Vuelve a enviar una clave con otro valor para cambiarla.

metadata solo existe en la forma estructurada message. El atajo text no tiene dónde ponerlo, así que cambia a message cuando necesites campos propios. Todo lo demás — el mismo id, los modos de respuesta, la transcripción — no cambia.

Modos de respuesta

Se eligen con la cabecera Accept.

`Accept`	Recibes	Úsalo para
(ninguno) o `application/json`	`{"id", "text"}` cuando la respuesta está completa — por defecto	Integraciones servidor a servidor
`text/plain`	La respuesta en streaming como texto plano, token a token	Interfaces de chat que muestran la respuesta según llega
`text/event-stream`	El stream de eventos: Server-Sent Events estándar, un evento JSON por línea — deltas de texto, actividad de herramientas, fin	Interfaces de chat más ricas que muestran progreso y actividad de herramientas

Streaming

curl -N https://chat.juryo.ai/api/v1/agent/chat \
  -H 'Authorization: Bearer sk_live_TU_CLAVE' \
  -H 'accept: text/plain' \
  -H 'content-type: application/json' \
  -d '{"id": "conv-8841", "text": "¿Qué documentación necesitáis de mí?"}'

Lee el cuerpo según llega; la conexión se cierra cuando la respuesta está completa. Envía el siguiente mensaje con el mismo id cuando termine.

Stream de eventos

Server-Sent Events estándar: cada línea es data: seguido de un objeto JSON con un type; el stream termina con data: [DONE]. Cualquier cliente SSE en cualquier lenguaje lo lee — sin librerías.

curl -N https://chat.juryo.ai/api/v1/agent/chat \
  -H 'Authorization: Bearer sk_live_TU_CLAVE' \
  -H 'accept: text/event-stream' \
  -H 'content-type: application/json' \
  -d '{"id": "conv-8841", "text": "¿Qué documentación necesitáis de mí?"}'

data: {"type":"start"}
data: {"type":"start-step"}
data: {"type":"text-start","id":"0"}
data: {"type":"text-delta","id":"0","delta":"Hola,"}
data: {"type":"text-delta","id":"0","delta":" soy el asistente"}
data: {"type":"text-end","id":"0"}
data: {"type":"finish-step"}
data: {"type":"finish","finishReason":"stop"}
data: [DONE]

`type`	Significado
`start` / `finish`	La respuesta empieza / termina. `finish` lleva `finishReason` (`stop`, `length`, `tool-calls`, `error`).
`start-step` / `finish-step`	Un paso del modelo; una respuesta que usa herramientas tiene varios.
`text-start` / `text-delta` / `text-end`	Un segmento de texto: concatena cada `delta` al segmento con ese `id`.
`tool-input-start` / `tool-input-delta` / `tool-input-available`	El agente llama a una herramienta: `toolName`, `toolCallId`, y después el `input` completo.
`tool-output-available`	El resultado (`output`) de la herramienta para ese `toolCallId`.
`tool-output-error`	La herramienta falló (`errorText`).
`error`	El turno falló (`errorText`); el stream termina.
`[DONE]`	Fin del stream (no es JSON).

Concatena los text-delta para obtener el mismo texto que devuelve el modo JSON. Ignora los tipos de evento que no manejes — pueden aparecer nuevos.

Clientes AI SDK

El stream de eventos es el protocolo de UI message stream del AI SDK (x-vercel-ai-ui-message-stream: v1 en la respuesta), así que los clientes del AI SDK funcionan contra este endpoint sin adaptador:

import { DefaultChatTransport } from "ai";

const transport = new DefaultChatTransport({
  api: "https://chat.juryo.ai/api/v1/agent/chat",
  headers: {
    accept: "text/event-stream",
    authorization: `Bearer ${process.env.JURYO_API_KEY}`,
  },
  // Juryo guarda la transcripción en el servidor — envía solo el mensaje nuevo.
  prepareSendMessagesRequest: ({ api, body, headers, id, messages }) => ({
    api,
    body: { ...body, id, message: messages.at(-1) },
    headers,
  }),
});

Pasa el transport a useChat (React) o a cualquier otro cliente de chat del AI SDK.

Cuando una persona atiende la conversación

Cuando alguien del despacho atiende la conversación, el agente no responde. La API guarda igualmente el mensaje y devuelve 200 con text vacío (cuerpo vacío en text/plain, un stream sin texto en el stream de eventos). No muestres nada al usuario: el despacho responde desde Juryo.

Autenticación y claves

Cada petición lleva una cabecera:

Authorization: Bearer TU_CLAVE

Una clave está vinculada a un agente. La clave decide qué agente responde, así que crea una clave por cada agente que quieras exponer. También está vinculada a tu despacho — la clave por sí sola determina a quién pertenecen los datos de la conversación, y por eso nada de lo que envíes en el cuerpo puede cambiarlo.

Qué clave usar

Juryo está migrando a un sistema de claves nuevo. Ambos tipos funcionan en este endpoint, así que puedes cambiar cuando te venga bien.

Clave	Dónde se crea	Para qué
Clave API de agente (actual)	Configuración → Integraciones → Claves API de agentes → Crear clave API	Integraciones nuevas, y todo lo que construyas a partir de ahora
Clave secreta `sk_live_…` (heredada)	Configuración → Integraciones → Canales → API → Clave secreta	Integraciones de servidor existentes. Sigue plenamente soportada
Clave pública `pk_live_…` (heredada)	La misma pantalla de canales	El widget y la API de sesiones. Se acepta aquí para integraciones que ya la usan — no es la clave sobre la que empezar una nueva

Las claves API de agentes son el sistema actual. La creas tú: eliges el agente que ejecuta y le pones un nombre (por ejemplo, Backend del sitio web), y la clave se muestra una sola vez. Una clave por integración, cada una apuntando al agente que debe responder. La misma clave sirve también para el runtime de agentes, no solo para este endpoint. Las claves heredadas viven en la pantalla Canales → API, donde es el canal el que lleva el agente, no la clave. Esa diferencia es la razón de que sean dos secciones distintas.

Cambiar a una clave nueva

Tu clave anterior sigue funcionando durante el cambio. No hay ventana de corte ni despliegue coordinado:

Crea una clave API de agente para la integración y cópiala — se muestra una sola vez.
Despliégala en lugar de la anterior cuando estés listo.
Cuando esté en producción, elimina la clave anterior desde la pantalla Canales → API.

Si algo falla en el paso 2, vuelve a poner la clave anterior — no ha cambiado nada en ella al crear la nueva.

Guarda las claves de servidor en tu servidor — nunca en el navegador ni en una app móvil. Una clave se almacena como hash y se muestra una sola vez, al crearla; si la pierdes, emite una nueva en lugar de intentar recuperarla. Rotar una clave heredada sk_live_… con Regenerar en la pantalla del canal invalida la anterior al instante, así que despliega primero la sustituta. La clave pública pk_live_… está diseñada para aparecer en una página web y no es un secreto.

Errores

Estado	Significado
`400`	El cuerpo no es JSON; falta `id` / `text` o son demasiado largos; o `metadata` tiene una forma incorrecta — un valor que no es texto, demasiadas claves, o una clave o valor por encima de su límite. Detalle en `issues`
`401`	Clave ausente o desconocida
`403`	La clave no tiene agente asociado
`404`	El agente de la clave está inactivo
`429`	Límite de peticiones superado — 60 turnos por minuto por clave; espera los segundos de la cabecera `Retry-After` y reintenta

En los modos de streaming, un fallo a mitad de respuesta cierra el stream antes de tiempo (el stream de eventos envía antes un evento error); reintenta con el mismo id.

Conviene saber

Memoria: la conversación se guarda por agente e id, y se reproduce en cada turno.
Tu bandeja: cada turno se registra además como una conversación en Juryo, contra un contacto creado para ese id — así una conversación de API aparece en la bandeja junto a las de WhatsApp y el widget. Los metadata que envíes se guardan en ese contacto.
Herramientas: las integraciones conectadas del agente (calendario, correo vía Composio) y las herramientas HTTP definidas por tu administrador se ejecutan en línea. Las herramientas específicas de WhatsApp (acciones de contacto y pipeline) no están en esta superficie.
Modelo y razonamiento son los que configuraste para el agente en Configuración → Agentes; la misma configuración gobierna ambas APIs.
Un turno puede durar hasta 300 s cuando hay herramientas; lo típico son 3–5 s.

​La llamada

​Campos propios (metadata)

​Modos de respuesta

​Streaming

​Stream de eventos

​Clientes AI SDK

​Cuando una persona atiende la conversación

​Autenticación y claves

​Qué clave usar

​Cambiar a una clave nueva

​Errores

​Conviene saber

La llamada

Campos propios (metadata)

Modos de respuesta

Streaming

Stream de eventos

Clientes AI SDK

Cuando una persona atiende la conversación

Autenticación y claves

Qué clave usar

Cambiar a una clave nueva

Errores

Conviene saber