Referencia de la API del widget externo

URL base

La API del widget se sirve desde tu Salesforce Site, bajo la ruta /services/apexrest/redaai/chat/v1/:

https://<your-org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1/

El host exacto depende del dominio de tu Site. Obtenlo desde Configuración › Sites; el script de carga que incrustas en tu sitio web usa la misma ruta en el atributo data-endpoint.

Autenticación

Cada solicitud requiere una clave de API. Pásala como encabezado HTTP o en el cuerpo de la solicitud — la API comprueba ambos:

Salesforce Sites puede eliminar los encabezados personalizados en algunas configuraciones, por lo que existe la alternativa en el cuerpo. Usa cualquiera de las dos; la forma del cuerpo es más confiable en CDN y proxies, y es la que usa de forma predeterminada el cargador del widget incluido.

Después de /init, cada solicitud posterior también necesita el token de sesión que devuelve /init:

Consulta Administración de claves de API para generar, rotar y revocar claves.

CORS

La API refleja Access-Control-Allow-Origin para las llamadas desde el navegador. La definición de agente puede restringir las llamadas mediante el campo Orígenes permitidos (lista de orígenes separados por comas); déjalo en blanco para permitir cualquier origen. Cuando está configurado, solo los orígenes de la lista tienen éxito; los demás reciben un error ORIGIN_NOT_ALLOWED.

Cambiado en la V1.13. El origen se toma del encabezado Origin de la solicitud, no del cuerpo de la solicitud. Por lo tanto, una solicitud sin encabezado Origin — cualquier llamada de servidor a servidor — se rechaza cuando Orígenes permitidos está configurado. Consulta POST /chat/v1/init.

Endpoints

Cuatro endpoints, todos POST. Las solicitudes OPTIONS de verificación previa (pre-flight) se gestionan automáticamente.

POST /chat/v1/init

Valida la clave de API, comprueba el origen de la llamada y crea una sesión. Devuelve el token de sesión junto con los metadatos del agente que tu widget necesita para representar el estado de bienvenida.

Cuerpo de la solicitud

{
  "clientKey": "<tu clave de API>"
}

Cambiado en la V1.13. El origen de la llamada ahora se toma del encabezado Origin de la solicitud — lo establece el navegador y no lo pueden sobrescribir los scripts de la página. Un campo origin en el cuerpo de la solicitud aún se acepta por compatibilidad con versiones anteriores, pero se ignora: un valor proporcionado por la llamada no puede usarse para restringir la llamada misma. Los widgets que aún lo envían siguen funcionando sin cambios.

Esto es importante para las llamadas que no provienen del navegador. Una solicitud de servidor a servidor no lleva encabezado Origin, por lo que se rechaza con ORIGIN_NOT_ALLOWED cuando el agente tiene configurado Orígenes permitidos. Si llamas a esta API desde tu propio backend, deja Orígenes permitidos en blanco y restringe el acceso de otra manera. Consulta Configuración de los orígenes permitidos.

Respuesta (200 OK)

{
  "sessionToken":     "<token de sesión opaco>",
  "agentName":        "support-assistant",
  "displayName":      "Support Assistant",
  "welcomeMessage":   "Hi! How can I help today?",
  "mascotImage":      "https://…/mascot.png",
  "maxMessageLength": 2000
}

• sessionToken — pásalo en cada solicitud posterior.
• agentName — el identificador del agente, útil para el análisis del lado del cliente.
• displayName — el nombre legible que se muestra en el encabezado del widget y en la sección principal de bienvenida.
• welcomeMessage — el texto de bienvenida externo configurado del agente. Cadena vacía cuando no está configurado.
• mascotImage — la URL de la mascota cuando hay una configurada. Cadena vacía cuando no la hay.
• maxMessageLength — el límite de longitud de los mensajes del usuario, en caracteres.

POST /chat/v1/message

Envía un único mensaje del usuario al agente. Devuelve la respuesta del agente una vez que se completa el bucle agéntico.

Cuerpo de la solicitud

{
  "clientKey":    "<tu clave de API>",
  "sessionToken": "<from /init>",
  "message":      "What's open on the Acme account?"
}

Los mensajes que superan maxMessageLength (devuelto por /init) se rechazan con INVALID_INPUT.

Respuesta (200 OK)

{
  "response":            "<texto de respuesta del agente>",
  "creditsUsed":         1.42,
  "conversationId":      "a0Q…",
  "pendingActions":      [],
  "continuationPending": true,
  "continuationDepth":   0
}

• response — la respuesta del agente, incluidos los marcadores SUGGESTIONS o ACTION incrustados que analiza el renderizador del widget.
• creditsUsed — créditos consumidos en este turno.
• conversationId — el ID de Salesforce del registro de conversación. Útil para hacer referencias cruzadas con la transcripción de la Conversación en Salesforce.
• pendingActions — acciones pendientes de confirmación por el cliente. En el canal de widget externo siempre está vacío, porque las tarjetas de confirmación solo existen en el canal interno. Consulta POST /chat/v1/action más abajo.
• continuationPending — true cuando el agente ha ejecutado una o más acciones en este turno y todavía no ha narrado el resultado. Llama a /chat/v1/continue para obtener esa narración.
• continuationDepth — cuántos turnos de continuación se han ejecutado ya. Devuélvelo en la siguiente llamada a /continue.

POST /chat/v1/action

Ejecuta bajo demanda una herramienta de Acción concreta. Solo se aceptan las herramientas de Acción asignadas al agente y con alcance al canal de widget externo.

Cuerpo de la solicitud

{
  "clientKey":    "<tu clave de API>",
  "sessionToken": "<from /init>",
  "actionTool":   "create_record",
  "params": {
    "object_name":  "Case",
    "field_values": { "Subject": "Issue with login", "…": "…" }
  }
}

Respuesta (200 OK)

{
  "success": true,
  "result":  "<tool execution result, JSON-serialised>"
}

La forma de result coincide con el resultado de la herramienta subyacente. Para las herramientas de acción integradas, eso significa una carga útil estructurada con al menos un indicador success, un message y (cuando corresponde) un recordId.

POST /chat/v1/continue

Pide al agente que narre el resultado de las acciones que ejecutó en el turno /message anterior. No se envía ningún mensaje nuevo del usuario. Llámalo siempre que una respuesta vuelva con continuationPending: true.

Cuerpo de la solicitud

{
  "clientKey":         "<tu clave de API>",
  "sessionToken":      "<de /init>",
  "continuationDepth": 0
}

Respuesta (200 OK)

{
  "response":            "<narración del agente sobre lo ocurrido>",
  "creditsUsed":         0.68,
  "conversationId":      "a0Q…",
  "continuationPending": false,
  "continuationDepth":   1
}

continuationPending sigue siendo true si el agente encadenó otra acción mientras narraba, así que trátalo como un bucle: sigue llamando a /continue, devolviendo el continuationDepth recibido, hasta que vuelva como false. El ajuste Profundidad máxima de continuación del agente acota la cadena, de modo que siempre termina.

POST /chat/v1/history

Devuelve hasta 100 mensajes de la conversación de la sesión, del más antiguo al más reciente. Útil cuando el widget se vuelve a conectar después de una actualización y necesita restaurar el hilo visible.

Cuerpo de la solicitud

{
  "clientKey":    "<tu clave de API>",
  "sessionToken": "<from /init>"
}

Respuesta (200 OK)

{
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "2026-04-25T08:55:12.000Z" },
    { "role": "assistant", "content": "…", "timestamp": "2026-04-25T08:55:14.000Z" }
  ]
}

Respuestas de error

Todos los errores comparten la misma forma:

{
  "error": "<localised user-facing message>",
  "code":  "<machine-readable code>"
}

Usa code para las decisiones programáticas en tu cliente; muestra error al usuario final.

Límites de tasa

Cada llamada pasa por varios limitadores de tasa en orden. Los dos primeros y el tope de mensajes se configuran por agente en la Definición de agente; el tope diario de créditos es de toda la organización, un ajuste de plataforma compartido por todos los agentes externos, de modo que un solo bot con mucho tráfico puede agotar el presupuesto del día para todos. Ponerlo en 0 significa ilimitado: no recomendable en un widget público.

Consulta Referencia de configuración de la plataforma para conocer los detalles del tope de crédito diario.

Ciclo de vida de la sesión

• Creación: /init crea una sesión vinculada a la IP del cliente que llama y al origen validado.
• Validez: las sesiones permanecen válidas mientras se usen. La actividad en /message, /action o /history reinicia la sesión.
• Tiempo de espera: las sesiones inactivas caducan después de los Minutos de tiempo de espera de sesión del agente (30 de forma predeterminada). Las llamadas con un token de sesión caducado reciben SESSION_EXPIRED; el widget debería volver a llamar a /init.
• Límites estrictos: una sesión termina cuando alcanza el Máximo de mensajes por sesión. Las llamadas posteriores reciben MAX_MESSAGES hasta que se crea una nueva sesión.

Configuración requerida en el agente

Varios campos de la Definición de agente determinan el comportamiento del widget:

Postura de seguridad

• Ejecución como usuario invitado. La API se ejecuta como el usuario invitado del Salesforce Site. Los permisos CRUD y FLS del perfil de ese usuario determinan lo que el agente y cualquier herramienta pueden leer o escribir.
• Clave de API con alcance a un solo agente. Cada agente externo tiene su propia clave; revócala y rótala por agente sin afectar a los demás.
• Orígenes en lista de permitidos. Configura Orígenes permitidos en cada agente de producción. En blanco significa que cualquier origen puede llamar — cómodo para pruebas, arriesgado en producción.
• Mensajes de error genéricos. La API nunca refleja errores internos a los clientes. Las fallas graves se registran en el Registro de incidentes para su investigación por parte del administrador.
• Tope de crédito diario. El Tope de crédito diario externo es el límite máximo de toda la organización que impide que un bot público descontrolado agote el presupuesto de la licencia.

Prácticas recomendadas

Usa el cargador incluido a menos que tengas un motivo para no hacerlo. El cargador se encarga de la invalidación de caché, las alternativas de encabezados, la representación de errores y los atributos de datos de Personalización de la interfaz del widget. Crear tu propio cliente solo tiene sentido para las llamadas que no provienen del navegador (aplicaciones móviles, integraciones de servidor).

Trata code como la fuente de verdad. La cadena error está localizada para los usuarios finales y puede cambiar entre versiones. El code es estable.

Reinicia las sesiones ante SESSION_EXPIRED, no ante cualquier error. El cargador del widget lo hace; los clientes personalizados también deberían hacerlo. No trates RATE_LIMITED ni CREDIT_LIMIT como problemas de sesión — requieren una recuperación diferente (espera con retroceso y atención del administrador, respectivamente).

Configura Orígenes permitidos en cada agente de cara al público. Dejarlo en blanco en producción elimina una capa de defensa en profundidad.

Vigila el tope de crédito diario. Es la red de seguridad para los bots de cara al público; ajústalo después de observar el tráfico real.

Cambios incluidos en 1.16000

El límite horario por agente también se aplica durante la última hora UTC del día. Las API externa y de Comunidad utilizan un código estable de límite de créditos para que la respuesta HTTP 429 no dependa del mensaje traducido.

Lista de actualización del cliente

Preguntas frecuentes

Próximos pasos

Lee Administración de claves de API para la emisión de claves, o Referencia de la API de Comunidad para su equivalente en el portal autenticado.