Chat integrado
El chat integrado pone AptiveAI Agents en un panel dentro de tu aplicación. La persona elige uno de sus agentes, inicia una tarea, la sigue, responde sus preguntas y aprueba sus pasos, y encuentra sus tareas anteriores, agrupadas por agente, todo sin salir de tu aplicación. Una tarea iniciada en el panel es una tarea normal: también aparece en AptiveAI Agents, a nombre de la misma persona.
Tu aplicación hace tres cosas:
- Inicia la sesión de la persona. Tu servidor responde por la persona que tiene la sesión iniciada en tu aplicación con un token firmado de corta duración. La persona nunca ve una pantalla de inicio de sesión de AptiveAI.
- Le dice al agente qué hay en pantalla (opcional): la página, el registro que la persona tiene abierto, para que “¿qué estoy viendo?” tenga respuesta.
- Ofrece acciones de pantalla (opcional), como abrir un registro, que el agente puede pedirle a tu página mientras responde.
El panel es una página de AptiveAI Agents mostrada en un <iframe> de tu
página. No tiene vista en vivo de la computadora del agente: un paso que la
necesita ofrece Abrir en AptiveAI, que abre el producto completo en una
pestaña nueva.
Inicio rápido
Sección titulada «Inicio rápido»Agrega el script de AptiveAI a tu página y monta el panel en un elemento tuyo:
<div id="assistant" style="height: 100%"></div>
<script src="https://console.aptiveai.io/embed/v1.js"></script><script> const panel = AptiveAI.mount('#assistant', { enterpriseId: 'YOUR-ENTERPRISE-ID', // Your own server signs a token for the person signed in to your application. getToken: async () => { const res = await fetch('/aptiveai/token', { method: 'POST', credentials: 'same-origin' }); if (!res.ok) throw new Error('Could not get an AptiveAI token'); return res.text(); }, context: { page: { title: 'Customers', url: location.href }, }, actions: [ { name: 'open_customer', description: "Open a customer's record on the person's screen.", parameters: { type: 'object', properties: { customerId: { type: 'string' } }, required: ['customerId'], }, run: async ({ customerId }) => { await router.navigate(`/customers/${encodeURIComponent(customerId)}`); return 'Opened'; }, }, ], onEvent: (event) => console.log('AptiveAI', event.type, event), });</script>AptiveAI.mount(el, options) crea el frame del panel dentro de el (un
elemento, o un selector que lo indique) y devuelve un objeto de control.
Ajustes → Chat integrado muestra la etiqueta del script de tu cuenta, lista
para copiar.
| Opción | Qué es |
|---|---|
enterpriseId | El id de tu empresa, de Ajustes → Chat integrado |
getToken | Una función que devuelve un token (un string), o una promesa de uno, obtenido de tu propio servidor (El inicio de sesión, paso a paso). Se llama cuando el panel está listo y otra vez cada vez que la sesión vence |
context | Opcional. Lo que la persona tiene abierto (Contexto de la página) |
actions | Opcional. Acciones de pantalla que el agente puede pedirle a tu página: cada una { name, description, label, parameters, run(args) }. label y parameters (un JSON schema) son opcionales; run devuelve un resultado o lanza un error (Acciones de pantalla) |
onEvent | Opcional. Recibe { type, … } para ready, signed-in, unavailable, session-expired, task y error (Solución de problemas) |
origin | Opcional. La dirección de AptiveAI Agents, como https://console.aptiveai.io. Por defecto se toma de la dirección del propio script, así que solo la necesitas si cargas el script de otra forma |
locale | Opcional. 'en' o 'es': abre el panel en inglés o en español, y se mantiene en ese idioma mientras la persona se mueve por él. Cualquier otro valor hace que mount lance un error. Sin esta opción, el panel usa el idioma elegido por última vez dentro de él; si no, el del navegador; si no, inglés. Se lee al abrir el panel; para cambiarlo, llama a unmount() y vuelve a montarlo |
theme | Opcional. 'light' o 'dark': el modo de tu página, para que el panel coincida con él (Tema). Cualquier otro valor hace que mount lance un error. Sin esta opción, el panel sigue la configuración del sistema de quien lo visita |
taskId | Opcional. El id de una tarea (un UUID): el panel se abre en esa tarea en lugar de en una nueva. Cualquier valor que no sea un UUID hace que mount lance un error. Una tarea que no existe, o que no es de la persona, aparece como no disponible |
agentId | Opcional. El único agente con el que habla el panel (su id, un UUID); la persona no puede elegir — consulta Qué agente responde. Si también pasas taskId, se abre la tarea y este es el agente con el que empieza Nueva tarea. Cualquier valor que no sea un UUID hace que mount lance un error |
defaultAgentId | Opcional. El agente en el que se abre el panel (su id, un UUID); la persona puede cambiarlo — consulta Qué agente responde. No junto con agentId. Cualquier valor que no sea un UUID hace que mount lance un error |
| Objeto de control | Qué hace |
|---|---|
setContext(context) | Reemplaza el contexto de la página; llámalo cada vez que la persona abra otra página o registro |
setActions(actions) | Reemplaza la lista de acciones de pantalla; una lista vacía las retira |
setTheme(mode) | Cambia el panel a 'light' o 'dark' cuando tu página cambia, en vivo y sin recargar: una tarea abierta sigue abierta. Cualquier otro valor lanza un error |
unmount() | Quita el panel |
iframe | El elemento <iframe> del panel, para darle tamaño o estilo |
Eventos que recibe onEvent:
type | Campos | Significado |
|---|---|---|
ready | — | El panel se cargó y pide un token |
signed-in | — | La persona inició sesión |
unavailable | reason | El panel no puede iniciar la sesión de la persona y muestra una frase que explica por qué (Solución de problemas). El script no pide más tokens hasta que el panel vuelva a cargarse |
session-expired | — | La sesión del panel terminó; el script ya le está pidiendo un token nuevo a getToken: de inmediato tras una sesión que duró, o tras una pausa creciente (1 segundo, luego 2) cuando una terminó antes de 30 segundos de iniciarse |
task | id, status | Una tarea empezó o se abrió, o cambió de estado (los estados) |
error | code | Se rechazó un mensaje; o token_failed: getToken falló tres veces seguidas; o session_not_kept: tres inicios de sesión seguidos terminaron antes de 30 segundos, así que este navegador no conserva la sesión del panel. Tras cualquiera de los dos últimos, el script deja de pedir tokens hasta que el panel vuelva a cargarse (Solución de problemas) |
mount lanza un Error de inmediato cuando falta el elemento, falta
enterpriseId, getToken no es una función, locale no es 'en' ni 'es',
theme no es 'light' ni 'dark', taskId, agentId o defaultAgentId no
es un UUID, o se pasan a la vez agentId y defaultAgentId; mount y
setActions también lanzan un error ante una acción con un nombre no válido,
un nombre repetido, sin descripción o sin run. El tamaño lo decides tú: el
panel llena el elemento. Una columna fija de unos
400 píxeles de ancho funciona bien; el panel también funciona en el ancho de un
teléfono.
Qué agente responde
Sección titulada «Qué agente responde»Sin agentId, el panel funciona como AptiveAI Agents: la persona elige uno de
los agentes que puede usar, o escribe sin ninguno. Con agentId, el panel se
abre en ese agente, Nueva tarea dentro del panel lo conserva y no se ofrece
ninguna lista de agentes, así que nadie inicia una tarea sin él. Si la persona
no puede usar ese agente — no está compartido con ella, se eliminó o no es un
agente normal —, el panel dice que no está disponible y tu página recibe
unavailable con el motivo no_agents.
Con defaultAgentId, el panel se abre en ese agente pero no obliga a la
persona a usarlo: el agente aparece como una etiqueta sobre el cuadro de
mensaje, su ✕ lo quita y muestra los demás agentes de la persona, y Nueva
tarea vuelve a abrirse en el agente por defecto. Un agente por defecto que la
persona no puede usar se ignora, y el panel muestra sus agentes como lo haría
sin la opción.
| Pasas | El panel se abre en | La persona puede cambiar de agente |
|---|---|---|
agentId | Ese agente | No |
defaultAgentId | Ese agente | Sí, entre los agentes compartidos con ella |
| Ninguno | La lista de sus agentes | Sí |
Cuando tu aplicación tiene un solo asistente, pasa el id de su agente como
agentId: así todos hablan con el mismo agente y nadie tiene que elegir.
Cuando tiene un asistente habitual y otros para trabajos concretos, pasa el
habitual como defaultAgentId. Para usar otro agente, llama a unmount() y
vuelve a montarlo con su id.
Volver a donde estaba la persona
Sección titulada «Volver a donde estaba la persona»El panel te avisa de cada tarea con un evento task, { type: 'task', id, status }, cuando una tarea empieza, cuando se abre una tarea existente y cada
vez que cambia su estado. Guarda el último id — en tu propia sesión o
almacenamiento, por persona — y pásalo como taskId en el siguiente mount:
el panel se abre en esa tarea en lugar de en una nueva. Desde ahí la persona
puede iniciar una tarea nueva igualmente.
status | Significa |
|---|---|
running | El agente está trabajando |
awaiting_input | El agente espera a la persona: una pregunta o una aprobación |
idle | Abierta para otro mensaje |
completed, partial, failed, skipped, expired, stopped | La tarea terminó |
Elegir el nombre global
Sección titulada «Elegir el nombre global»El script pone su API en window.AptiveAI. Si tu página ya usa ese nombre, o
prefieres otro, agrega data-global a la etiqueta del script:
<script src="https://console.aptiveai.io/embed/v1.js" data-global="NorthwindAssistant"></script><script> const panel = NorthwindAssistant.mount('#assistant', { /* the same options */ });</script>El nombre debe ser un identificador simple de JavaScript (letras, dígitos, _
y $, sin empezar por un dígito) que tu página no use ya. Si no lo es, el
script usa window.AptiveAI en su lugar y la consola del navegador muestra una
advertencia que explica por qué. El script nunca sobrescribe una variable
global que no sea suya: si AptiveAI también está ocupada, no instala nada y
registra un error con los nombres que no pudo usar. Si el script se carga dos
veces, se conserva la primera copia.
Cómo se comunican tu página y el panel
Sección titulada «Cómo se comunican tu página y el panel»El panel es un <iframe> que AptiveAI sirve desde su propio origen,
https://console.aptiveai.io. En el navegador, tu página y el panel son dos
sitios distintos, así que ninguno puede meterse en el otro: se comunican solo
con window.postMessage, en la versión 1 de un pequeño protocolo donde cada
mensaje es un objeto { type, v: 1, … }. El script — AptiveAI.mount — lo
habla por ti; esta sección cuenta lo que hace en tu nombre. El protocolo
completo está en Avanzado: el protocolo de
mensajes.
Quién envía qué, y cuándo
Sección titulada «Quién envía qué, y cuándo»- Tu página crea el frame (lo hace el script, en
mount). AptiveAI deja que el navegador lo muestre solo en tus orígenes permitidos. - El frame se carga y envía
aptiveai:ready. - Tu página le pide un token a TU servidor (
getToken). Tu servidor firma uno para la persona que tiene la sesión iniciada en tu aplicación, válido como máximo 60 segundos y de un solo uso. - Tu página envía
aptiveai:sessioncon ese token al frame. - AptiveAI verifica el token y abre una sesión para esa persona, solo dentro del frame.
- El frame envía
aptiveai:signed-in— oaptiveai:unavailablecon un motivo, cuando no puede iniciar la sesión de la persona. - A partir de ahí, tu página envía
aptiveai:context,aptiveai:actionsyaptiveai:themecada vez que cambian. El frame envíaaptiveai:taskcuando las tareas empiezan y cambian,aptiveai:actioncuando el agente pide una de tus acciones de pantalla — a la que tu página responde conaptiveai:action-result, con el mismoid—,aptiveai:session-expiredcuando la sesión termina (vuelta al paso 3) yaptiveai:errorcuando rechaza uno de tus mensajes.
| Tu página → el panel | El panel → tu página |
|---|---|
aptiveai:session — un token nuevo | aptiveai:ready — escuchando; envía un token |
aptiveai:context — lo que la persona tiene abierto | aptiveai:signed-in — la persona inició sesión |
aptiveai:actions — las acciones de pantalla que ofreces | aptiveai:task — una tarea empezó, se abrió o cambió de estado |
aptiveai:theme — el modo claro u oscuro de tu página | aptiveai:action — el agente pide una acción de pantalla |
aptiveai:action-result — tu respuesta a aptiveai:action | aptiveai:session-expired — envía un token nuevo |
aptiveai:unavailable — no puede iniciar la sesión de esta persona, y por qué | |
aptiveai:error — se rechazó uno de tus mensajes |
Lo que nunca cruza el límite
Sección titulada «Lo que nunca cruza el límite»- El secreto de firma se queda en tu servidor. Por tu página solo pasa un token firmado, válido 60 segundos y una sola vez.
- Tu página no puede leer el panel: ni la conversación, ni las tareas, ni su cookie de sesión. Solo recibe los mensajes de la tabla anterior.
- El panel no puede leer tu página: ni su DOM, ni sus cookies, ni su almacenamiento. El agente sabe solo lo que envías como contexto y lo que responden tus acciones de pantalla.
Comprobación del origen, en los dos lados
Sección titulada «Comprobación del origen, en los dos lados»- El frame se carga solo en tus orígenes permitidos (Ajustes → Chat integrado); el navegador se niega a mostrarlo en cualquier otro lugar.
- El panel envía mensajes solo al origen de tu página y lee un mensaje solo cuando viene de la página que lo incrustó, en uno de tus orígenes permitidos.
- Tu página envía mensajes al frame con su origen exacto como destino — nunca
*— y acepta un mensaje solo cuandoevent.origines el origen de la consola yevent.sourcees elcontentWindowdel frame.
El script hace todo esto por ti: crea el frame, responde a cada
aptiveai:ready y aptiveai:session-expired con un token de getToken,
envía tu contexto, tus acciones y tu tema, ejecuta el run de tus acciones y
aplica las comprobaciones de origen. Nunca pone un token en una URL, en el
almacenamiento ni en un registro.
Antes de que el panel pueda iniciar la sesión de alguien, actívalo en AptiveAI Agents y agrega a tu servidor un endpoint de tokens: las dos secciones siguientes.
Configurarlo en AptiveAI
Sección titulada «Configurarlo en AptiveAI»Un propietario de tu empresa configura el chat integrado en AptiveAI Agents, en Ajustes → Chat integrado.
-
En Acceso, escribe los orígenes de tu aplicación en Orígenes permitidos: uno por línea, como
https://hostohttps://host:puerto, sin ruta. Como máximo 10. Solo las páginas de estos orígenes pueden mostrar el panel; el navegador lo rechaza en cualquier otro lugar. -
En Secreto de firma, pulsa Generar un secreto. El secreto se muestra una sola vez: cópialo en la configuración de tu servidor (un almacén de secretos o una variable de entorno), nunca en tu página. Al lado se muestra el Id de la empresa: tu servidor firma con él como emisor, y tu página se lo pasa a
AptiveAI.mount. -
Activa Chat integrado activado y pulsa Guardar. No se puede activar sin al menos un origen y un secreto.
-
Si quieres, elige los colores del panel en Tema (Tema).
Generar un secreto nuevo reemplaza el secreto al instante: el anterior deja
de funcionar de inmediato, así que actualiza tu servidor al mismo tiempo.
Desactivar el chat integrado cierra todas las sesiones del panel: la siguiente
solicitud de un panel abierto se rechaza, el panel le pide un token a tu página
y la respuesta es unavailable con disabled. Un panel que se abre mientras
está desactivado se carga igual en tus orígenes permitidos, pero no inicia la
sesión de nadie y dice que el asistente está desactivado.
Quién puede usar el panel
Sección titulada «Quién puede usar el panel»Cada persona que usa el panel necesita una cuenta de AptiveAI en tu
empresa. La crea un propietario por invitación — consulta Usuarios y
roles — o tu servidor con la API de
Aprovisionamiento (PUT /members/{email}), que no
le envía ningún correo a la persona ni le pone contraseña. El token responde
por una persona que ya existe; nunca la crea. Quien no tiene cuenta ve El asistente aún no está
configurado para usted. Pida a su administrador que lo invite.
En el panel una persona ve los agentes que ya puede usar en AptiveAI
Agents, según las reglas de uso compartido de
siempre, salvo que tu página indique uno con agentId (Qué agente
responde). Los agentes independientes no se ofrecen. Quien no tiene ningún agente
que usar ve Aún no tiene agentes con los que trabajar. Pida a su administrador
que comparta uno con usted.
Una persona sin puesto cuenta como si no tuviera ningún agente que usar
(no_agents), salvo en una cuenta que paga solo con su billetera — una
donde nadie tiene puesto (Una cuenta que paga solo con su
billetera).
Ahí, las personas sin puesto usan el panel, y cada una de sus tareas se paga
con la billetera a la misma tarifa que la API de Agentes. Una tarea se rechaza
antes de empezar cuando la billetera tiene menos de $0.05, y el panel le dice
a la persona que le pida a su administrador que agregue fondos.
El inicio de sesión, paso a paso
Sección titulada «El inicio de sesión, paso a paso»-
Tu página monta el panel. El frame del panel se carga desde AptiveAI Agents, que solo permite mostrarlo en tus orígenes permitidos.
-
El panel avisa que está listo y el script llama a tu
getToken. -
getTokenle pide un token a tu propio servidor. Tu servidor comprueba que la persona tiene la sesión iniciada en tu aplicación, firma un token para el correo de esa persona con el secreto de firma y lo devuelve. -
El script le entrega el token al panel, que lo cambia en AptiveAI Agents por una sesión propia. Si
getTokenlanza un error, no devuelve un token o el panel no logra comunicarse con AptiveAI Agents, el script vuelve a intentarlo al cabo de un momento; tras tres fallos seguidos se detiene yonEventrecibe{ type: 'error', code: 'token_failed' }. -
El panel se abre con la sesión iniciada. Cuando esa sesión termina, el panel vuelve a pedirlo y el script llama a
getTokenpara obtener un token nuevo.
El token
Sección titulada «El token»Un JSON Web Token firmado con HS256, con el secreto de firma como clave. El secreto se usa como texto plano, sus bytes UTF-8; no se decodifica de base64.
| Claim | Valor |
|---|---|
iss | El id de tu empresa |
aud | aptiveai-embed |
sub | El correo de la persona. Se compara, sin distinguir mayúsculas, con una cuenta de tu empresa |
iat | Cuándo se firmó, en segundos |
exp | Cuándo vence: como máximo 60 segundos después de iat |
jti | Un id único. Un token se usa una sola vez: el mismo jti se rechaza mientras el token siga vigente |
Se toleran hasta 30 segundos de diferencia entre el reloj de tu servidor y el de AptiveAI. Un token tiene como máximo 4.096 caracteres. Firma un token nuevo cada vez que el panel lo pida; nunca lo guardes para reutilizarlo.
Un endpoint de tokens
Sección titulada «Un endpoint de tokens»Cada ejemplo de abajo es un endpoint completo y mínimo. Toma el correo de la
sesión iniciada en tu propia aplicación, responde 401 cuando no la hay y
devuelve el token como texto plano, que es lo que lee getToken en el
inicio rápido. Cada uno lee el id de tu empresa y el secreto
de las variables de entorno APTIVEAI_ENTERPRISE_ID y APTIVEAI_EMBED_SECRET.
// npm install express joseimport express from 'express';import { SignJWT } from 'jose';import { randomUUID } from 'node:crypto';
const ENTERPRISE_ID = process.env.APTIVEAI_ENTERPRISE_ID;// La clave son los bytes UTF-8 del secreto: no lo decodifiques de base64.const SECRET = new TextEncoder().encode(process.env.APTIVEAI_EMBED_SECRET);
export async function signEmbedToken(email, audience = 'aptiveai-embed') { const now = Math.floor(Date.now() / 1000); return new SignJWT({}) .setProtectedHeader({ alg: 'HS256', typ: 'JWT' }) .setIssuer(ENTERPRISE_ID) .setAudience(audience) .setSubject(email) .setIssuedAt(now) .setExpirationTime(now + 60) .setJti(randomUUID()) .sign(SECRET);}
const app = express();// app.use(yourSession); — El inicio de sesión de tu propia aplicación, que debe identificar a la persona.
app.post('/aptiveai/token', async (req, res) => { // La persona con sesión iniciada en TU aplicación; nunca un correo de la solicitud. const email = req.user?.email; if (!email) return res.sendStatus(401); res.set('Cache-Control', 'no-store').type('text/plain').send(await signEmbedToken(email));});
app.listen(3000);# pip install fastapi uvicorn PyJWTimport osimport timeimport uuid
import jwt # PyJWTfrom fastapi import Depends, FastAPI, HTTPException, Requestfrom fastapi.responses import PlainTextResponse
ENTERPRISE_ID = os.environ["APTIVEAI_ENTERPRISE_ID"]# La clave son los bytes UTF-8 del secreto: no lo decodifiques de base64.SECRET = os.environ["APTIVEAI_EMBED_SECRET"].encode("utf-8")
def sign_embed_token(email: str, audience: str = "aptiveai-embed") -> str: now = int(time.time()) claims = { "iss": ENTERPRISE_ID, "aud": audience, "sub": email, "iat": now, "exp": now + 60, "jti": str(uuid.uuid4()), } return jwt.encode(claims, SECRET, algorithm="HS256")
app = FastAPI()
def signed_in_email(request: Request) -> str: # La persona con sesión iniciada en TU aplicación; nunca un correo de la solicitud. # El inicio de sesión de tu propia aplicación, que debe identificar a la persona. user = getattr(request.state, "user", None) if user is None: raise HTTPException(status_code=401) return user.email
@app.post("/aptiveai/token", response_class=PlainTextResponse)def aptiveai_token(email: str = Depends(signed_in_email)): return PlainTextResponse(sign_embed_token(email), headers={"Cache-Control": "no-store"})// Maven: com.auth0:java-jwt:4.4.0 (with Spring Boot's spring-boot-starter-web and spring-boot-starter-security)import com.auth0.jwt.JWT;import com.auth0.jwt.algorithms.Algorithm;import java.security.Principal;import java.time.Instant;import java.util.UUID;import org.springframework.http.CacheControl;import org.springframework.http.HttpStatus;import org.springframework.http.MediaType;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RestController;
@RestControllerpublic class AptiveAiTokenController { static final String ENTERPRISE_ID = System.getenv("APTIVEAI_ENTERPRISE_ID"); // La clave son los bytes UTF-8 del secreto: no lo decodifiques de base64. static final Algorithm HS256 = Algorithm.HMAC256(System.getenv("APTIVEAI_EMBED_SECRET"));
static String signEmbedToken(String email, String audience) { Instant now = Instant.now(); return JWT.create() .withIssuer(ENTERPRISE_ID) .withAudience(audience) .withSubject(email) .withIssuedAt(now) .withExpiresAt(now.plusSeconds(60)) .withJWTId(UUID.randomUUID().toString()) .sign(HS256); }
@PostMapping(value = "/aptiveai/token", produces = MediaType.TEXT_PLAIN_VALUE) public ResponseEntity<String> token(Principal principal) { // La persona con sesión iniciada en TU aplicación; nunca un correo de la solicitud. if (principal == null) return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build(); String email = principal.getName(); // Si el nombre de tu principal no es el correo, busca aquí el correo. return ResponseEntity.ok() .cacheControl(CacheControl.noStore()) .body(signEmbedToken(email, "aptiveai-embed")); }}// dotnet add package System.IdentityModel.Tokens.Jwtusing System.IdentityModel.Tokens.Jwt;using System.Security.Claims;using System.Text;using Microsoft.IdentityModel.Tokens;
var enterpriseId = Environment.GetEnvironmentVariable("APTIVEAI_ENTERPRISE_ID")!;// La clave son los bytes UTF-8 del secreto: no lo decodifiques de base64.var signingKey = new SymmetricSecurityKey( Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("APTIVEAI_EMBED_SECRET")!));
string SignEmbedToken(string email, string audience = "aptiveai-embed"){ var now = DateTime.UtcNow; var handler = new JwtSecurityTokenHandler(); var token = handler.CreateJwtSecurityToken(new SecurityTokenDescriptor { Issuer = enterpriseId, Audience = audience, Subject = new ClaimsIdentity(new[] { new Claim(JwtRegisteredClaimNames.Sub, email), new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()), }), IssuedAt = now, NotBefore = now, Expires = now.AddSeconds(60), SigningCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256), }); return handler.WriteToken(token);}
var builder = WebApplication.CreateBuilder(args);builder.Services.AddAuthentication(/* El inicio de sesión de tu propia aplicación (cookie, OpenID Connect, …). */);builder.Services.AddAuthorization();var app = builder.Build();app.UseAuthentication();app.UseAuthorization();
app.MapPost("/aptiveai/token", (ClaimsPrincipal user, HttpResponse response) =>{ // La persona con sesión iniciada en TU aplicación; nunca un correo de la solicitud. var email = user.FindFirstValue(ClaimTypes.Email); if (email is null) return Results.Unauthorized(); response.Headers.CacheControl = "no-store"; return Results.Text(SignEmbedToken(email));});
app.Run();También sirve cualquier otra biblioteca de JWT, en cualquier lenguaje, siempre que produzca los claims de arriba con HS256.
La sesión del panel
Sección titulada «La sesión del panel»El token abre una sesión de 8 horas que existe solo dentro del panel de tu aplicación. No es la sesión normal de la persona en AptiveAI Agents: no inicia su sesión en console.aptiveai.io, solo llega a las páginas del propio panel y no puede cambiar una contraseña, la verificación en dos pasos ni otras sesiones. Abrir en AptiveAI abre el producto completo en una pestaña nueva, donde la persona inicia sesión de la forma habitual.
Cerrar la sesión de una persona
Sección titulada «Cerrar la sesión de una persona»Cuando una persona cierra sesión en tu aplicación, o la desactivas, cierra también su sesión del panel; si no, sigue viva el resto de sus 8 horas. Tu servidor llama a:
POST https://console.aptiveai.io/api/embed/session/revokeContent-Type: application/json
{ "token": "<a revoke token>" }Es una llamada de servidor a servidor: sin cookie y sin navegador. El token de
revocación se firma igual que el token de inicio de sesión —
HS256 con el secreto de firma, iss el id de tu empresa, sub el correo de la
persona, como máximo 60 segundos de vigencia, un jti de un solo uso — con una
diferencia: aud es aptiveai-embed-revoke. Los dos no son
intercambiables: aquí se rechaza un token de inicio de sesión, y un token de
revocación nunca inicia la sesión de nadie.
| Respuesta | Significado |
|---|---|
200 { "ok": true, "ended": <n> } | Todas las sesiones del panel de esa persona abiertas a través de tu empresa terminaron; n es cuántas. Es 0 cuando no había ninguna, y también cuando el correo no tiene cuenta contigo, así que la respuesta nunca revela quién tiene una. Las sesiones propias de la persona en AptiveAI Agents no se tocan |
401 { "ok": false, "reason": "bad_token" } | El token no se verificó: secreto o audiencia equivocados, vencido, de más de 60 segundos o ya usado |
401 { "ok": false, "reason": "disabled" } | El chat integrado está desactivado para tu empresa, así que todas las sesiones ya terminaron |
429 | Más de 60 llamadas por minuto desde tu servidor; espera los segundos de Retry-After |
Cada ejemplo reutiliza la función de firma del
endpoint de tokens, con la audiencia de revocación, y
lee la dirección de AptiveAI Agents de APTIVEAI_CONSOLE_URL, que por defecto
es https://console.aptiveai.io.
// Usa signEmbedToken del endpoint de tokens de arriba.const CONSOLE_URL = process.env.APTIVEAI_CONSOLE_URL ?? 'https://console.aptiveai.io';
export async function endEmbedSessions(email) { const token = await signEmbedToken(email, 'aptiveai-embed-revoke'); const res = await fetch(`${CONSOLE_URL}/api/embed/session/revoke`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token }), }); return res.json(); // { ok: true, ended } o { ok: false, reason }}# Usa sign_embed_token del endpoint de tokens de arriba.import jsonimport urllib.request
CONSOLE_URL = os.environ.get("APTIVEAI_CONSOLE_URL", "https://console.aptiveai.io")
def end_embed_sessions(email: str) -> dict: body = json.dumps({"token": sign_embed_token(email, "aptiveai-embed-revoke")}).encode("utf-8") request = urllib.request.Request( f"{CONSOLE_URL}/api/embed/session/revoke", data=body, headers={"Content-Type": "application/json"}, method="POST", ) # Un 401 o un 429 lanza urllib.error.HTTPError. with urllib.request.urlopen(request) as response: return json.load(response)// Usa signEmbedToken del endpoint de tokens de arriba.import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;
public class AptiveAiSessions { static final String CONSOLE_URL = System.getenv().getOrDefault("APTIVEAI_CONSOLE_URL", "https://console.aptiveai.io"); // HTTP/1.1: algunos servidores cortan el upgrade a HTTP/2 que Java intenta por http. static final HttpClient HTTP = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
public static String endEmbedSessions(String email) throws Exception { String token = AptiveAiTokenController.signEmbedToken(email, "aptiveai-embed-revoke"); HttpRequest request = HttpRequest.newBuilder(URI.create(CONSOLE_URL + "/api/embed/session/revoke")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString("{\"token\":\"" + token + "\"}")) .build(); return HTTP.send(request, HttpResponse.BodyHandlers.ofString()).body(); // { ok: true, ended } o { ok: false, reason } }}// Usa SignEmbedToken del endpoint de tokens de arriba.using System.Net.Http.Json;
var consoleUrl = Environment.GetEnvironmentVariable("APTIVEAI_CONSOLE_URL") ?? "https://console.aptiveai.io";var http = new HttpClient();
async Task<string> EndEmbedSessions(string email){ var token = SignEmbedToken(email, "aptiveai-embed-revoke"); var res = await http.PostAsJsonAsync($"{consoleUrl}/api/embed/session/revoke", new { token }); return await res.Content.ReadAsStringAsync(); // { ok: true, ended } o { ok: false, reason }}Llámalo:
- cuando la persona cierra sesión en tu aplicación;
- cuando desactivas o quitas a la persona en tu aplicación.
Un panel que sigue abierto cuando termina su sesión se da cuenta en su
siguiente solicitud y le pide un token nuevo a tu página con getToken.
Después del cierre de sesión o la desactivación, tu endpoint de tokens debe
rechazar a esa persona, para que el panel siga sin sesión. En una computadora
compartida, quita además el panel de la página al cerrar sesión (unmount())
y monta uno nuevo para la siguiente persona, para que no quede en pantalla nada
del panel de la persona anterior.
Contexto de la página
Sección titulada «Contexto de la página»El contexto le dice al agente qué tiene abierto la persona en tu aplicación,
para que una pregunta como “¿qué cambió en este pedido?” no necesite
explicación. Pásalo a AptiveAI.mount y actualízalo con setContext cada vez
que la persona se mueva:
panel.setContext({ page: { title: 'Order 1042', url: location.href }, record: { type: 'order', id: '1042', label: 'Order 1042 — Jane Sample' }, note: 'Delivery was rescheduled this morning.',});| Campo | Qué es |
|---|---|
page | { title, url }: la página donde está la persona |
record | { type, id, label }: el registro que tiene abierto |
note | Cualquier texto breve que valga la pena saber |
Todos los campos son opcionales; setContext({}) o setContext(null) lo
borra.
- El panel lo muestra. Una línea sobre el cuadro de mensaje muestra la etiqueta del registro (o el título de la página), y la persona puede quitarlo de su próximo mensaje. Viaja con cada mensaje que la persona envía, y el mensaje lo muestra en la transcripción de la tarea.
- Es una pista, no una instrucción. Al agente se le dice que viene de la aplicación que la persona tiene abierta, no de la persona, y lee los datos reales con sus propios conectores.
- Que sea breve y sin secretos. El contexto completo tiene como máximo 4 KB de JSON; uno más grande se rechaza y el panel conserva el anterior.
Acciones de pantalla
Sección titulada «Acciones de pantalla»Una acción de pantalla permite que el agente cambie lo que la persona ve en
tu aplicación mientras responde: abrir un registro, cambiar de pestaña, ir a
una página. Las declaras con actions; el agente ve cada una como una
herramienta que puede llamar, descrita por tu description.
panel.setActions([ { name: 'go_to', description: 'Go to one of the main pages: "orders", "customers" or "schedule".', parameters: { type: 'object', properties: { page: { type: 'string', enum: ['orders', 'customers', 'schedule'] } }, required: ['page'], }, run: async ({ page }) => { if (!['orders', 'customers', 'schedule'].includes(page)) throw new Error('Unknown page'); await router.navigate(`/${page}`); return `Showing ${page}`; }, },]);Cómo transcurre una llamada:
-
El agente llama a una de tus acciones, y la transcripción de la tarea muestra el paso.
-
El script llama a tu
run(args)con los argumentos. -
Lo que devuelve
run— o aquello con que se resuelve — le dice al agente el resultado, que también muestra la transcripción:runAl agente se le dice devuelve un string, o cualquier otra cosa Se hizo, con el string como mensaje breve devuelve falseNo se hizo devuelve { ok, message }Se hizo o no, según ok, conmessagelanza un error No se hizo, con la primera línea del mensaje de tu error Una acción que el agente nombra y que ya no ofreces se responde con Unknown action. Cada pedido del agente se responde una sola vez:
runnunca se llama dos veces para el mismo pedido.
Las acciones de pantalla son de mejor esfuerzo:
- El agente espera como máximo 10 segundos una respuesta y luego sigue como si la acción no se hubiera hecho.
- Un tramo del trabajo del agente puede llamar como máximo 5 acciones de pantalla.
- Si el panel está cerrado, o la persona salió de la página, la acción no se hace y la tarea sigue.
- Una tarea a la que la persona le envía un mensaje desde el producto completo, fuera de tu aplicación, no tiene acciones de pantalla.
| Límite | Valor |
|---|---|
| Acciones declaradas a la vez | 20 |
name | Letras minúsculas, dígitos y _, empezando por una letra, como máximo 40 caracteres, sin repetir |
description | Obligatoria, como máximo 300 caracteres |
parameters | Un JSON schema de type: "object" con properties (y required opcional), como máximo 2 KB |
| El mensaje con que responde una acción | Como máximo 300 caracteres; lo que sobra se corta |
Tu propio sistema, como cada persona
Sección titulada «Tu propio sistema, como cada persona»Cuando el agente trabaja en el sistema de tu propia aplicación, dale un conector a tu servidor MCP y configúralo como Cada persona inicia sesión: así cada persona inicia sesión en tu servidor como ella misma, y cada acción que el agente hace ahí lleva el token de esa persona, nunca el de un administrador.
Lo que tu servidor debe ofrecer
Sección titulada «Lo que tu servidor debe ofrecer»Un servidor MCP por Streamable HTTP que inicie la sesión de las personas con OAuth, como describe la especificación de autorización de MCP:
- Una llamada sin autenticar responde
401, y tu servidor publica sus metadatos de recurso protegido (RFC 9728) con el nombre de su servidor de autorización. - El servidor de autorización publica sus metadatos (RFC 8414) y admite PKCE
con
S256, el parámetroresource(RFC 8707), tokens de actualización y el registro dinámico de clientes (RFC 7591). AptiveAI registra un cliente para cada inicio de sesión, con la URI de redirecciónhttps://console.aptiveai.io/api/embed/connect/callback(yhttps://console.aptiveai.io/api/connectors/oauth/callbackpara un inicio de sesión hecho dentro de AptiveAI Agents). - Emite un token para la persona que inicia sesión, y tu servidor MCP actúa como esa persona con él. Un token que actúa como una cuenta de servicio fija le quita todo el sentido.
- Dice qué cuenta inició sesión, con un
emailde un endpoint de userinfo o dentro de un access token JWT (conemail_verified: truecuando tu servidor lo ha verificado).
Lo que configura un administrador
Sección titulada «Lo que configura un administrador»Un administrador conecta tu servidor una vez en AptiveAI Agents (Conectores → Servidor MCP personalizado, autenticación El inicio de sesión del propio servidor), le da la conexión al agente que monta tu panel y elige Cada persona inicia sesión en Quién inicia sesión. Esa primera conexión solo indica el servidor y las herramientas que el agente puede usar; sobre ella no se ejecuta el trabajo de nadie más.
Para una persona solo se usa su propia conexión a esa dirección exacta — el inicio de sesión del panel siempre la hace a esa dirección, envíe lo que envíe el navegador —, y no ofrece ninguna herramienta que no ofrezca la del administrador. Si no la tiene, la herramienta no se ejecuta.
Lo que ve una persona la primera vez
Sección titulada «Lo que ve una persona la primera vez»- Cuando el agente necesita tu sistema por primera vez, el chat pregunta: host.example aún no está conectado para ti. Conéctalo para que pueda continuar. con Iniciar sesión en host.example y Ahora no.
- Iniciar sesión en host.example abre una pestaña nueva (el panel nunca sale de tu página; permite la pestaña si el navegador lo pregunta). Primero dice Vas a conectar host.example para Pat Example (pat@example.test) en Northwind Desk. Si no eres tú, cierra esta pestaña. — con el nombre de para quién es la conexión, y en qué cuenta — y un botón Continuar.
- Continuar lleva a la página de inicio de sesión de tu propio servidor.
- Después de iniciar sesión, la pestaña dice Ya estás conectado. Cierra esta pestaña y vuelve al chat. y la tarea continúa sola. La próxima vez no se pregunta nada.
La pestaña funciona sin ninguna sesión de AptiveAI: lleva un enlace de un solo uso, válido diez minutos, que solo puede hacer la conexión de esa persona a tu servidor, para la tarea que la pidió. Si tarda más, o el inicio de sesión falla, el chat lo dice y la persona puede volver a elegir Iniciar sesión. Ahora no deja que el agente continúe sin tu sistema.
Comprobar que nadie actúa como otra persona
Sección titulada «Comprobar que nadie actúa como otra persona»Antes de abrir el panel a personas que no son administradoras, consulta
GET /connectors con la API de
Aprovisionamiento desde tu servidor: lista cada conexión a una dirección de
servidor, de quién es y con quién está compartida, y cómo la usa cada agente.
Para el agente que montas, su permiso en la dirección de tu servidor debe ser
per_person, y ninguna conexión a esa dirección debe estar compartida.
Sin tema, el panel se ve como AptiveAI Agents. Para que combine con tu aplicación, abre Ajustes → Chat integrado → Tema y elige un Tema base, y luego los colores de Página, Barra lateral y tarjetas y Acento para Claro y Oscuro. Claro y oscuro decide si cada persona ve los colores que eligió para sí (Según cada persona) o un solo aspecto para todos (Siempre este aspecto). Desde una captura propone colores a partir de una imagen de tu aplicación. Los colores que se leen mal se marcan antes de que puedas guardar.
El modo de tu página elige cuál de los dos juegos de colores muestra el
panel. Pasa theme: 'light' o 'dark' a mount y llama a setTheme cuando
tu página cambie. Una empresa que eligió Siempre este aspecto conserva ese
único aspecto, pase lo que pase tu página. Sin theme, el panel sigue la
configuración del sistema de quien lo visita. Para seguir tú mismo al
dispositivo:
const dark = window.matchMedia('(prefers-color-scheme: dark)');const panel = AptiveAI.mount('#assistant', { /* … */ theme: dark.matches ? 'dark' : 'light' });dark.addEventListener('change', (e) => panel.setTheme(e.matches ? 'dark' : 'light'));Navegadores y cookies
Sección titulada «Navegadores y cookies»La sesión del panel se guarda en una cookie de terceros particionada
(SameSite=None; Secure; Partitioned): el navegador la conserva solo para el
panel dentro de tu sitio, separada de cualquier otro sitio, y nunca se
convierte en la sesión normal de la persona en AptiveAI Agents.
Solución de problemas
Sección titulada «Solución de problemas»Cuando el panel no puede iniciar la sesión de la persona, le muestra una frase
y tu onEvent recibe { type: 'unavailable', reason }. Cuando se rechaza un
mensaje de tu página, recibe { type: 'error', code }.
| Síntoma | Causa | Solución |
|---|---|---|
| El área del panel queda en blanco y la consola del navegador informa que se negó a mostrar la página en un frame | El origen de tu página no está en Orígenes permitidos, no hay ningún origen en la lista o el id de la empresa es incorrecto | Agrega el origen exacto (esquema, host y puerto) en Ajustes → Chat integrado y revisa el id que pasas |
unavailable, motivo disabled | El chat integrado está desactivado para la empresa. El panel se carga igual y lo indica, y se rechaza cualquier token | Un propietario activa Chat integrado activado. No envíes más tokens hasta que tu página vuelva a cargarse |
unavailable, motivo bad_token | Se rechazó el token: secreto equivocado, iss o aud equivocados, vigencia de más de 60 segundos, vencido, reloj muy desfasado o un jti usado dos veces | Firma con el secreto actual y los claims de El token; firma un token nuevo en cada llamada a getToken; revisa el reloj de tu servidor |
unavailable, motivo no_account | Ninguna cuenta de tu empresa tiene el correo del token | Invita a la persona — consulta Usuarios y roles — o comprueba que tu servidor firma el correo que la persona tiene en AptiveAI |
unavailable, motivo account_unavailable | La empresa está pausada, bloqueada o cancelada, o la cuenta de la persona está suspendida | La persona consulta a su administrador; un propietario revisa Facturación y puestos |
unavailable, motivo no_agents | La persona no tiene ningún agente que pueda usar o, con agentId, no puede usar ese agente (no está compartido con ella, se eliminó o no es un agente normal). Una persona sin puesto cuenta como si no tuviera ninguno, salvo en una cuenta que paga solo con su billetera | Comparte el agente con la persona — consulta Compartir —, revisa el agentId que pasas o dale un puesto a la persona |
error, código network | El panel no pudo comunicarse con AptiveAI Agents al iniciar la sesión | El script le pide por sí solo un token nuevo a getToken; si se repite, revisa la conexión de la persona |
error, código token_failed | getToken falló tres veces seguidas: lanzó un error, no devolvió un token o el panel no logró comunicarse con AptiveAI Agents | Revisa tu endpoint de tokens y la conexión de la persona; el script vuelve a intentarlo cuando el panel se recarga |
error, código session_not_kept | Tres inicios de sesión seguidos terminaron antes de 30 segundos: el navegador no conserva la sesión del panel, normalmente porque bloquea su cookie. Safari no se ha verificado | Prueba el panel en un navegador basado en Chromium o en Firefox y revisa si el navegador bloquea las cookies de terceros. El script deja de pedir tokens hasta que el panel vuelva a cargarse |
error, código context_too_large | El contexto pasa de 4 KB | Envía menos: una etiqueta y un id bastan |
error, código too_many_actions | Más de 20 acciones | Declara menos |
error, código invalid_action | Una acción incumple una regla de arriba: su nombre, su descripción, su schema parameters, un tamaño, o dos con el mismo nombre | Corrige la acción; toda la lista se rechaza hasta que sea válida |
error, código invalid_message | Un mensaje no tenía la forma esperada | Revisa lo que le pasas a setContext y setActions |
| El agente dice que la pantalla no respondió | run no respondió en 10 segundos, el panel estaba cerrado o la persona salió de la página | Haz que run responda rápido; solo necesita iniciar la navegación |
Avanzado: el protocolo de mensajes
Sección titulada «Avanzado: el protocolo de mensajes»El script es una capa delgada sobre un pequeño protocolo de postMessage entre
tu página y el frame del panel. Si no puedes usar el script, puedes hablar el
protocolo directamente.
El frame. Créalo con el id de tu empresa. Agrega &lang=es o &lang=en a
la dirección para elegir el idioma del panel, &theme=light o &theme=dark
para que empiece en el modo de tu página, &agent=<agent id> para indicar el
único agente con el que habla, o &default_agent=<agent id> para indicar el
agente en el que se abre (Qué agente responde):
<iframe src="https://console.aptiveai.io/embed?e=YOUR-ENTERPRISE-ID" title="Assistant" allow="clipboard-write"></iframe>Quién puede incrustarlo. Solo tus orígenes permitidos. Para una empresa
desconocida, o sin ningún origen permitido, nadie puede. Una empresa que
desactivó el chat integrado sigue permitiendo que sus orígenes permitidos
incrusten el panel, para que el panel pueda decir que está desactivado: el
frame se carga, envía aptiveai:ready y responde a tu aptiveai:session con
aptiveai:unavailable y el motivo disabled. Deja entonces de enviar tokens
hasta que tu página vuelva a cargarse; enviar uno en cada aptiveai:ready solo
le pide a tu servidor tokens que se van a rechazar.
Reglas de seguridad para tu página:
- Envía mensajes al frame con su origen exacto,
https://console.aptiveai.io, como destino; nunca*. - Acepta un mensaje solo cuando
event.originseahttps://console.aptiveai.ioyevent.sourcesea elcontentWindowdel frame. - Ignora los mensajes cuyo
typeno empiece poraptiveai:.
El frame acepta aptiveai:context y aptiveai:actions en cuanto ha enviado
aptiveai:ready.
Cada mensaje es un objeto con un type y v: 1. Un mensaje con otro v se
rechaza con aptiveai:error unsupported_version.
De tu página al frame
Sección titulada «De tu página al frame»type | Campos | Significado |
|---|---|---|
aptiveai:session | token | Inicia la sesión de la persona. Envíalo en respuesta a aptiveai:ready y a aptiveai:session-expired, cada vez con un token nuevo |
aptiveai:context | opcionales page: { title, url }, record: { type, id, label }, note | Lo que la persona tiene abierto. Envíalo cada vez que cambie; sin campos, borra el contexto |
aptiveai:actions | actions: [{ name, description, label?, parameters? }] | Las acciones de pantalla que ofreces. Enviarlo de nuevo reemplaza la lista; una lista vacía las retira. label (como máximo 80 caracteres) es tu propia redacción del paso en la transcripción |
aptiveai:action-result | id, ok, message opcional | Tu respuesta a un aptiveai:action: ok: true cuando se hizo, ok: false con un mensaje breve cuando no |
aptiveai:theme | theme: light o dark | El modo de tu página. Envíalo después de aptiveai:ready (de nuevo tras cada aptiveai:ready) y cada vez que tu página cambie |
Del frame a tu página
Sección titulada «Del frame a tu página»type | Campos | Significado |
|---|---|---|
aptiveai:ready | — | El frame está escuchando. Envía aptiveai:session |
aptiveai:signed-in | — | La persona inició sesión. Envía ahora aptiveai:context y aptiveai:actions |
aptiveai:session-expired | — | La sesión del panel terminó. Envía un aptiveai:session nuevo |
aptiveai:unavailable | reason | No se puede iniciar la sesión de la persona: no_account, disabled, bad_token, account_unavailable o no_agents (Solución de problemas). No envíes más tokens hasta que tu página vuelva a cargarse |
aptiveai:task | id, status | Una tarea empezó o se abrió, o cambió de estado (los estados) |
aptiveai:action | id, name, arguments | El agente te pide hacer una de tus acciones. Responde con aptiveai:action-result y el mismo id |
aptiveai:error | code | Se rechazó un mensaje tuyo (unsupported_version, invalid_message, context_too_large, too_many_actions, invalid_action), o network: el panel no logró comunicarse con AptiveAI Agents al iniciar la sesión; envía un token nuevo |
Límites
Sección titulada «Límites»Un mensaje que pasa un límite se rechaza con aptiveai:error y no tiene efecto.
| Límite | Valor |
|---|---|
Un mensaje aptiveai:context completo | 4 KB de JSON |
Acciones en un aptiveai:actions | 20 |
name de una acción | ^[a-z][a-z0-9_]{0,39}$, sin repetir en la lista |
description de una acción | De 1 a 300 caracteres |
label de una acción | 80 caracteres |
parameters de una acción | Un JSON schema de type: "object" con properties, como máximo 2 KB de JSON |
message de aptiveai:action-result | 300 caracteres (lo que sobra se corta) |
id de aptiveai:action-result | 100 caracteres |
token de aptiveai:session | 4.096 caracteres |