Visión general
Existen dos integraciones diferentes entre el Centro de Ayuda y Maestro. Tienen nombres parecidos, pero un alcance y una velocidad muy distintos — confundirlas es la causa más común de "publiqué el artículo y el bot no lo sabe":
| Selección de artículos por bot | Sincronización diaria de la cuenta | |
|---|---|---|
| Qué entra | solo los artículos/categorías que marcas | todo lo publicado, en todos los portales |
| Quién lo usa | solo ese bot | todos los bots de la cuenta (base compartida) |
| Cuándo se actualiza | al instante — al guardar la selección y en cada edición/publicación del artículo | una vez al día, automáticamente |
| Dónde se configura | pestaña de conocimiento en la configuración del bot | nada que configurar: es automático |
La primera siempre funcionó al instante. La segunda — la que lleva todo el portal a la base compartida de la cuenta — no tenía disparador automático: solo se ejecutaba si un administrador de la instalación la lanzaba a mano. A partir de esta versión se ejecuta sola, todos los días.
Cada artículo publicado se convierte en un documento de la base de la cuenta, en la ruta
help-center/{portal}/{categoría}/{artículo} — así el bot responde con el contenido oficial y
puede citar de qué artículo salió la respuesta. Los artículos sin categoría quedan en
uncategorized.
Requisitos previos
- Una cuenta con Maestro habilitado y al menos un bot activo. El barrido diario ignora las cuentas sin ningún bot activo — no habría a quién entregarle el conocimiento.
- Un portal del Centro de Ayuda con artículos en estado publicado.
- Un proveedor de embeddings con clave y créditos válidos — es la misma indexación que usa la base de conocimiento del Cerebro de la Cuenta.
- La sincronización debe estar habilitada en la instalación (una llave de despliegue bajo el control del administrador de la instalación). Si está apagada, ninguna cuenta sincroniza.
Paso a paso
- Escribe y publica tus artículos en el portal, como siempre. Los borradores y los archivados no cuentan.
- No hagas nada más. El barrido se ejecuta automáticamente todos los días a las 05:10 UTC (02:10 en la hora de Brasilia). No se dispara cuando el servicio se reinicia: espera el horario.
- Al día siguiente, confirma: pregúntale al bot algo que solo exista en ese artículo. La
respuesta debe traer el contenido publicado y apuntar a su origen en
help-center/…. - ¿Necesitas que valga ahora, sin esperar al día siguiente? Dos salidas:
- marca el artículo (o la categoría entera) en la pestaña de conocimiento del bot — esa selección vale al instante y se mantiene sincronizada en cada edición;
- o pídele a un administrador de la instalación que dispare la sincronización de la cuenta bajo demanda.
Configuración y opciones
- Cadencia diaria, a las 05:10 UTC. El horario quebrado es deliberado: las demás rutinas automáticas de Maestro se ejecutan en horas en punto, y el mapeo de la estructura del Cerebro corre 55 minutos antes — así la lectura de los artículos nunca compite con la rutina anterior por la misma cuenta.
- Alcance: todos los portales de la cuenta, todos los artículos publicados. La categoría se convierte en una "carpeta" dentro de la ruta del documento.
- Contenido indexado: el título más el cuerpo del artículo. Los subtítulos (
##,###) guían el corte en fragmentos — cada fragmento lleva la sección de la que salió, lo que mejora la cita. - Solo lectura: la sincronización nunca edita, publica, despublica ni borra un artículo. Solo lee el portal y escribe en la base de Maestro.
- Una ejecución por cuenta, por día: si la sincronización del día anterior sigue corriendo cuando empieza la siguiente, la nueva se descarta. Nunca hay dos escribiendo en la misma base a la vez.
- Sustitución atómica: el contenido se indexa antes de tocar la base, y el cambio ocurre en una única transacción. Un fallo a mitad de camino nunca vacía lo que ya estaba indexado.
- Aislamiento de errores: un artículo, una página o un portal con problemas se contabiliza y el barrido continúa con el resto — un elemento defectuoso no hunde toda la sincronización.
- Guarda de paginación: la lectura de cada portal está limitada y se detiene sola cuando los artículos empiezan a repetirse, evitando una lectura infinita.
Casos de uso
- Lograr que el bot responda con la política oficial ya publicada, citando el artículo, en vez de una versión pegada a mano y desactualizada.
- Mantener una única fuente de verdad: el equipo edita en el portal y todos los bots lo heredan.
- Cuentas con muchos artículos: aprovechar todo el portal sin marcar elemento por elemento.
- Los bots nuevos ya nacen sabiendo — la base es de la cuenta, no de un bot en particular.
- Portales trilingües: todo lo publicado en cada idioma entra en la base.
Consejos, límites y buenas prácticas
- Los borradores y los archivados no entran. Un artículo con el cuerpo vacío también se ignora (y se conserva lo que ya estaba indexado).
- Despublicar no quita el artículo de la base compartida en el barrido diario: agrega y actualiza, no borra documentos de artículos que salieron del aire. Si un contenido debe desaparecer de las respuestas de inmediato, usa la selección por bot (que lo quita al despublicar) o pide a un administrador que elimine esa fuente.
- Costo: cada ejecución vuelve a indexar los artículos publicados, e indexar cuesta dinero por cuenta. Por eso la cadencia es diaria: es el menor costo estable que mantiene el desfase dentro de 24 horas. Ejecutarlo cada hora multiplicaría ese costo por 24 para observar un contenido que casi nunca cambia de hora en hora.
- Una ventana de hasta 24 horas: los cambios urgentes deben ir por la selección por bot, que vale al instante.
- Un buen artículo hace una buena respuesta: títulos claros, secciones bien divididas y contenido actualizado generan mejores citas. El contenido viejo genera respuestas viejas.
Solución de problemas
- "Publiqué ayer y el bot no lo sabe": confirma que el artículo esté publicado, que la cuenta tenga al menos un bot activo y que el proveedor de embeddings tenga créditos. Si el artículo se publicó después de las 05:10 UTC, solo entra en el barrido siguiente.
- "No sincroniza nada, en ninguna cuenta": lo más probable es que la sincronización esté apagada en la instalación. Habla con el administrador de la instalación.
- "Sincronizó, pero el bot no lo usa": el bot debe estar autorizado a consultar la base de conocimiento. Revisa las herramientas habilitadas para él.
- "Un artículo viejo sigue apareciendo en las respuestas": es el límite descrito arriba — despublicar no lo borra de la base compartida. Usa la selección por bot o pide la eliminación de la fuente.
- "No se pudo indexar" / embeddings no disponibles: ningún proveedor de embeddings tiene clave y créditos válidos. Verifica los créditos del proveedor primario o conecta una clave alternativa en Integraciones — es la misma causa (y la misma solución) que en la base de conocimiento.