Inserta un widget en tu sitio

Puedes colocar el producto en tu propio sitio web con una etiqueta <script>. Hay dos widgets, y cuál elijas depende de si los visitantes deben tener una conversación o ejecutar algo específico.

	Widget de chat	Widget de flujo de trabajo
Lo que obtiene un visitante	Una conversación con un asistente	Un flujo de trabajo, con sus entradas
Formularios interactivos	Sí	No — solo muestra resultados
Script	chat-widget.js	workflow-widget.js

Ambos son autónomos: no se necesita ningún marco en tu página, ni una hoja de estilos por incluir, y nada que construir.

Agregar el widget de chat

<script src="https://app.example.com/chat-widget.js"></script>
<script>
  sapajaChat('init', {
    templateId: 'tu-id-de-plantilla',
    token: 'tu-token-de-inserción',
  });
</script>

Obtienes el id de la plantilla y su token del workspace que posee la plantilla de chat. El token es lo que autoriza el widget, y está ligado a una lista de sitios que pueden usarlo; un token usado desde un dominio que no está en esa lista es rechazado, así que un token copiado no funciona en otros lugares.

Lo que ven los visitantes

Las respuestas no son texto plano. El widget renderiza las mismas superficies ricas que el chat en la aplicación — tarjetas, tablas, estadísticas, insignias, gráficos e imágenes — así que un resultado llega como algo legible en lugar de un bloque de JSON.

El widget de chat también renderiza formularios reales. Cuando el asistente necesita detalles antes de poder ejecutar algo, el visitante recibe campos etiquetados y un botón de enviar en lugar de ser solicitado a escribir valores en una oración. Hay algunos comportamientos que vale la pena conocer:

• Un envío incompleto regresa como un formulario corregido, con los campos faltantes marcados, en lugar de un error.
• Si un envío no puede alcanzarnos, el formulario permanece editable y ofrece un reintento — nunca informa falsamente de éxito.
• Un formulario enviado permanece visible pero congelado, marcado como enviado, para que el visitante pueda ver lo que envió.

El widget de flujo de trabajo muestra resultados pero no tiene formularios; recoge lo que necesita de antemano.

El idioma de tu visitante

El widget habla el idioma del visitante, no el tuyo. Determina cuál utilizar en este orden: el idioma que configuras, luego el del navegador del visitante, y después el inglés.

sapajaChat('init', { templateId: '…', token: '…', locale: 'fr' });

Soportados: en, fr, es, th, zh y zh-HK. Las etiquetas de navegador comunes son aceptables — fr-CA se convierte en francés, zh-TW se convierte en chino tradicional. Cualquier cosa no reconocida regresa a inglés en lugar de fallar.

Esto cubre los propios controles del widget y todo lo que genera el asistente: líneas de estado, mensajes de finalización, etiquetas de tarjetas de resultado y las respuestas mismas. Se aplica por mensaje, por lo que un visitante que cambia de idioma a mitad de conversación recibe el nuevo en su siguiente mensaje. El contenido ya enviado nunca se retranslada — una tarjeta de resultado permanece en el idioma en que fue construida.

Si una conversación inicia un trabajo de larga duración, el idioma viaja con él, así que el mensaje de finalización llega en el idioma que estaba usando el visitante, incluso si eso es horas más tarde.

Una excepción: el texto escrito por quien construyó el flujo de trabajo — descripciones de campos, solicitudes de clarificación y visualizaciones personalizadas — aparece tal como fue escrito. Ese es contenido creado en lugar de copia de producto, por lo que no se traduce.

Construyendo tu propio cliente en su lugar

No tienes que usar los widgets. Los endpoints de inserción están documentados en la referencia de la API REST, y toman el mismo valor de locale en cada llamada — envíalo y obtendrás el mismo comportamiento, omítelo y recibirás inglés.

Si algo no aparece

• Sin botón de micrófono. La voz necesita una conexión segura. En una página servida a través de HTTP sin cifrado, el navegador no otorgará acceso al micrófono, por lo que el control no se mostrará. Sirve tu página a través de HTTPS.
• Un componente no se renderiza. El widget solo renderiza tipos de componentes conocidos y silenciosamente omite cualquier otro, así que una visualización que no puede entender se salta en lugar de mostrarse rota.
• El widget deja de funcionar. Si el workspace que posee la inserción ya no tiene una suscripción activa, el widget se niega educadamente en lugar de mostrar a tus visitantes un mensaje de facturación.