Ir al contenido
Consola

Arma tu propio widget de chat

Reemplaza el widget de chat de Espejo por una interfaz de soporte propia. Usa createChatClient sobre nuestro backend, trae tu propio modelo con espejo.agent o habla el protocolo HTTP directamente.

Nuestro widget de chat es una forma de poner el agente de soporte en tu sitio. Cuando no encaja con tu diseño, tu framework o tu producto, puedes armar el chat tú mismo y usar tanto de Espejo como quieras. Esta guía cubre tres niveles, del que menos trabajo pide al que más.

Qué haces túQué hace Espejo
1. Tu interfaz sobre nuestro backend (createChatClient, el recomendado)La interfaz: burbujas, campo de texto, confirmación, errores.El proveedor y su clave, el loop de tools, las acciones en la página, guías, tickets, el techo diario y la conversación.
2. Tu interfaz y tu propio modelo (window.espejo.agent)La interfaz, el modelo, su clave y el loop de tools, en tu servidor.El contexto de la página y las acciones en la página.
3. El protocolo HTTP directoLa interfaz, el lector del stream y el loop de acciones.El mismo backend que el nivel 1.

El nivel 1 es sobre lo que corre nuestro widget. Tienes el mismo comportamiento (reintentos, cola, confirmación, identidad) y solo dibujas la interfaz. Casi toda esta guía trata de él.

El nivel 2 no usa el backend de chat de Espejo: tu código lee la página con getContext(), le ofrece las tools a tu modelo con tools() y ejecuta lo que pide con act(), con una política y un handler de confirmación. Está documentado entero en Camino 1: tu propio chat y tu propio agente.

El nivel 3 es para cuando no puedes o no quieres cargar nuestro script para el chat. Igual necesitas espejo.agent en la página para ejecutar las acciones. Ver El protocolo HTTP.

Los niveles 1 y 3 necesitan el agente de soporte configurado y encendido en la consola (Agente de soporte), igual que el widget.

Carga espejo.chat.js sin data-key. Sin clave no monta nada: ni botón ni panel. Deja window.EspejoChat con createChatClient, installPresence, installChatWidget e identify, más chat, el widget montado, que queda en null sin clave:

<script src="https://app.espejo.dev/sdk/espejo.chat.js"></script>
<script>
const { createChatClient } = window.EspejoChat;
</script>

Cárgalo sin async ni defer si un script inline justo después usa window.EspejoChat, o espera al evento load. El bundle trae su propia copia de la capa espejo.agent, así que ejecuta las acciones solo. Funciona con o sin espejo.js: si el grabador está en la página, el agente manda además las acciones y los errores recientes del visitante.

EspejoChat.identify es del widget montado. Con tu propia interfaz, pon la identidad en tu cliente (ver Identidad y tickets).

Un chat completo en HTML y JavaScript sin dependencias: muestra la respuesta a medida que llega, muestra cada acción mientras corre, pregunta antes de actuar y muestra los errores.

<section id="support">
<ol id="log"></ol>
<form id="form">
<input id="input" autocomplete="off" placeholder="Pregunta lo que quieras" />
<button>Enviar</button>
</form>
</section>
<script src="https://app.espejo.dev/sdk/espejo.chat.js"></script>
<script>
const log = document.getElementById("log");
const rows = new Map();
let bubble = null;
// Siempre textContent: la respuesta es texto, nunca HTML.
function line(kind, text) {
const li = document.createElement("li");
li.className = kind;
li.textContent = text;
log.append(li);
li.scrollIntoView({ block: "end" });
return li;
}
function errorText({ code, retryAfter }) {
if (code === "rate_limited") return `Demasiados mensajes. Prueba de nuevo en ${retryAfter ?? 60} segundos.`;
if (code === "daily_cap") return "El asistente llegó al límite de hoy. Prueba mañana.";
if (code === "no_agent") return "El chat de soporte no está disponible en este sitio.";
if (code === "network") return "Se cortó la conexión. Envía tu mensaje de nuevo.";
return "Algo salió mal. Prueba de nuevo.";
}
const chat = window.EspejoChat.createChatClient({
key: "pk_live_...",
// Click, fill y navigate esperan esta respuesta. Usa tu propio diálogo.
onConfirm: ({ label }) => window.confirm(`¿Dejas que el asistente haga ${label}?`),
onEvent(event) {
switch (event.type) {
case "text":
bubble ??= line("assistant", "");
bubble.textContent += event.delta;
break;
case "tool_start":
bubble = null; // el texto después de una acción va en otra burbuja
rows.set(event.call.id, line("action", `${event.label}...`));
break;
case "tool": {
const row = rows.get(event.call.id) ?? line("action", "");
row.textContent = event.result.ok ? `${event.label}: listo` : `${event.label}: ${event.result.error}`;
break;
}
case "done":
bubble = null;
break;
case "error":
bubble = null;
line("error", errorText(event));
break;
}
},
});
document.getElementById("form").addEventListener("submit", (e) => {
e.preventDefault();
const input = document.getElementById("input");
const text = input.value.trim();
if (!text) return;
line("visitor", text);
input.value = "";
chat.send(text); // nunca rechaza
});
</script>

label es una descripción corta en inglés (click "Save", navigate to https://example.com/billing). Para escribir tu propio texto, en cualquier idioma, usa target, value y destination, que vienen en el pedido de confirmación y en los eventos tool_start y tool.

OpciónDefaultSignificado
keyningunoLa clave pública del proyecto (pk_...). Obligatoria.
baseUrlhttps://app.espejo.devURL base de la API.
onConfirmningunoSe llama antes de click, fill y navigate con { action, label, target?, value?, destination? }. Devuelve true (o una promesa de true) para ejecutar la acción. Sin esto, esas acciones vuelven como confirmation_required y no se ejecutan.
onEventningunoRecibe cada evento de la tabla de abajo. Una excepción adentro no corta el chat.
agentuno propioUn agente que ya armaste, por ejemplo window.espejo.agent. Su política queda como está. Un agente de createAgent ya permite las cinco acciones, así que cuáles se le ofrecen al modelo lo decide la consola. Si lo acotaste con policy({ allow }), solo se ejecutan esas. Pasado a installChatWidget, el menú Lo que el asistente puede hacer en esta página también muestra solo esas. Sin esto, el cliente arma uno que permite las cinco acciones.
allowlas cinco accionesRecorta las acciones del agente que arma el cliente. Se ignora con agent.
storagesessionStorageDónde se guarda el id de la conversación. null no guarda nada, así que cada carga de página arranca una conversación nueva.
identityninguno{ email, hash }, la identidad verificada del visitante.
conversationIdla guardadaArranca en esta conversación (un UUID) en vez de la guardada en storage, y la guarda ahí. Lo que no sea un UUID se ignora. Sirve para abrir una conversación desde un enlace o una lista propia.
langningunoEl idioma en que el agente escribe el saludo (es, pt-BR): de 2 a 10 letras, dígitos o guiones. Ver El saludo del agente.
MiembroQué hace
send(message)Manda un mensaje en el acto, corta el turno en curso y pone la cola en pausa. Resuelve cuando el cliente vuelve a quedar libre. Nunca rechaza.
enqueue(message)Manda en el acto si el cliente está libre y la cola no está en pausa. Si no, deja el mensaje en la cola. Devuelve false si el mensaje está en blanco o ya esperan 5.
removeQueued(id)Saca un mensaje de la cola.
editQueued(id, message)Reemplaza el texto de un mensaje de la cola. Un texto en blanco lo saca.
sendQueuedNow(id)Corta el turno en curso y manda primero ese mensaje de la cola. El resto de la cola sigue detrás.
clearQueue()Vacía la cola.
resumeQueue()Saca la cola de pausa. Si el cliente está libre, manda el primer mensaje.
reset()Corta el turno en curso, vacía la cola y arranca una conversación nueva.
abort()Corta el turno en curso, conserva la conversación y pone la cola en pausa.
identify(identity)Cambia la identidad, o la saca con null. Con otra persona hace un reset(). Si la conversación guardada espera la identidad (ver pending), la misma persona la recupera y otra persona, o null, la descarta.
destroy()Corta el turno en curso, vacía la cola y se suelta del agente.
getConfig()La configuración del widget en la consola. Ver más abajo.
listConversations()Promise<AgentConversationSummary[]>. Las últimas conversaciones del visitante. Ver Historial de conversaciones.
loadConversation(id)Promise<AgentConversationDetail>. Los mensajes visibles de una conversación, sin pasar a ella.
openConversation(id)Promise<AgentConversationDetail>. Pasa a esa conversación y resuelve con sus mensajes.
greet({ lang, title })Promise<ChatGreetResult>. Le pide al agente el saludo de una conversación vacía. Ver El saludo del agente.
conversationIdEl id de la conversación actual.
pendingtrue mientras la conversación guardada en storage espera la identidad: el cliente se creó sin identity y la conversación guardada es de una persona identificada. Mientras es true, conversationId es el id guardado y el cliente no pide esa conversación al servidor, así que loadConversation(chat.conversationId) fallaría. Pasa a false cuando identify la resuelve, o cuando mandas un mensaje antes, que arranca una conversación nueva sin identidad.
busytrue mientras corre un turno.
queueLos mensajes que esperan, en orden, como { id, text }[].
pausedtrue mientras la cola está en pausa. Siempre false con la cola vacía.

La cola solo avanza cuando un turno termina con done, y se pone en pausa después de un error, de abort() y de un send() directo. Vive en memoria: una recarga la pierde. Las reglas completas están en createChatClient: nuestro backend, tu interfaz.

typeCamposCuándo
textdeltaUn pedazo de la respuesta. Agrégalo a la burbuja actual.
tool_startcall, label, target?, value?, destination?Una acción está por correr, antes de la confirmación.
toolcall, label, target?, value?, destination?, resultLa misma acción después de correr o de ser rechazada. Se empareja con tool_start por call.id. result es { ok, error?, snapshot? }, donde snapshot es la página después de la acción.
doneconversationIdEl asistente terminó de contestar el mensaje.
errorcode, message, retryAfter?El turno se cortó. retryAfter (segundos) solo viene con rate_limited.
queuequeue, pausedLa cola cambió.
dequeuedid, messageUn mensaje de la cola está saliendo. Muéstralo en la conversación aquí.

call es { id, name, input }, donde name es highlight, scroll_to, click, fill o navigate. result.error es un código corto como declined, confirmation_required, stale_ref, not_allowed o cross_origin.

Cada turno que llega al final emite exactamente un done o un error. Un mensaje en blanco no se envía, y un turno cortado por abort(), reset(), destroy(), un send() posterior o sendQueuedNow() no emite nada más, ni siquiera el evento tool de una acción que esperaba confirmación.

  • Recorta el mensaje y lo corta en 4.000 caracteres, el límite de la API. Un mensaje en blanco no se envía.
  • Lee la página antes de cada pedido y recorta el contexto a los límites de la API.
  • Ejecuta las acciones. Cuando un turno termina con acciones pendientes, ejecuta cada una en la página (preguntando con onConfirm cuando hace falta) y manda los resultados, hasta que el asistente deja de pedir. Se detiene a las 25 rondas en un mismo mensaje con iteration_limit.
  • Reintenta una vez por su cuenta cuando la conversación venció (conversation_expired) o es de otra identidad (identity_changed): arranca una conversación nueva y vuelve a mandar el mensaje. Cuando la conversación está ocupada con otro pedido (conversation_busy, por ejemplo desde otra pestaña), espera 1,5 segundos y reintenta una vez en la misma conversación. Solo si el reintento también falla recibes el evento error.
  • Guarda el id de la conversación en sessionStorage, así una recarga en la misma pestaña sigue la misma conversación. Solo se guarda el id, nunca los mensajes: para volver a mostrarlos después de una recarga, llama a loadConversation(chat.conversationId) (ver Restaurar la conversación después de recargar). Si prefieres arrancar de cero, llama a reset() al cargar o pasa storage: null.
  • Adjunta la última grabación. Cuando espejo.js está en la página y el visitante hizo un reporte, el pedido lleva su session_id, así un ticket que abra el asistente puede enlazar el replay.
codeCausaQué mostrar
no_agentEl proyecto no tiene un agente encendido (404).Oculta tu chat, o di que no está disponible.
forbiddenClave inválida o revocada, origen no permitido o cuenta desactivada (401 o 403).Un error genérico. Revisa la clave y los orígenes permitidos.
bad_requestLa API rechazó el pedido (400, 413 o cualquier otro 4xx que no esté en esta tabla).Un error genérico.
rate_limitedMás de 30 pedidos por minuto desde una IP al proyecto (429).Pide esperar retryAfter segundos.
daily_capEl proyecto llegó a sus mensajes por día (429).Di que el asistente vuelve mañana (medianoche UTC).
conversation_limitLa conversación es demasiado larga (409).Ofrece una conversación nueva y llama a reset().
conversation_expiredEl reintento con una conversación nueva también falló (409).Ofrece una conversación nueva.
conversation_busyOtro pedido seguía contestando después del reintento (409).Pide probar de nuevo en un momento.
identity_changedEl reintento con una conversación nueva también falló (409).Ofrece una conversación nueva.
conflictCualquier otro 409.Llama a reset() y prueba de nuevo.
identity_requiredEl historial necesita una identidad verificada (401). listConversations() rechaza con este código sin llamar a la API cuando el cliente no tiene identidad.No muestres el historial, o pide al visitante que inicie sesión.
history_disabledEl proyecto no guarda historial de conversaciones (404).Oculta tu vista de historial.
conversation_not_foundLa conversación no existe, venció o es de otra persona (404).Sigue con una conversación nueva.
greeting_disabledgreet() en un proyecto cuyo saludo no es Saludo del agente (409).Muestra tu propio saludo.
greeting_not_allowedgreet() en una conversación que ya tiene mensajes (409), o con el cliente ocupado.Nada: la conversación ya empezó.
bad_responseUna respuesta del historial con un cuerpo que el cliente no puede leer.Un error genérico.
unavailableEl agente está mal configurado o el servicio está caído (5xx).Prueba más tarde.
networkEl pedido falló o el stream se cerró antes del final.Pide enviar el mensaje de nuevo.
provider_auth, provider_rate_limited, provider_error, timeout, iteration_limit, internalEl turno falló después de que empezó la respuesta. Ver Errores del stream.Un error genérico. iteration_limit: pide acotar el pedido.

message es un texto legible en inglés que viene de la API o del cliente. Nunca incluye la respuesta del proveedor.

Los códigos de un turno llegan en el evento error. Los métodos del historial no emiten eventos: rechazan con un ChatError, un Error con uno de estos code (identity_required, history_disabled, conversation_not_found, bad_response, bad_request para un id que no es un UUID, y los códigos HTTP y network de arriba). greet() nunca rechaza: resuelve con greeting_disabled o greeting_not_allowed sin evento error.

Sigue la configuración de la consola: getConfig()

Sección titulada «Sigue la configuración de la consola: getConfig()»

El dueño elige el nombre, el icono, el tema, el color de acento, el saludo, el historial y las secciones del asistente en los ajustes de Widget de la consola. getConfig() los lee (GET /v1/agent/config) para que tu interfaz también los respete:

const config = await chat.getConfig();
// { enabled, allowed_actions, theme, name, icon, accent_color, greeting_mode, greeting_text, history_enabled, sections }
  • enabled: si el asistente contesta. Con false, no muestres el chat.
  • allowed_actions: las acciones que permitió el dueño, entre highlight, scroll_to, click, fill y navigate.
  • theme: auto, light o dark. auto significa “adaptarse a la página”.
  • name: el nombre del asistente (hasta 40 caracteres), o null para tu nombre por defecto. Insértalo siempre como texto.
  • icon: chat, sparkles, headset, bot, help, la URL https:// de una imagen, o null para el de fábrica.
  • accent_color: el acento del dueño como color hexadecimal #rrggbb en minúsculas, o null para tu acento por defecto (el widget de Espejo usa #4c5fd5). Lo que no sea #rrggbb llega como null. Elige el color del texto encima según el contraste: puede ser claro u oscuro.
  • greeting_mode: default (tu propio saludo por defecto), custom (muestra greeting_text) o agent (pídeselo al agente con greet()).
  • greeting_text: el saludo del dueño, hasta 500 caracteres, solo con greeting_mode: "custom". Si no, null. Insértalo siempre como texto.
  • history_enabled: si el proyecto guarda el historial de los visitantes verificados. Es false cuando el proyecto no tiene secreto de identidad de visitantes. Con true y una identidad, listConversations() funciona.
  • sections: las secciones a mostrar, en el orden del dueño, entre home, support (el chat), tickets y guides. support solo aparece mientras enabled es true. tickets además necesita un visitante con identidad verificada: ocúltala si no la tienes.

Nunca rechaza. Cuando el proyecto no tiene nada que mostrar resuelve a { enabled: false, allowed_actions: [], theme: "auto", name: null, icon: null, accent_color: null, greeting_mode: "default", greeting_text: null, history_enabled: false, sections: [] }, y a null cuando no se pudo leer (red, origen no permitido, servidor caído). El navegador puede guardar la respuesta 60 segundos y la API 30, así que un cambio en la consola puede tardar hasta unos 90 segundos en llegar a tu interfaz.

Muéstrale al visitante lo que hace el asistente

Sección titulada «Muéstrale al visitante lo que hace el asistente»

Nuestro widget muestra un aviso con un botón Detener, un borde de color y un cursor mientras el asistente actúa. Lo mismo lo tienes con installPresence. Necesita el agente que ejecuta las acciones, así que carga también espejo.agent.js y dale ese agente al cliente:

<script src="https://app.espejo.dev/sdk/espejo.agent.js"></script>
<script src="https://app.espejo.dev/sdk/espejo.chat.js"></script>
<script>
const agent = window.espejo.agent;
// Permite las cinco acciones por defecto. Cuáles se le ofrecen al modelo lo decide la consola.
const chat = window.EspejoChat.createChatClient({
key: "pk_live_...",
agent,
onConfirm: ({ label }) => window.confirm(`¿Dejas que el asistente haga ${label}?`),
onEvent(event) {
if (event.type === "done" || event.type === "error") presence?.end();
// ...el resto se pinta como en el chat mínimo
},
});
const presence = window.EspejoChat.installPresence(agent, {
lang: "es",
name: "Ana",
onStop: () => chat.abort(),
});
function sendMessage(text) {
presence?.start();
chat.send(text);
}
</script>

Llama a start() al principio de cada turno: después de Detener, cada acción resuelve como declined hasta que lo hagas. Con glow: false no se pinta el borde y con cursor: false no se pinta el cursor. El aviso con Detener se muestra siempre. Un <dialog> nativo abierto con showModal() queda por encima del aviso, el borde y el cursor de installPresence. Las opciones (lang, text, name, theme, onStop, idleMs, glow, cursor) están en Mostrar lo que hace el agente.

Con la identidad verificada del visitante, el asistente puede consultar y abrir los tickets de esa persona, y tu interfaz puede listarlos. Tu servidor calcula el hash como hex(HMAC-SHA256(secreto de identidad, email)), con el correo recortado y en minúsculas. Cómo obtener el secreto y firmar en tu servidor, con Node, Python y PHP, está en Identidad verificada para tickets. El secreto nunca va al navegador.

Si ya sabes quién es el visitante cuando carga la página, pasa la identidad en identity al crear el cliente. Así una recarga conserva la conversación guardada de esa persona:

const chat = window.EspejoChat.createChatClient({
key: "pk_live_...",
identity: { email: "[email protected]", hash }, // el hash viene de tu backend
});

Usa identify() para iniciar y cerrar sesión durante la visita. No es lo mismo que pasar identity al crear el cliente: una llamada que cambia la identidad arranca una conversación nueva, así que llamarla justo después de crear el cliente descarta la conversación guardada de esa persona. La excepción es un cliente creado sin identity cuya conversación guardada la está esperando (ver pending): ahí, identify con la misma persona continúa esa conversación.

// Después de iniciar sesión: el hash viene de tu backend.
chat.identify({ email: "[email protected]", hash });
// Después de cerrar sesión.
chat.identify(null);
  • Sin identidad, o con una que no verifica, el chat anda igual, sin tickets. Un correo o un hash con algo que no sea ASCII cuenta como sin identidad.
  • Cambiar a otra persona, o a null, arranca una conversación nueva. El mismo correo y el mismo hash otra vez no cambian nada.
  • Con la conversación guardada esperando la identidad (pending es true), identify con la misma persona la recupera, y identify con otra persona o con null la descarta y arranca una nueva. Limpia lo que muestra tu interfaz en ese caso.
  • La identidad vive solo en memoria. Vuelve a ponerla en cada carga de página.
  • Cada pedido la lleva en los headers x-espejo-user-email y x-espejo-user-hash.

Espejo guarda cada conversación de su lado, así tu interfaz puede volver a mostrarla. Hay dos usos:

  • La conversación en curso después de una recarga, para cualquier visitante, también los anónimos.
  • Las últimas conversaciones del visitante, cuando el dueño prende el historial de conversaciones en la subpestaña Conversación de Widget y el visitante tiene una identidad verificada.

Cuánto se guarda cada conversación está en Retención. La parte de la consola está en Saludo e historial de conversaciones.

Restaurar la conversación después de recargar

Sección titulada «Restaurar la conversación después de recargar»

El cliente guarda el id de la conversación en sessionStorage. Después de una recarga, lee esa conversación y dibuja sus mensajes antes de que el visitante escriba:

Si el cliente se creó sin identity, la conversación guardada puede ser de una persona identificada y esperar a identify (chat.pending es true). No la cargues todavía: el pedido saldría sin identidad y fallaría. Cárgala cuando identify la recupere.

async function restore() {
if (chat.pending) return false; // espera la identidad: todavía no hay nada que cargar
try {
const { messages } = await chat.loadConversation(chat.conversationId);
for (const m of messages) line(m.role === "user" ? "visitor" : "assistant", m.text);
return messages.length > 0;
} catch (err) {
// conversation_not_found: la conversación es nueva o venció. Arranca vacía.
return false;
}
}

Cuando llega la identidad, por ejemplo en una aplicación de una sola página que pide la firma después de cargar, llama a identify y comprueba si la conversación sigue siendo la guardada:

const saved = chat.conversationId;
chat.identify({ email: "[email protected]", hash });
if (chat.conversationId === saved) restore(); // la misma persona: carga y vuelve a dibujar
else clearMessages(); // otra persona o null: una conversación nueva y vacía

Una conversación que nunca recibió un mensaje todavía no existe en Espejo, así que contesta conversation_not_found. Para evitar ese pedido, recuerda de tu lado si la conversación tuvo mensajes, como hace nuestro widget.

loadConversation(id) resuelve con un AgentConversationDetail:

{
id: string;
created_at: string; // ISO 8601
updated_at: string; // ISO 8601, la última actividad
messages: { role: "user" | "assistant"; text: string }[];
}

messages trae, en orden, lo que escribió el visitante y el texto que contestó el asistente, incluido el saludo del agente. Deja afuera las acciones, sus resultados y las respuestas que solo pidieron acciones. Inserta text como texto, nunca como HTML, como cualquier respuesta.

Quién puede leer una conversación:

  • Una conversación anónima la puede leer cualquiera que tenga su id, la clave pública y un origen permitido, mientras vive (24 horas después de su última actividad).
  • Una conversación con identidad verificada solo se puede leer con esa misma identidad. Sin una válida el cliente rechaza con identity_required, y con otra, con conversation_not_found.

Con history_enabled: true en getConfig() y una identidad en el cliente, listConversations() devuelve las últimas conversaciones del visitante, de la más reciente a la más vieja:

const config = await chat.getConfig();
if (config?.history_enabled) {
try {
const conversations = await chat.listConversations();
// [{ id, title, created_at, updated_at }]
for (const c of conversations) addRow(c.title, c.updated_at, () => openPast(c.id));
} catch (err) {
// identity_required, history_disabled, network...: oculta la lista.
}
}
async function openPast(id) {
clearLog();
try {
const { messages } = await chat.openConversation(id);
for (const m of messages) line(m.role === "user" ? "visitor" : "assistant", m.text);
} catch (err) {
chat.reset(); // no se pudo leer: sigue con una conversación nueva
}
}
  • Cada elemento es un AgentConversationSummary: id, title (el primer mensaje que escribió el visitante, en una línea, hasta 80 caracteres y con … al final cuando se cortó), created_at y updated_at (la última actividad).
  • Como mucho 3 conversaciones por visitante. Una cuarta borra la más vieja. Una conversación en la que el visitante nunca escribió (solo el saludo del agente) no aparece.
  • Sin identidad, listConversations() rechaza con identity_required sin llamar a la API. Con el historial apagado, con history_disabled.
  • openConversation(id) corta el turno en curso, vacía la cola, hace de esa conversación la actual (y guarda su id) y resuelve con sus mensajes. Tu próximo send() la continúa. Si no se pueden leer los mensajes, rechaza, pero el cliente ya quedó en ese id: llama a reset() para arrancar una nueva.
  • loadConversation(id) solo lee: la conversación actual no cambia.
  • Un id que no es un UUID rechaza con bad_request sin llamar a la API.

Nuestro widget muestra la misma lista en Inicio. Sus dos textos para eso, historyTitle y errorHistory, se reemplazan con text en installChatWidget.

Cuando el dueño elige Saludo del agente en la consola, getConfig() devuelve greeting_mode: "agent", y tu interfaz pide el saludo con greet() cuando se abre una conversación nueva y vacía:

const config = await chat.getConfig();
const restored = await restore();
if (!restored) {
if (config?.greeting_mode === "agent") {
const result = await chat.greet({ lang: "es" }); // title es document.title por defecto
if (result !== "done") line("assistant", "¡Hola! ¿En qué te puedo ayudar?");
} else if (config?.greeting_mode === "custom" && config.greeting_text) {
line("assistant", config.greeting_text);
} else {
line("assistant", "¡Hola! ¿En qué te puedo ayudar?");
}
}
greet(options?: { lang?: string; title?: string }): Promise<"done" | "greeting_disabled" | "greeting_not_allowed" | "failed">
  • El saludo llega por onEvent como una respuesta: eventos text y un done final, sin un mensaje del visitante antes.
  • lang es el idioma en que se escribe (por defecto, el lang de las opciones). Un valor que no tenga de 2 a 10 letras, dígitos o guiones no se manda. title es el título de la página, por defecto document.title, cortado en 200 caracteres.
  • Solo funciona en una conversación vacía. Con mensajes resuelve greeting_not_allowed, y con otra opción de saludo en la consola, greeting_disabled, en los dos casos sin evento error. Con el cliente ocupado no manda nada y resuelve greeting_not_allowed.
  • Si la conversación actual es de otra identidad verificada (la API contesta 409 identity_changed), el cliente arranca una conversación nueva y pide el saludo ahí, una sola vez. chat.conversationId cambia.
  • failed significa que el turno se cortó: recibes su evento error, salvo que lo hayan cortado abort(), reset() o destroy().
  • Nunca rechaza. Los mensajes encolados con enqueue() mientras el agente saluda salen justo después, y la promesa resuelve cuando el cliente queda libre, como send().
  • Cada saludo es una llamada al proveedor del dueño: gasta tokens del agente y cuenta para el techo diario y el límite por minuto. El agente solo recibe la URL de la página, su ruta y su título. Pídelo una vez por conversación.

El cliente no trae un lector de guías ni de tickets. Tu interfaz llama a los mismos endpoints públicos que usa nuestro widget, desde el navegador, con la clave pública.

GET /v1/guides, GET /v1/guides/search?q= y GET /v1/guides/{id}, con el header x-espejo-key. Las formas de respuesta, la sintaxis de búsqueda, los errores y el cache están en Guías de ayuda: En el widget. Dos cosas a tener en cuenta cuando las muestras tú:

  • render en la lista dice cómo quiere el dueño que se abran las guías: native dentro de tu interfaz (muestra markdown), o link en la url propia de la guía, en una pestaña nueva.
  • markdown es contenido del dueño, pero muéstralo como no confiable: nuestro widget solo activa links e imágenes https:// y muestra cualquier HTML como texto.

GET /v1/tickets?status=all|open|resolved (sin status, all), con el header x-espejo-key y los dos headers de identidad. Aquí la clave va solo en el header, nunca en ?key=.

const res = await fetch("https://app.espejo.dev/v1/tickets?status=open", {
headers: {
"x-espejo-key": "pk_live_...",
"x-espejo-user-email": "[email protected]",
"x-espejo-user-hash": hash,
},
credentials: "omit",
});
const { tickets, waiting } = await res.json();

La forma de cada ticket, qué significan status y waiting, los límites y los errores están en Tickets en el widget y en el agente y Errores HTTP de GET /v1/tickets. Un 401 significa que el correo y el hash no verifican: oculta tu vista de tickets hasta tener otra identidad. Muestra la vista de Tickets solo cuando sections incluye tickets.

Este es el contrato que habla createChatClient. Úsalo cuando quieras escribir el cliente tú mismo. Igual necesitas window.espejo.agent en la página para leerla y ejecutar las acciones (carga espejo.agent.js).

Todos los endpoints públicos (/v1/agent/config, /v1/agent/chat, /v1/widget/conversations, /v1/guides, /v1/tickets) revisan lo mismo primero:

  • El header x-espejo-key con la clave pública. Sin él la respuesta es 403 Missing x-espejo-key header. Con una clave desconocida o revocada, es 403 Invalid ingest key.
  • La cuenta tiene que estar activa. Si no, 403 This account is deactivated. Recording is off.
  • El Origin tiene que estar permitido. Un proyecto sin orígenes permitidos acepta cualquiera. Con una lista, un pedido desde otro origen, o sin Origin, recibe 403 Origin <origin> is not allowed for this project., o Origin (none) is not allowed for this project. cuando falta el header. Los navegadores siempre mandan Origin en estos pedidos. Un servidor normalmente no, y por eso estos endpoints están pensados para llamarse desde el navegador del visitante.

Manda los pedidos sin cookies (credentials: "omit").

Headers: x-espejo-key. También puedes agregar la clave como ?key=, junto al header y nunca en su lugar: el cache del navegador se indexa por URL, así dos proyectos en el mismo sitio no comparten entrada. Si vienen las dos, tienen que coincidir. Si no, la respuesta es 403.

{
"enabled": true,
"allowed_actions": ["highlight", "scroll_to", "click"],
"theme": "auto",
"name": "Ana",
"icon": "sparkles",
"sticky_container_id": "main-content",
"accent_color": "#e8590c",
"greeting_mode": "custom",
"greeting_text": "¡Hola! Pregúntame lo que quieras sobre tu cuenta.",
"history_enabled": true,
"sections": ["home", "support", "guides"]
}

Si omitís sticky_container_id, el SDK busca <main> y raíces habituales como #__next o #root; una raíz genérica con un <main> interno usa ese contenido principal. Un ID explícito se respeta tal cual, incluso si es root. Al acoplar, el SDK reduce temporalmente el ancho de ese elemento y coloca el widget fijo como hermano, sin envolver ni mover nodos de la app; al soltarlo, restaura el ancho. Elegí un elemento cuyo ancho pueda reducirse; si no hay uno adecuado, el widget queda flotante. Mientras está acoplado, ese elemento se alinea al borde inicial de la página en vez de seguir centrado, así su contenido nunca queda detrás del panel. Si se abre un diálogo modal o un sheet de la página, el widget se reduce a una tira angosta contra el borde derecho y, al cerrarse, vuelve a la misma posición y modo. Ver Modales y sheets de la página. Minimizarlo manualmente también conserva el acoplamiento.

Los campos son los que se describen en getConfig(). Responde 404 cuando el proyecto no tiene nada que mostrar (ni agente encendido, ni tickets, ni guías). Un 200 lleva Cache-Control: private, max-age=60, y cualquier otra respuesta lleva no-store. Como mucho 120 pedidos por minuto desde una IP a un proyecto.

Headers:

HeaderValor
content-typeapplication/json
x-espejo-keyLa clave pública.
accepttext/event-stream
x-espejo-user-email, x-espejo-user-hashOpcionales. La identidad verificada.

Cuerpo:

{
"conversation_id": "0f8b1c1e-5a0e-4c52-9d0b-7f1e8f3a2b64",
"message": "¿Dónde cambio mi plan?",
"context": {
"page": "espejo-snapshot/1 ...",
"url": "https://example.com/settings",
"recent": ["click button \"Billing\""],
"errors": []
},
"session_id": "3f2a9c0d4b6e8f1a2c3d4e5f6a7b8c9d"
}
CampoReglas
conversation_idUn UUID que genera tu cliente (crypto.randomUUID()) y reusa en toda la conversación. Obligatorio.
messageLo que escribió el visitante. No vacío, hasta 4.000 caracteres.
tool_resultsLos resultados de las acciones pendientes. Ver El loop de acciones.
contextLo que ve el visitante ahora: page (el snapshot), url, recent y errors, de agent.getContext(). Mándalo en cada pedido, también con resultados.
session_idOpcional. El session_id del último reporte que hizo espejo.js en esta página (window.espejo.lastReportId, 32 caracteres hex). Cualquier otra cosa se ignora.
greettrue para pedir el saludo del agente en lugar de un mensaje. Solo en una conversación vacía y con Saludo del agente en la consola. Cualquier otro valor es un 400.
langOpcional, solo con greet. El idioma del saludo: de 2 a 10 letras, dígitos o guiones (es, pt-BR). Cualquier otra cosa es un 400.
titleOpcional, solo con greet. El título de la página, un string. Se corta en 200 caracteres.

Manda exactamente uno de message, tool_results o greet. Más de uno, o ninguno, es un 400. Con greet solo se usa context.url: page, recent y errors se descartan. Un pedido de saludo contesta 409 greeting_disabled cuando el saludo de la consola no es Saludo del agente, y 409 greeting_not_allowed cuando la conversación ya tiene mensajes. Cuenta para el techo diario como un mensaje. El contexto se corta a los límites de AGENT_CHAT_LIMITS, y el cuerpo entero no puede pasar de 769.528 bytes (413).

Los errores que se pueden decidir antes de contestar (clave, origen, agente apagado, límites de frecuencia, cuerpo inválido, estado de la conversación) llegan como un status HTTP normal con un cuerpo JSON. Si no, la respuesta es 200 con content-type: text/event-stream, y cada evento es:

event: <name>
data: <json>
EventodataSignificado
text{ "delta": "..." }Un pedazo de la respuesta. Puede haber muchos.
tool_call{ "id": "...", "name": "click", "input": { "ref": "e12" } }Una acción para la página. Puede haber varias en un turno.
done{ "conversation_id": "...", "awaiting_tools": true }El turno terminó. Con awaiting_tools: true, el servidor espera los resultados.
error{ "code": "timeout", "message": "..." }El turno falló. Los códigos están en Errores del stream.

El stream termina con exactamente un done o un error. Un stream que se cierra sin ninguno de los dos es una conexión caída: manda el mensaje de nuevo.

Las cinco acciones de la página (highlight, scroll_to, click, fill, navigate) corren en el navegador. Solo llegan las que el dueño permitió en la consola. Todo lo demás (volver a leer la página, buscar en las guías, consultar y abrir tickets) se resuelve en el servidor de Espejo y nunca llega como tool_call.

Cuando un turno termina con awaiting_tools: true:

  1. Ejecuta cada tool_call de ese turno, en orden, con el mismo agente que armó el context: agent.act({ ...call.input, type: call.name }). Los ref apuntan al snapshot de ese agente.
  2. Manda otro POST en la misma conversación con tool_results en lugar de message, y un context fresco. Un resultado por cada acción pendiente, con su id exacto: { "id": "...", "ok": true }, más error (hasta 1.000 caracteres) y snapshot (hasta 24.000) cuando act() los devolvió. Como mucho 8 resultados por pedido.
  3. Lee el stream nuevo. Repite mientras termine con awaiting_tools: true.

Un resultado que falta, un id repetido o un id que no se pidió es un 400. Resultados cuando no hay nada pendiente son un 409. Si en cambio el visitante escribe un message nuevo, las acciones pendientes se cierran como no ejecutadas y la conversación sigue desde el mensaje nuevo.

window.espejo.agent permite las cinco acciones por defecto, y pregunta antes de click, fill y navigate. Para igualarlo a lo que permitió el dueño, llama a agent.policy({ allow: config.allowed_actions }). Contesta la confirmación con agent.on("action_confirm", handler). Sin handler, esas acciones devuelven confirmation_required: mándalo como resultado. Ver La política.

No mandes el historial: Espejo lo guarda por conversation_id. Una conversación vence 24 horas después de su último pedido, o después de los días que eligió el dueño cuando la conversación tiene identidad verificada y el historial está prendido (ver Retención). Un message nuevo en una conversación vencida la arranca de cero, vacía, con el mismo id. tool_results en una vencida recibe 409 conversation_expired. Después de 60 pedidos (contando los de resultados) o 256 KB guardados, la conversación contesta 409 conversation_limit: arranca una nueva con un UUID nuevo. Un solo pedido a la vez por conversación: un segundo recibe 409 conversation_busy.

El primer pedido con una identidad válida la ata a la conversación. Los pedidos siguientes con otra identidad, o sin ninguna, reciben 409 identity_changed.

Las últimas conversaciones del visitante. Headers: x-espejo-key y los dos headers de identidad (x-espejo-user-email, x-espejo-user-hash), sin cookies.

{
"conversations": [
{
"id": "0f8b1c1e-5a0e-4c52-9d0b-7f1e8f3a2b64",
"title": "¿Dónde cambio mi plan?",
"created_at": "2026-10-01T14:02:11.000Z",
"updated_at": "2026-10-01T14:05:40.000Z"
}
]
}
  • Como mucho 3, por updated_at, de la más reciente a la más vieja. Solo conversaciones de ese visitante verificado que no vencieron y en las que el visitante escribió algo.
  • title es el primer mensaje que escribió el visitante, en una línea, hasta 80 caracteres.
  • 401 identity_required sin una identidad verificada, y 404 history_disabled cuando el proyecto tiene el historial apagado.

Una conversación con sus mensajes visibles. Los mismos headers: los de identidad solo hacen falta para una conversación que tiene identidad. Funciona también con el historial apagado, para la conversación en curso después de una recarga.

{
"id": "0f8b1c1e-5a0e-4c52-9d0b-7f1e8f3a2b64",
"created_at": "2026-10-01T14:02:11.000Z",
"updated_at": "2026-10-01T14:05:40.000Z",
"messages": [
{ "role": "assistant", "text": "¡Hola! Veo que estás en Facturación. ¿Te ayudo?" },
{ "role": "user", "text": "¿Dónde cambio mi plan?" },
{ "role": "assistant", "text": "En Facturación, en Plan. Te lo señalo." }
]
}
  • {id} tiene que ser un UUID. Si no, la respuesta es 400.
  • 404 conversation_not_found cuando no existe, venció, es de otro proyecto o tiene otra identidad verificada. Una conversación con identidad leída sin una válida recibe 401 identity_required.
  • messages solo tiene texto: ni acciones, ni resultados, ni el pedido que hay detrás del saludo del agente.

Las dos respuestas, errores incluidos, llevan Cache-Control: no-store. Entre las dos permiten 60 pedidos por minuto desde una IP a un proyecto, y necesitan el agente encendido (si no, 404). La tabla completa de errores está en Errores HTTP de GET /v1/widget/conversations.

EventSource solo hace GET, así que lee la respuesta del POST con fetch y un lector del stream:

const API = "https://app.espejo.dev";
const KEY = "pk_live_...";
const agent = window.espejo.agent; // de espejo.agent.js
let conversationId = crypto.randomUUID();
function context() {
const c = agent.getContext();
return {
page: c.page.slice(0, 24000),
url: c.url.slice(0, 2048),
recent: c.recent.slice(-30).map((l) => l.slice(0, 500)),
errors: c.errors.slice(-20).map((l) => l.slice(0, 500)),
};
}
async function post(body, onText) {
const res = await fetch(`${API}/v1/agent/chat`, {
method: "POST",
headers: { "content-type": "application/json", "x-espejo-key": KEY, accept: "text/event-stream" },
credentials: "omit",
body: JSON.stringify(body),
});
if (!res.ok) {
const err = await res.json().catch(() => ({}));
throw Object.assign(new Error(err.message ?? `HTTP ${res.status}`), { status: res.status, code: err.code });
}
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
const calls = [];
let end = null;
let buffer = "";
for (;;) {
const { done, value } = await reader.read();
if (done) break;
buffer += value;
let cut;
while ((cut = buffer.indexOf("\n\n")) >= 0) {
const block = buffer.slice(0, cut);
buffer = buffer.slice(cut + 2);
let name = "message";
const data = [];
for (const line of block.split("\n")) {
if (line.startsWith("event:")) name = line.slice(6).trim();
else if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
}
if (!data.length) continue;
const payload = JSON.parse(data.join("\n"));
if (name === "text") onText(payload.delta);
else if (name === "tool_call") calls.push(payload);
else if (name === "done") end = payload;
else if (name === "error") throw Object.assign(new Error(payload.message), { code: payload.code });
}
}
if (!end) throw new Error("The connection closed before the answer finished.");
return { calls, awaiting: end.awaiting_tools };
}
async function ask(message, onText) {
let body = { conversation_id: conversationId, message, context: context() };
for (let round = 0; round < 25; round++) {
const { calls, awaiting } = await post(body, onText);
if (!awaiting || !calls.length) return;
const tool_results = [];
for (const call of calls) {
const r = await agent.act({ ...call.input, type: call.name });
tool_results.push({
id: call.id,
ok: r.ok,
...(r.error ? { error: r.error.slice(0, 1000) } : {}),
...(r.snapshot ? { snapshot: r.snapshot.slice(0, 24000) } : {}),
});
}
body = { conversation_id: conversationId, tool_results, context: context() };
}
}

Un cliente de verdad además maneja los códigos 409 (un conversationId nuevo para conversation_expired, conversation_limit e identity_changed, una espera corta para conversation_busy) y retry_after en un 429. Es lo que ya hace createChatClient.

Las tablas completas están en Errores y límites. Lo que más importa al escribir el cliente:

  • Los errores HTTP llegan antes del stream, como JSON con message y, en algunos, code: 409 con conversation_expired, conversation_limit, conversation_busy, identity_changed, greeting_disabled o greeting_not_allowed, y 429 con daily_cap. Un 429 sin code es el límite de frecuencia y trae retry_after en segundos.
  • Límites de frecuencia: 30 pedidos de chat por minuto desde una IP a un proyecto (los pedidos con tool_results y con greet también cuentan), 120 por minuto para GET /v1/agent/config, y 60 por minuto entre los dos endpoints del historial.
  • Techo diario: solo los pedidos con message o greet cuentan para los mensajes por día del proyecto.
  • Un stream por pedido: no hay forma de retomar un stream que se cortó. Manda el turno de nuevo.
  • Retomar un stream. Un stream que se corta no se puede seguir desde donde quedó. Manda el mensaje de nuevo.
  • Tickets fuera del asistente. No hay un endpoint para que el visitante abra o conteste un ticket desde tu interfaz. El visitante puede pedirle al asistente que abra uno, si el dueño lo permitió.
  • Llamar al chat desde un servidor. Cuando el proyecto restringe sus orígenes permitidos, un pedido sin un Origin permitido se rechaza. El chat está pensado para correr en el navegador del visitante.
  • Renderizado del lado del servidor. El cliente y el agente necesitan un navegador: leen la página y actúan sobre ella. Crea el cliente del lado del cliente, después de que carga la página.