Solución de problemas

#El widget no aparece en mi sitio

1. Abre las DevTools del navegador y busca una solicitud a widget.customerhero.app/v1/loader.js. Si está bloqueada, tu Content Security Policy está rechazando el script: revisa la sección de CSP en la guía del Widget.
2. Comprueba que el script tenga el data-chatbot-id correcto y un data-api-base que coincida con la región de tu org (US o EU).
3. Confirma que el chatbot está publicado: los chatbots en borrador no exponen widget.
4. Si el loader devuelve 200 pero no aparece la burbuja, descarta bloqueadores de anuncios y extensiones anti-tracking: a veces bloquean widgets de chat aunque la CSP esté bien.

#El widget carga pero todos los mensajes fallan

La causa más común es un data-api-base desalineado. Un chatbot de la región UE solo habla con eu.api.customerhero.app; enviar solicitudes al host de US devuelve 404. Copia el snippet directamente desde Chatbot → Embed: siempre lleva el host correcto.

#Una fuente de datos se ingestó pero el bot no la conoce

1. Abre el detalle de la fuente y confirma que el Estado es Listo, no Procesando ni Fallido. Las fuentes fallidas suelen mostrar el error en la fila.
2. Mira el número de fragmentos. Si un PDF de 50 páginas produjo 0 fragmentos, probablemente el parser no pudo extraer texto (los PDFs escaneados sin OCR son la causa típica).
3. Prueba la pregunta en Chatbot → Probar y haz clic en cualquier fragmento citado para confirmar que la recuperación lo encuentra. Si no se cita ninguno, baja minScore o sube topK en el ajuste de recuperación.
4. Para fuentes URL, confirma que la página es accesible públicamente. Muros de login, geo-bloqueos y protecciones anti-bot agresivas (p. ej. el "I'm under attack" de Cloudflare) provocan ingestiones vacías.

#El bot inventa respuestas

• Cambia el perfil a Preciso. Indica al modelo que rechace en lugar de improvisar cuando la recuperación no devuelve nada útil.
• Añade una regla de rechazo explícita al prompt del sistema: "Si la respuesta no está en el contexto provisto, di que no lo sabes y ofrece conectar con un humano."
• Sube minScore en el ajuste de recuperación para que las coincidencias débiles no entren al contexto.
• Revisa la pestaña de analíticas en busca de conversaciones con baja confianza: ahí suele improvisar el bot. Añade fuentes Q&A para tapar esos huecos.

#Los webhooks no se entregan

1. Abre Ajustes → Webhooks → Actividad. Muestra el código de respuesta y el cuerpo de las últimas 1.000 entregas; suele bastar para ver si tu endpoint devolvió 5xx o tu firewall cerró la conexión.
2. Verifica que tu endpoint termine en menos de 10 segundos. Los handlers largos que se bloquean en escrituras a base de datos son la causa más común de timeouts.
3. Si la verificación de firma falla, comprueba que estás usando el cuerpo crudo de la solicitud, no un JSON re-serializado: una sola diferencia de espacios rompe el HMAC.
4. Usa el botón Reenviar en una entrega fallida para reintentarla sin esperar al ciclo automático.

#Las llamadas a la API devuelven 401 sin esperarlo

• Confirma que la clave no ha sido revocada. El log de auditoría muestra cada revocación y el usuario que la hizo.
• Comprueba el host. Una clave de la región US no se autentica contra eu.api.customerhero.app ni viceversa.
• Asegúrate de que la cabecera sea exactamente Authorization: Bearer sk_live_… con un único espacio después de Bearer. Algunos clientes descartan la cabecera silenciosamente si está mal formada.

#Las llamadas a la API devuelven 403 sin esperarlo

Un 403 significa que la autenticación fue correcta pero te falta el rol (admin frente a agente) o el permiso (clave de API) para esa operación. El campo error de la respuesta indica exactamente qué scope falta: añádelo a tu clave en Ajustes → Claves de API y vuelve a intentarlo. La lista completa está en la guía de Claves de API.

#Las llamadas a la API devuelven 402

Has llegado a un límite del plan o te has quedado sin créditos. La respuesta incluye un campo code estable que dice qué límite. Resuélvelo en Ajustes → Facturación: la lista completa de códigos está en Planes, límites y créditos.