Configuración del widget externo
Financiación y uso de IA
IA incluida utiliza créditos REDA. Traiga su propia IA utiliza la cuenta de proveedor de su organización, facturada directamente por ese proveedor. La licencia determina un modelo para toda la organización. En ambos, REDA AI controla las herramientas y acciones configuradas en Salesforce. Configure la licencia y las cuentas de IA.
Si el administrador cambia la conexión efectiva, el modelo o la financiación, las sesiones afectadas necesitan una conversación nueva. Iníciela cuando se le solicite; no se puede continuar la conversación anterior en la nueva ruta. Para cuentas propias, verifique el acceso a credenciales de la identidad invitada o del usuario autenticado del portal. Consulte los permisos.
Un agente con Channel = External_Widget está vinculado únicamente a la superficie del widget público. No se puede invocar desde el LWC interno de Salesforce, desde Flujo / Apex (canal de API) ni desde una página de comunidad o portal. A la inversa, el extremo REST público (/chat/v1/*) solo acepta agentes cuyo Canal esté configurado como External_Widget — enrutar un agente Interno, de API o de Comunidad a través de esta superficie se rechaza con un error claro. Elige el canal que coincida con la superficie en la que pretendes implementar.
¿Qué es el widget externo?
El widget externo te permite insertar un widget de chat de REDA AI en tu sitio web, portal o aplicación web. Los visitantes pueden hacer preguntas, buscar en tus datos y obtener ayuda — todo sin iniciar sesión en Salesforce.
- No requiere autenticación — Los visitantes chatean sin un inicio de sesión de Salesforce
- Acceso de invitado — Usa un perfil de usuario invitado configurado con permisos limitados y controlados
- Restricciones de origen — Tú controlas exactamente qué dominios pueden insertar el widget
- Totalmente configurable — Los colores, el texto, el diseño, el estilo de la burbuja y la pantalla de bienvenida son todos personalizables mediante los atributos de inserción
- Adaptable a móviles — Se adapta automáticamente a las pantallas móviles con un modo de pantalla completa opcional
Descripción general de la configuración
-
Configura la Definición de agente
Establece el canal en External_Widget y configura los orígenes permitidos, el mensaje de bienvenida y las herramientas.
-
Genera la clave de API
Crea una clave de API externa que el widget usa para autenticarse.
-
Inserta el widget
Agrega una sola etiqueta de script a tu sitio web con la clave de API y el extremo.
-
Personaliza la apariencia
Agrega atributos
data-*opcionales para controlar los colores, el diseño, el estilo de la burbuja y la pantalla de bienvenida.
Paso 1: Configura la Definición de agente
- Ve al objeto REDAAI Agent Definition en Configuración
- Abre o crea un registro de Definición de agente
- Establece Canal en
External_Widget - Establece Orígenes permitidos en el dominio o los dominios donde se insertará el widget (p. ej.,
https://example.com, https://www.example.com) - Establece Mensaje de bienvenida externo en un saludo para los visitantes (p. ej., “¡Hola! ¿En qué podemos ayudarte hoy?”)
- Si lo deseas, carga una Imagen de mascota para un avatar personalizado
- Asigna las herramientas adecuadas (se recomienda solo lectura para los usuarios invitados)
- Activa el agente
Paso 2: Genera una clave de API
El widget se autentica usando una clave de API externa. Consulta Administración de claves de API para conocer los pasos detallados. Necesitarás dos valores del registro de la clave de API:
- Clave de API — la cadena de la clave generada
- URL del extremo — el extremo REST de Salesforce Sites (formato:
https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1)
Paso 3: Inserta el widget
Agrega una sola etiqueta <script> a tu sitio web. El Cargador de REDA AI se encarga de todo — cargar el widget, aplicar tu configuración e inicializar el chat.
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key-here"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1">
</script>
Reemplaza <org> con el prefijo de My Domain de tu organización de Salesforce y your-api-key-here con la clave de API real.
Los atributos data-api-key y data-endpoint son obligatorios. Sin ellos, el widget no se cargará.
Esta clave es pública. Está en el HTML de tu página, así que cualquiera que vea el código fuente puede leerla — eso es intencional en un widget público, y por eso la clave por sí sola nunca debe bastar para llegar a nada sensible. El trabajo real lo hacen dos controles: los Orígenes permitidos, que se comprueban contra la cabecera Origin que fija el navegador (el JavaScript de la página no puede falsificarla), de modo que la clave solo funciona si se llama desde tus dominios; y los permisos del propio usuario invitado, que limitan lo que cualquier conversación puede alcanzar, sin importar lo que se le pida al agente. Configura ambos como si la clave estuviera en una valla publicitaria.
Ejemplo de inserción con todas las funciones
Puedes agregar atributos data-* opcionales para personalizar la apariencia y el comportamiento del widget:
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key-here"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
data-title="Support Agent"
data-primary-color="#0070D2"
data-bubble-style="pill"
data-bubble-label="Ask Support"
data-header-style="minimal"
data-welcome-heading="How can {title} help?"
data-welcome-subtext="Ask me anything about your account"
data-theme="light"
data-position="bottom-right"
data-display-mode="bubble">
</script>data-display-mode="docked-right" (o docked-left) y el asistente se abre como un panel de altura completa anclado a ese borde, en lugar de una tarjeta flotante — útil cuando las respuestas incluyen tarjetas de propiedades o fotos. La burbuja de inicio permanece exactamente donde está. Consulta Modo de visualización.
Consulta Personalización de la interfaz del widget para ver la lista completa de atributos data-*.
Configuración de los orígenes permitidos
El campo Orígenes permitidos en la Definición de agente controla qué dominios pueden insertar tu widget. Esta es una función de seguridad que impide la inserción no autorizada.
Orígenes permitidos está vacío de forma predeterminada, y vacío significa sin restricción — cualquier sitio web que tenga tu clave de API puede usar tu agente. Dado que la clave de API es visible en el código fuente de tu página (algo inevitable en cualquier widget insertable — consulta el Paso 2), cualquiera puede copiarla de tu sitio. Completar Orígenes permitidos es lo que impide que otro sitio web use tu agente y tus créditos.
Recomendamos configurarlo en cada widget en producción.
https://example.com, https://www.example.com, https://support.example.com
El widget se carga solo en estos tres dominios. Cualquier otro dominio queda bloqueado.
- Incluye siempre el protocolo —
https://example.comyexample.comse tratan de forma diferente - Separa varios dominios con comas
- Enumera todos los dominios que tus visitantes usan realmente — si
www.example.comyexample.comsirven ambos tu sitio, incluye los dos, o el widget fallará en uno de ellos - Prueba antes de pasar a producción — primero inserta en un dominio de ensayo para verificar que funciona, y agrega el dominio de ensayo a la lista mientras lo haces
Cuando Orígenes permitidos está configurado, REDA AI verifica el sitio web del que realmente provino la solicitud, según lo informado por el navegador del visitante. Una página no puede afirmar ser un sitio diferente, por lo que tu clave no funcionará si se copia en el sitio web de otra persona.
De esto se derivan dos cosas. Las solicitudes que no provienen de un navegador en absoluto se rechazan cuando Orígenes permitidos está configurado — así que si llamas a la API de chat directamente desde tu propio servidor, deja Orígenes permitidos en blanco y controla el acceso de otra manera. Y una lista de permitidos es una capa, no toda la historia: los límites por conversación, por hora y por día en la Definición de agente son los que limitan el uso si alguna vez se hace un uso indebido de una clave.
¿Estás actualizando? Si Orígenes permitidos está en blanco — el valor predeterminado — nada cambia para ti. Los widgets siguen funcionando exactamente como antes.
Ten claro qué frena y qué no frena la lista de orígenes. Funciona porque el propio
navegador establece la cabecera Origin y el JavaScript de la página no puede
sobrescribirla, así que una clave robada y pegada en otro sitio web se rechaza.
No puede frenar a quien llame desde un servidor falsificando la cabecera, con
curl o con cualquier script. Ninguna lista de orígenes puede.
Lo que limita ese caso es todo lo demás: los límites de tasa por sesión y por hora, el tope diario de créditos de la organización y revocar la clave. Trata Orígenes permitidos como el control que mantiene tu widget en tus propias páginas, no como autenticación.
Permisos de usuario invitado
Los agentes de widget externo se ejecutan bajo un perfil de usuario invitado. Este perfil debe configurarse con cuidado:
- Acceso limitado a objetos — Concede acceso solo a los objetos que los visitantes necesitan (p. ej., Knowledge, Caso)
- Acceso limitado a campos — Expón solo campos públicos y no sensibles
- Reglas de colaboración — Los usuarios invitados solo pueden ver los registros marcados como públicos mediante reglas de colaboración
- Acceso de escritura (opcional) — Concede acceso de creación con moderación (p. ej., solo para la creación de casos)
Revisa siempre tu perfil de usuario invitado y tus reglas de colaboración antes de implementar un widget externo. Prueba como usuario invitado para verificar exactamente a qué datos se puede acceder.
Herramientas recomendadas para los widgets externos
Sé conservador con las asignaciones de herramientas para los agentes de cara a invitados:
| Herramienta | ¿Recomendada? | Notas |
|---|---|---|
soql_query |
Tal vez | Solo si los invitados necesitan buscar registros públicos (p. ej., artículos de la base de conocimiento) |
get_record |
Tal vez | Si los invitados deben ver los detalles de registros públicos específicos |
count_records |
Tal vez | Útil para responder preguntas del tipo “cuántos” sobre datos públicos |
create_record |
Rara vez | Solo si los visitantes deben crear registros (p. ej., casos de soporte). Restringe a objetos específicos. |
describe_object |
No | Expone detalles del esquema — no es adecuado para usuarios externos |
send_email |
No | Riesgo de seguridad — nunca lo asignes a widgets externos |
update_record / delete_record |
No | Los invitados no deben modificar ni eliminar registros |
web_search |
Opcional | Actívalo mediante Permitir búsqueda web en la Definición de agente. Genera un costo de crédito adicional por búsqueda. |
Cómo funcionan las acciones en el widget externo
El widget externo es un canal conversacional de cara al cliente, por lo que no muestra las tarjetas de confirmación que se usan en el canal interno. En cambio, el agente ejecuta automáticamente una herramienta de acción y luego responde automáticamente con el resultado real — p. ej., “¡Gracias! He creado tu solicitud como el Caso n.º 00001234.” Si la acción falla, lo informa con honestidad. El número de turnos de seguimiento automáticos está limitado por la configuración de plataforma Max Continuation Depth (valor predeterminado: 3). Dado que el widget se ejecuta como el usuario invitado compartido del Sitio, asigna las herramientas de acción de forma deliberada y mantén ajustados los permisos de invitado. Consulta Confirmaciones de acciones → Cómo difieren las confirmaciones según el canal.
Casos de uso comunes
Los visitantes abren el chat en tu página de soporte. El agente responde preguntas frecuentes, busca artículos de conocimiento y ofrece crear un caso de soporte para problemas complejos.
Herramientas: soql_query, create_record (solo Casos)
Los prospectos en tu sitio web chatean con el agente. El agente califica al prospecto y crea un registro de Prospecto para su seguimiento.
Herramientas: soql_query, create_record (solo Prospectos)
Los inquilinos o clientes preguntan sobre propiedades, reservas o detalles de la cuenta. El agente busca en los datos públicos y proporciona respuestas.
Herramientas: soql_query, get_record
Descripción general de la apariencia del widget
El widget admite una amplia personalización mediante los atributos data-* en la etiqueta del script de inserción:
- Estilo de la burbuja — Círculo (predeterminado) o botón con forma de píldora con una etiqueta de texto
- Estilo del encabezado — Con color (fondo de marca) o minimalista (blanco/limpio)
- Portada de bienvenida — Pantalla de bienvenida con marca, con título, avatar y subtexto opcional
- Colores — Color principal, fondo del encabezado, color de los mensajes del usuario, fondo, texto y bordes
- Tipografía — Familia y tamaño de fuente personalizados
- Dimensiones — Ancho del panel, altura, tamaño de la burbuja y radio de los bordes
- Posición — Inferior derecha o inferior izquierda
- Tema — Modo claro u oscuro
- Móvil — Punto de quiebre configurable y modo de pantalla completa opcional
- Texto / i18n — Todas las etiquetas, los textos de marcador de posición, el texto ARIA y los mensajes de error son personalizables
Para conocer todos los detalles y ejemplos, consulta Personalización de la interfaz del widget.
Prácticas recomendadas
Revisa con cuidado los permisos del perfil de usuario invitado. Asegúrate de que no se exponga ningún dato sensible. Prueba el widget como invitado para verificar a qué datos se puede acceder.
Mantén las herramientas al mínimo — Asigna solo las herramientas que los invitados realmente necesitan. Cada herramienta aumenta el uso de tokens y la posible exposición de datos.
Escribe medidas de protección adecuadas — Agrega prompts de medidas de protección para restringir el comportamiento del agente. Ejemplo: “Nunca hables de precios internos. Ofrece siempre poner en contacto al usuario con ventas.”
Supervisa las conversaciones — Revisa los registros de conversaciones con regularidad para entender las preguntas de los visitantes. Usa esos conocimientos para mejorar tu base de conocimiento o ajustar el comportamiento del agente.
Prueba en varios dispositivos — Verifica que el widget funcione en computadora de escritorio, tableta y móvil antes de pasar a producción.
Preguntas frecuentes
Agregas una sola etiqueta <script> a tu página. El Cargador de REDA AI obtiene automáticamente el código del widget con invalidación de caché, aplica tu configuración a partir de los atributos data-* e inicializa el chat. No se requiere JavaScript adicional.
Sí. Agrega todos los dominios al campo Orígenes permitidos en la Definición de agente (separados por comas). Usa el mismo código de inserción en cada sitio.
La API rechazará las solicitudes de los dominios que no figuren en Orígenes permitidos. El widget no funcionará en dominios no autorizados.
Sí. Crea registros de Definición de agente separados, cada uno con su propia clave de API y sus propios orígenes permitidos. Cada sitio web recibe su propio código de inserción que apunta a la clave de API y al extremo correspondientes.
Sí. El widget se adjunta a la página una vez al cargarla y persiste a través de los cambios de ruta. Usa un Shadow DOM, por lo que no entra en conflicto con los estilos ni el JavaScript de tu aplicación.
Sí. Toda la personalización se realiza mediante atributos data-* en la etiqueta del script de inserción. No se necesitan cambios en CSS ni en JavaScript. Consulta Personalización de la interfaz del widget para ver todas las opciones.
Próximos pasos
Personaliza la apariencia de tu widget con Personalización de la interfaz del widget, o revisa Acceso a datos y permisos para proteger la configuración de tu usuario invitado.