Problemas frecuentes del widget
Qué revisar cuando el widget de soporte no aparece, la API lo rechaza o fallan los adjuntos, con el código de error de cada caso.
Actualizado el . 4 min de lectura
Incluido en los planes Profesional y Avanzado. Ver precios
Esta página reúne los fallos más habituales al insertar el widget de soporte y cómo resolverlos. Casi todos se diagnostican igual: abre las herramientas de desarrollo del navegador, mira la consola y, en la pestaña de red, la respuesta de la petición que falla. Los errores de la API traen un campo errorCode que dice exactamente qué pasa.
¿Por qué no funciona el widget?
¿Aparece el botón flotante en la página?
No:
¿Ves en la consola un aviso que empieza por [UtiliaWidget]?
Sí:
Faltan atributos obligatorios
La etiqueta necesita data-base-url, data-api-key y data-user-id.No:
El script no carga o no arranca
Busca utilia-widget.js en la pestaña de red y revisa tu política de seguridad (CSP). Con el componente web no hay aviso: revisa base-url, api-key y user-id.
Sí:
¿Ves un error de CORS en la consola?
Sí:
Declara tu dominio
Añádelo en «Dominios autorizados» de la aplicación y espera un minuto.No:
¿Qué código responde la API?
401:
Revisa la clave
API_KEY_INVALID
Falta, no existe o se ha regenerado.403:
Lee su errorCode
INSUFFICIENT_SCOPE (falta un scope), ORIGIN_NOT_ALLOWED (dominio no autorizado) o MODULE_NOT_ENABLED (plan).429:
Límite de la clave
RATE_LIMIT_EXCEEDED
Se han superado las 1.000 peticiones por hora.
El widget no aparece
- Faltan atributos obligatorios. Con la etiqueta de script, comprueba
data-utilia-widget,data-base-url,data-api-keyydata-user-id. Si falta alguno de los tres últimos, la consola muestra un aviso que empieza por[UtiliaWidget]. Con el componente web, revisabase-url,api-keyyuser-id: sin ellos no arranca y no avisa. - El script no carga. Busca en la pestaña de red el archivo
utilia-widget.js. Si tu web tiene una política de seguridad de contenido (CSP), añade el origen del script ascript-src, o sirve el archivo desde tu propio servidor (lo tienes en el paquete npm, endist/utilia-widget.js). - El botón aparece pero no carga nada. Mira en la consola si hay errores de CORS o en la pestaña de red si hay respuestas 401, 403 o 429, y sigue los apartados siguientes.
Errores de CORS o 403 «Origen no permitido»
El widget llama a la API desde el navegador de tus usuarios, y la API solo acepta esas llamadas desde los dominios que declaras en la aplicación externa.
- Añade tu dominio en «Dominios autorizados» de la aplicación (en Ajustes › Integraciones › Aplicaciones externas, necesitas entrar con tu cuenta), con el protocolo y sin barra final:
https://www.tuempresa.com. Un asterisco vale por cualquier subdominio (https://*.tuempresa.com); un asterisco solo no se acepta. - No dejes la lista vacía. Una lista vacía deja pasar las llamadas de servidor, pero el navegador las bloquea si tu dominio no está declarado.
- Después de guardar, espera un minuto: la lista de dominios se refresca cada 60 segundos.
Si el navegador muestra un error de CORS, la petición no llega a la aplicación; si llega y el dominio no está en su lista, la respuesta es un 403 con ORIGIN_NOT_ALLOWED.
Errores 401 y 403
| Código | errorCode | Qué pasa y qué hacer |
|---|---|---|
| 401 | API_KEY_REQUIRED | La petición no lleva clave. Revisa data-api-key, api-key o apiKey. |
| 401 | API_KEY_INVALID | La clave no existe o se ha regenerado. Copia la clave vigente de la aplicación. |
| 401 | API_KEY_NOT_LINKED | La clave no pertenece a ninguna aplicación externa. Usa la que se muestra al crear la aplicación. |
| 403 | APP_DISABLED | La aplicación externa está desactivada. Actívala desde su ficha, con «Activar la aplicación». |
| 403 | INSUFFICIENT_SCOPE | A la aplicación le falta un scope. Mira cuál en la tabla de la visión general. |
| 403 | MODULE_NOT_ENABLED o CAPABILITY_NOT_ENABLED | El plan de tu organización no incluye Tickets de soporte, Integraciones o Gestor de archivos. Se resuelve ampliando el plan, no con permisos. |
Error 429: límite de peticiones
Límites del widget
- Peticiones por clave
- 1.000por hora
- Compartidas entre todas las visitas de tu web.
- Peticiones al cargar una página
- 2
- Identificar al usuario y pedir los no leídos.
- Adjuntos por ticket
- 5de hasta 10 MB
- Fijos en el widget; no se pueden cambiar.
Al superar las 1.000 peticiones por hora de la clave, la API responde 429 con RATE_LIMIT_EXCEEDED y la cabecera Retry-After, y el widget deja de cargar hasta que se cumple una hora desde la primera petición de ese periodo. Si te ocurre con frecuencia, evita inicializar el widget varias veces en la misma página y cárgalo solo en las páginas donde tus usuarios lo necesitan. Más detalle en Límites de uso y CORS.
Los adjuntos no se suben
- El widget admite hasta 5 archivos por ticket y 10 MB por archivo. Estos límites son del widget y no se pueden cambiar.
- Tipos admitidos: imágenes JPEG, PNG, GIF y WebP; PDF; documentos de Word; hojas de Excel; texto plano y CSV.
- Si la subida da 403, a la aplicación le faltan los scopes
fm:files:writeyfm:files:read, o el plan no incluye el Gestor de archivos.
El asistente con IA o la nota de voz no funcionan
- Las dos funciones necesitan el scope
support:tickets:ai, que la propuesta «Tickets y soporte» no incluye: añádelo a mano. - El botón de grabar solo aparece si el navegador permite grabar audio, y el navegador pide permiso para el micrófono la primera vez. La grabación necesita que tu web se sirva por HTTPS.
Siguiente paso
Si después de revisar esto el problema sigue, anota el valor de la cabecera x-request-id de la respuesta que falla y abre un ticket de soporte, necesitas entrar con tu cuenta con él: así se localiza tu petición. Cómo leer los errores de la API en general está en Errores, identificador de petición y reintentos.