Widgets e integración web

Preparar el widget

1. Un operador publica el widget de un agente o un enrutador activo.
2. Obtiene su publicationId desde la configuración del widget.
3. Crea una licencia de uso por usuario externo con el plan y el vencimiento apropiados.
4. Tu aplicación entrega a cada usuario únicamente la licencia que le corresponde.

La licencia de instalación también debe estar vigente. Su ausencia puede producir un 402 aunque la licencia del usuario sea correcta.

Insertar el asistente

Este ejemplo no incluye una licencia: el widget la solicitará al usuario. Reemplaza el origen y el identificador por los de tu instalación.

<iframe
  src="https://agos.example.com/widget/PUBLICATION_ID"
  title="Asistente de soporte"
  width="400"
  height="680"
  style="width:100%;max-width:400px;border:0"
  loading="lazy"
  referrerpolicy="no-referrer">
</iframe>

Tu aplicación puede construir la URL con ?license-id=... para la sesión autorizada. Codifica el valor como parámetro de URL y evita que aparezca en telemetría, capturas, logs o páginas compartidas. Nunca incrustes un JWT de administración.

Si habilitas voz, agrega allow="microphone" al iframe y usa HTTPS. Comprueba también las políticas de permisos y de contenido del sitio anfitrión y de AGOS: ambas deben permitir la integración.

Construir un chat propio

Desde tu backend, o desde un frontend servido en el mismo origen de AGOS:

1. Consulta GET /api/public/widgets/{publicationId} para obtener apariencia y disponibilidad de audio.
2. Valida la licencia con POST .../validate-license y { "licenseId": "<licencia-del-usuario>" }.
3. Envía el mensaje a POST .../chat.

{
  "message": "¿Cuál es el horario de atención?",
  "licenseId": "<licencia-del-usuario>",
  "history": [],
  "voice": false
}

La respuesta incluye text, consumo, cupo restante y videos. Por privacidad, no expone los nombres de documentos internos. Un cupo restante null indica que el plan no tiene cupo mensual configurado (monthlyInputTokenLimit = 0).

Gestionar límites y cambios

Situación	Comportamiento
Licencia de usuario inválida o vencida	401; solicita revisión o renovación
Cupo mensual agotado	429; no reintentes continuamente
Widget no publicado o inactivo	404; revisa su publicación
Rotación del publicationId	El enlace anterior deja de funcionar
Rotación de licenseId	Debes entregar la nueva clave al usuario autorizado

El consumo mensual se reinicia el día 1 en UTC. Los planes técnicos Free, Standard y Premium son valores del contrato de AGOS; no representan una oferta comercial gratuita de este sitio.

Consulta los contratos completos de widgets públicos y licencias de uso.