Referencia
Solución de problemas y FAQ
Problemas comunes y cómo resolverlos, agrupados por tipo de usuario. Cada entrada ofrece una solución práctica y enlaza a la documentación detallada cuando necesite más información. Reemplace los marcadores en MAYÚSCULAS por sus propios valores. El dominio de producción es helpstack.eu.
Agentes y administradores#
Un compañero de equipo no puede ver Configuración ni cambiar la configuración
Su rol probablemente es AGENT o VIEWER. Los agentes tienen acceso de solo lectura a la configuración, y los viewers son de solo lectura en conversaciones y analítica. Pida a un OWNER o ADMIN que cambie su rol. Consulte ../guides/09-team-and-roles.md.
No recibo notificaciones sobre nuevas conversaciones
Verifique su configuración de notificaciones para el evento (NEW_CONVERSATION / NEW_MESSAGE / ASSIGNED / STATUS_CHANGED) y el canal (IN_APP, EMAIL, PUSH, etc.). Si el ámbito es ASSIGNED_ONLY, solo recibirá alertas de conversaciones asignadas a usted — cambie a ALL para ser notificado de todo. Consulte ../guides/10-notifications.md.
Una conversación desapareció de mi bandeja de entrada
Verifique su estado. Las conversaciones pasan de OPEN → PENDING → CLOSED, y su filtro de bandeja de entrada puede estar ocultando los hilos CLOSED (o PENDING). Borre o amplíe el filtro de estado. Consulte ../guides/02-conversations.md.
Mi nota interna fue enviada al cliente
Las notas internas son privadas para su equipo y nunca se entregan al cliente — si el cliente recibió texto, fue añadido como respuesta OUTBOUND, no como nota. Asegúrese de usar el campo de nota, no el cuadro de respuesta. Consulte ../guides/02-conversations.md.
IA y base de conocimiento#
Las respuestas de IA son genéricas, vagas o incorrectas
Dos cosas fundamentan la IA: un prompt de sistema y conocimiento. Primero, escriba un prompt de sistema claro por canal que establezca la persona, el tono y las reglas. Segundo, adjunte los grupos de base de conocimiento relevantes al canal para que las respuestas se fundamenten en su propio contenido mediante RAG. Sin grupos de KB adjuntos, el modelo solo dispone de conocimiento general. Consulte ../guides/03-ai-replies.md y ../guides/05-knowledge-base.md.
No hay ninguna opción de respuesta de IA en ningún lugar
Necesita al menos un proveedor de IA configurado (OpenAI, Anthropic, Azure OpenAI u Ollama) con un modelo establecido, y un proveedor marcado como predeterminado de la organización. Añada un proveedor en la configuración y luego márquelo como predeterminado. Consulte ../guides/03-ai-replies.md.
Un artículo de la base de conocimiento está atascado o muestra un error
Los artículos pasan de PROCESSING → READY/ERROR. Si un artículo permanece en PROCESSING, espere a que termine el rastreo/subida; si muestra ERROR, la URL de origen puede no ser accesible o el archivo subido no estar admitido — vuelva a añadirlo con una fuente válida. Solo los artículos en estado READY se usan para RAG. Consulte ../guides/05-knowledge-base.md.
La IA ignora mi base de conocimiento
Confirme que el grupo de base de conocimiento que contiene esos artículos esté efectivamente adjunto al canal que gestiona la conversación, y que los artículos estén en estado READY (no PROCESSING/ERROR). El fundamento de la KB es por canal mediante grupos adjuntos. Consulte ../guides/05-knowledge-base.md.
Los chips de FAQ no aparecen en el widget, pero la KB se ve bien
Las FAQs y la base de conocimiento son funcionalidades diferentes. Las FAQs (Pregunta ≤280 caracteres, Respuesta ≤2000 caracteres) generan los chips en el saludo del widget y deben definirse a nivel de organización o en ese canal WEBSITE_CHAT. La base de conocimiento fundamenta las respuestas de IA y no crea chips de saludo. Consulte ../guides/06-faqs.md.
Los borradores nunca se envían solos
El modo de respuesta automática del canal probablemente es off o prepare. prepare redacta una respuesta pero espera a que un agente la apruebe; solo auto-approve envía sin revisión. Establezca el modo en auto-approve si quiere envío sin intervención. Consulte ../guides/03-ai-replies.md.
Canales y mensajería#
Los mensajes de Facebook no llegan
Siga estos pasos en orden:
- Discrepancia en el token de verificación — el token en su aplicación de Facebook debe coincidir exactamente con
FACEBOOK_VERIFY_TOKEN, o el challenge de verificación falla y el webhook nunca se suscribe. - Fallo de firma —
FACEBOOK_APP_SECRETdebe estar configurado correctamente para que HelpStack pueda validar la firma HMAC en los payloads entrantes; un secreto incorrecto rechaza silenciosamente los eventos. - Suscripción de página — confirme que la página de Facebook está suscrita al webhook de su aplicación con los campos de mensajería habilitados.
Consulte ../integrations/webhooks.md.
Los mensajes de Instagram o WhatsApp no llegan
Misma lista de verificación que Facebook, usando las variables de entorno correspondientes: INSTAGRAM_VERIFY_TOKEN para Instagram y WHATSAPP_VERIFY_TOKEN para WhatsApp. Confirme que el token de verificación coincide, que la firma/secreto es correcta y que la cuenta/número está suscrito al webhook. Consulte ../integrations/webhooks.md.
No encuentro una opción de canal de Telegram
TELEGRAM existe en el esquema pero aún no está disponible en la interfaz. Use EMAIL, FACEBOOK, INSTAGRAM, WHATSAPP o WEBSITE_CHAT. Consulte ../guides/04-channels.md.
Widget web#
El widget no aparece en mi sitio
Compruebe, en orden:
- CHANNEL_ID — el
iden la URL del script debe ser el ID de su canalWEBSITE_CHAT:<script src="https://helpstack.eu/widget.js?id=CHANNEL_ID" async></script>. - Lista de dominios permitidos — el dominio del sitio debe estar permitido para ese canal.
- Ubicación del script — asegúrese de que el fragmento esté presente en el HTML servido (no eliminado por un gestor de etiquetas o CSP) y que se cargue.
Consulte ../integrations/widget-embed.md.
¿Cómo abro o cierro el widget desde mi propio botón?
Use la API programática: window.ChatWidget.open(), .close(), .toggle() e .init(). Conéctelos al manejador de clic de su botón. Consulte ../integrations/widget-embed.md.
Los visitantes que regresan no son reconocidos
El widget almacena un visitorId en el localStorage del navegador. Si los visitantes borran el almacenamiento, usan el modo privado/incógnito o cambian de navegador/dispositivo, obtienen una nueva identidad. Consulte ../integrations/widget-embed.md.
¿Puedo registrar una herramienta JavaScript personalizada en el widget?
No. No existe una API de registro de herramientas JS en el widget. Las herramientas de agente del lado del cliente se definen en HelpStack como herramientas de agente CLIENT_SIDE y se ejecutan en el navegador del visitante a través del widget. Consulte ../guides/08-agent-tools.md y la referencia técnica en ../integrations/custom-agent-tools.md.
Webhooks e integraciones#
La verificación del webhook sigue fallando
El proveedor envía un challenge durante la configuración que debe devolver su token de verificación. Asegúrese de que el token configurado en el proveedor coincida exactamente con la variable de entorno correspondiente (FACEBOOK_VERIFY_TOKEN, INSTAGRAM_VERIFY_TOKEN, WHATSAPP_VERIFY_TOKEN). Consulte ../integrations/webhooks.md.
Los eventos de webhook entrantes son rechazados como no autorizados
HelpStack verifica una firma HMAC en los payloads entrantes. Confirme que el secreto de la aplicación (p. ej. FACEBOOK_APP_SECRET) esté configurado correctamente y que ningún proxy reescriba el cuerpo raw de la solicitud antes de que HelpStack lo lea — las verificaciones de firma se ejecutan sobre los bytes exactos recibidos. Consulte ../integrations/webhooks.md.
¿Hay una clave de API que pueda usar para llamar a la API?
No. No existe un sistema externo de clave de API. El panel y la API usan autenticación de sesión NextAuth limitada a su organización. Los endpoints de widget y webhook son públicos pero con límite de tasa y verificación de firma. Consulte ../integrations/api-reference.md.
La IA nunca llama a una herramienta de agente
El modelo decide si llamar a una herramienta basándose en su descripción. Reescriba la descripción para indicar claramente qué hace la herramienta y cuándo usarla, y asegúrese de que los parámetros del JSON Schema sean correctos. Las llamadas se registran, así que compruebe el registro de llamadas de la herramienta para ver si fue intentada. Consulte ../guides/08-agent-tools.md para la visión general y ../integrations/custom-agent-tools.md para los detalles de endpoint, esquema y tiempo de espera.
Canal de email#
Los emails no se están importando
Compruebe, en orden:
- Credenciales IMAP — el host del buzón, puerto, nombre de usuario y contraseña/contraseña de aplicación deben ser correctos y la cuenta debe permitir acceso IMAP.
- Buzón dedicado o indicador — use un buzón dedicado (o el indicador configurado) para que HelpStack sepa qué mensajes obtener y no compita con otro cliente.
EMAIL_MAX_AGE_DAYS— los mensajes más antiguos que esta ventana se omiten; auméntelo si espera que se importen emails más antiguos.
Consulte ../guides/04-channels.md.
El email saliente no se está entregando
El correo saliente del sistema depende de los ajustes SMTP_*. Confirme que el host, puerto y credenciales SMTP son válidos y que su dominio de envío tiene permiso para retransmitir. Consulte ../guides/04-channels.md.
Facturación y tokens#
No puedo cambiar el plan, comprar una recarga ni abrir facturación
Las acciones de facturación son exclusivas del OWNER. Pida al propietario de la organización que gestione el plan o compre una recarga a través del portal de clientes de Stripe. Consulte ../guides/12-billing.md.
Me estoy quedando sin tokens
El uso se mide en tokens. Suba de plan (Free / Starter / Growth / Enterprise) o compre una recarga única. Ambas opciones las realiza un OWNER a través del portal de clientes de Stripe. Consulte ../guides/12-billing.md.
Traducción#
Las traducciones se ven mal en mensajes cortos
Los mensajes cortos (menos de 6 palabras) heredan el idioma de la conversación en lugar de detectarse de forma independiente, lo que puede etiquetar incorrectamente una respuesta breve como "ok" o "gracias". Establezca un idioma de reserva/esperado para la conversación para que los mensajes cortos se resuelvan correctamente. Consulte ../guides/02-conversations.md.
Notificaciones#
Las notificaciones push no funcionan en mi iPhone
En iOS, el push web requiere que el sitio esté añadido a la pantalla de inicio (instalado como PWA) y se use a través de Safari — el push no se activará desde una pestaña normal de Safari. Añada HelpStack a su pantalla de inicio, ábralo desde allí y permita las notificaciones. Consulte ../guides/10-notifications.md.