Contexto desde API (JSON)

Trae catálogos y datos de tus sistemas a la base de conocimiento del bot y mantén el RAG actualizado.

Qué es

En Configurar bot → Contexto puedes conectar una API REST que devuelve JSON. EasyChatBot guarda el contenido en contextos persistentes, genera embeddings y lo usa en búsquedas RAG.

Esta función usa la misma capacidad de cuenta que API Connect en intenciones. Si no la tienes activa, contacta soporte.

Por defecto el contenido se guarda como Markdown legible (títulos y listas), igual que el resto del contexto del bot. Puedes usar una plantilla si tu API tiene campos en sitios distintos.

Formas típicas de respuesta JSON

1. Lista en la raíz

[{"id":1,"title":"..."},{"id":2,"title":"..."}]

En el modal elige Lista en la raíz. Deja vacía la ruta al array. Modo recomendado: Aplanar en un contexto (un solo bloque con todos los ítems separados por ---) o Un contexto por ítem (cada producto en su fila; necesitas item_id_path = id).

2. Objeto envuelto

{"products": [{"id":1,"title":"..."}], "meta": {"page": 1}}

Elige Lista dentro de un campo y escribe products en la ruta al array. Los metadatos fuera del array no se importan salvo que los incluyas en una plantilla apuntando a la raíz (modo avanzado).

3. Un solo objeto

{"name":"Mi empresa","hours":"9-18"}

Elige Un solo objeto. Se crea un único contexto con Markdown o plantilla.

Campos anidados y tags desde el JSON

Las APIs no comparten el mismo esquema. Ejemplos:

  • Campo de texto en category → en opciones avanzadas, campo JSON para tags = category (crea un tag de búsqueda, no una categoría del bot).
  • Valor anidado {"category":{"name":"Ropa"}} → plantilla {{category.name}} o campo para tags = category.name.
  • Valoración rating.rate → en plantilla: Nota: {{rating.rate}}.
  • Si no hay campo útil en cada ítem, usa tags por defecto (ej. catalogo).

Aplanar vs un contexto por ítem

En el paso principal Modo lista (justo después de la forma del JSON) eliges cómo se materializa la lista en tu bot. Por defecto usamos aplanar. El texto guardado suele ser Markdown o plantilla, no JSON crudo, salvo que elijas «JSON crudo» en «Texto para el bot».

  • Aplanar en un contexto — Un solo contexto con todos los ítems separados por una línea --- entre ítem e ítem (no entre campos del mismo producto). Los encabezados ## del bloque «Texto para el bot», si los activas, aplican a cada campo dentro del ítem, no a contextos distintos. Una entrada en la lista de contexto, un bloque grande en búsqueda. Recomendado para catálogos que quieres consultar como un todo.
  • Un contexto por ítem — Hasta el máximo de ítems configurado, cada producto o fila genera su propio contexto. La fila “fuente” de la API no se usa en RAG; solo los hijos. Útil cuando cada ítem debe verse, filtrarse o mantenerse por separado.
  • Objeto único — Solo el primer ítem (o un objeto sin lista). No es «un JSON y ya»: es el contenido derivado de ese ítem con el modo de texto elegido.

Si dudas entre aplanar y dividir: empieza por aplanar salvo que necesites cientos de contextos independientes.

Tags vs categorías de contexto

Tags son etiquetas ligeras tomadas del JSON (y opcionalmente tags fijos como catalogo). Ayudan a filtrar y enriquecer metadatos de búsqueda; no definen la estructura de tu sitio en el bot.

Categorías de contexto son la taxonomía que tú creas en Configurar bot → Categorías de contexto (opcional) (Nueva categoría). Cada categoría tiene un ID visible en el árbol. En la fuente API puedes vincular una categoría por defecto; antes debes haberla creado en ese acordeón.

La asignación fina de qué página o contexto pertenece a qué categoría (por URL, varios contextos a la vez) se gestiona desde el mismo bloque de categorías. Ese flujo se irá ampliando; en la fuente API solo fijas el vínculo inicial de la importación.

Plantilla personalizada

Cada línea de la plantilla es texto libre con marcadores {{campo}} (rutas con punto permitidas):

{{title}}
Precio: {{price}}
{{description}}
Categoría: {{category}}

Úsala cuando el Markdown automático no refleje bien tu negocio o cuando quieras omitir campos (por ejemplo URLs de imagen muy largas).

Caché y aviso de cambios

Configura un TTL en opciones avanzadas (desde 1 minuto hasta meses). Mientras no expire, el sync por TTL no vuelve a llamar a tu API; usa «Sincronizar ahora» si necesitas forzar. Cuando tu sistema actualice datos, envía una petición firmada a la URL de notificación (cabeceras X-ECB-Timestamp y X-ECB-Signature).

Propiedades a incluir en el texto (filtro y arrays)

En metadatos avanzados y en los campos de detalle (API genérica o Wix Get Product) puedes limitar qué partes del JSON de cada ítem se convierten en texto del contexto. Escribe rutas separadas por comas o saltos de línea. Usa punto para anidar: meta.stock, url.url.

Vacío = se incluye todo el objeto y se aplana a líneas legibles (p. ej. variants.0.price: 10, variants.1.price: 12).

Arrays de objetos: para leer el mismo subcampo en cada elemento, usa un comodín en el segmento del array. Las dos formas son equivalentes:

  • items.*.name — propiedad name de cada ítem en el array items
  • items[].price — propiedad price de cada ítem (mismo comportamiento que items.*.price)

Sin comodín, una ruta como items.price no recorre el array (el motor solo sigue objetos, no listas). Si indicas solo el array (items), se incluye el array entero y se aplanan todos sus subcampos.

Un índice numérico (items.0.name, choices.0.optionChoiceNames.choiceName) lee solo ese elemento: 0 es el primero. .* o [] recorren todos. Si un bloque tiene varios textos y la ruta pide .0, el resto de ese bloque no entra.

Ejemplo genérico (detalle por ítem):

title, description, items.*.sku, items[].stock

Ejemplo Wix (Get Product):

name, plainDescription, variantsInfo.variants.*.price, variantsInfo.variants[].name

Estos filtros no cambian lo que devuelve tu API o Wix; solo el texto que EasyChatBot guarda e indexa en RAG. Con Wix Get Product, la plataforma pide por defecto todos los bloques fields permitidos; tú recortas con «Propiedades del producto a incluir en el texto».

Solo valores en el texto: activa «En el texto del contexto, mostrar solo valores (sin nombre: delante)» en «Texto para el bot» → «Formato del texto generado». El markdown deja de usar líneas campo: valor y guarda solo el valor (útil para catálogos más limpios en RAG). No se combina con «usar solo el último nombre de la ruta».

Acortar nombre de la ruta: en el mismo bloque puedes mostrar solo los últimos segmentos del nombre (campo numérico «Últimos segmentos»: 1 → a.b.titulo como titulo; 2 → b.titulo). Nombres como título: si se muestra el nombre del campo, puedes usar un encabezado ## con el valor debajo (como las secciones Wix).

Orden del JSON (recomendado, activado por defecto): con formato markdown y una lista de rutas include, EasyChatBot recorre el producto en el mismo orden que en el JSON (cada variante con su precio seguido, secciones Wix infoSections como ## título + texto). Desactívalo solo si necesitas el orden antiguo (agrupado por patrón de ruta en la lista de propiedades).

Tags con peso desde el detalle: con Get Product (Wix), GET detalle (Woo) o detalle genérico activo, en la tabla «Propiedades como tags de búsqueda» marca rutas del JSON que deben convertirse en etiquetas de búsqueda con peso de 1 a 5. Los valores siguen en el texto del contexto; las etiquetas ayudan a priorizar resultados en búsqueda. Puedes cargar rutas desde el listado de propiedades de arriba. El campo «Campo JSON para tags» en metadatos sigue aplicando al listado o a tags globales.

API JSON genérica — detalle por ítem

Con Tipo de fuente → API JSON genérica y modo un contexto por ítem, puedes activar Traer detalle por ítem (GET con URL por ID). Tras obtener la lista con tu URL principal, EasyChatBot hace un GET por fila usando una plantilla como https://tu-api.com/items/{{id}}, donde {{id}} se sustituye por el valor del campo que definas en ID del ítem (item_id_path, por defecto id).

El objeto del listado se reemplaza por la respuesta del detalle: si el JSON raíz es el ítem, deja vacía «Ruta al objeto en la respuesta»; si viene envuelto (ej. {"data":{...}}), indica data. Si un GET falla, se conserva el resumen del listado. Las mismas cabeceras de la fuente se envían en cada detalle. En la misma sección, Propiedades del detalle a incluir en el texto filtra el JSON del GET (ver sección anterior sobre variable.*.campo y variable[].campo). Las «Propiedades a incluir por ítem» de metadatos avanzados siguen aplicando al listado cuando el detalle está desactivado. En Probar ahora solo se enriquecen los primeros ítems de la vista previa; la sincronización aplica el detalle a todos hasta el máximo configurado.

Wix Stores (catálogo de productos)

En el modal elige Tipo de fuente → Wix Stores – productos (v3). Necesitas una app headless en Wix con Client ID y Client secret (OAuth client credentials) y el permiso PRODUCT_READ.

En el paso 2. Probar la API validas credenciales y ves cuántos productos se obtendrían. EasyChatBot pide un token a Wix y consulta el catálogo con paginación automática (hasta 100 productos por página) hasta el máximo de ítems que configures (por defecto 200, máximo 500).

La respuesta se trata como lista en el campo products. Modo recomendado: un contexto por ítem con item_id_path = id. No hace falta escribir la URL de la API de Wix: el conector la resuelve por ti.

Filtro del listado (Query Products): en JSON opcional puedes enviar el fragmento que Wix acepta en query, por ejemplo {"filter":{"visible":true}} o la forma corta {"visible":true} (EasyChatBot la normaliza al guardar). Eso filtra productos visibles en el catálogo, no las tallas dentro de cada producto. Solo funcionan campos que Wix declare filtrables en su documentación. La paginación la sigue gestionando EasyChatBot.

Filtros de variantes en el texto (con Get Product activo), ambos activados por defecto e independientes del Query Products:

  • Solo variantes visibles — quita filas con variantsInfo.variants[].visible: false.
  • Excluir variantes sin stock — quita filas con variantsInfo.variants[].inventoryStatus.inStock: false (suele coincidir con tallas deshabilitadas en el selector de la tienda cuando visible sigue en true). También recorta options[].choicesSettings.choices si incluyes rutas options.*.

Desactiva uno u otro si necesitas el JSON completo en el contexto (auditoría).

Condiciones del producto: reglas sobre el JSON de cada ítem (tras listado y, si aplica, Get Product). Solo se importan productos que cumplan todas las reglas (ej. ruta visible, operador «igual», valor true). Útil si un campo solo aparece en el detalle.

Opcionalmente puedes activar Traer detalle completo por producto (Get Product): tras el listado, EasyChatBot llama a la API Get Product de Wix por cada ítem (hasta el máximo de ítems) y sustituye el resumen del listado por el producto completo. Get Product pide por defecto todos los bloques fields soportados por Wix; tú eliges qué entra al texto con Propiedades del producto a incluir en el texto (rutas con punto; para arrays usa variantsInfo.variants.*.price o variantsInfo.variants[].name; vacío = todo el producto). Las «Propiedades a incluir por ítem» de metadatos avanzados siguen aplicando al listado Query cuando Get Product está desactivado. Es más lento (una petición GET por producto). En Probar ahora, con Get Product activo, la vista previa muestra hasta 5 productos al azar (texto para el bot y JSON de detalle por muestra); en la prueba solo se enriquecen los primeros ~5 con Get Product; la sincronización aplica el detalle a todos dentro del límite. Al abrir un contexto hijo, el aviso «Origen del texto» refleja la última sincronización (wix_detail vs solo listado); si cambias el conector, vuelve a sincronizar la fuente.

En Extraer categorías desde API (ajustes de categorías de contexto) también puedes usar Wix Stores – colecciones con las mismas credenciales OAuth.

Wix Bookings (servicios)

En el modal elige Tipo de fuente → Wix Bookings – servicios. Usa las mismas credenciales OAuth (Client ID y secret) de tu app headless instalada en el sitio. Permisos recomendados: lectura de servicios (READ-BOOKINGS-PUBLIC) y, si activas huecos, calendario (READ-CALENDAR).

EasyChatBot lista servicios con Query Services (campo services en la respuesta). Modo recomendado: un contexto por ítem con item_id_path = id y title_path = name. Puedes enviar un filtro JSON opcional (por defecto se excluyen servicios ocultos).

Opcional: Traer disponibilidad (huecos Time Slots). Solo aplica a servicios de tipo APPOINTMENT (citas 1:1). Debes indicar una zona horaria IANA (ej. America/Bogota) y el horizonte en días (1–365, por defecto 90). Los huecos resumidos se guardan en el JSON del servicio bajo _ecb_bookings.slots_summary para que el RAG pueda responder sobre fechas disponibles. Clases (CLASS) y cursos (COURSE) no se enriquecen en esta versión.

EasyChatBot no crea reservas en Wix ni sustituye la intención de calendario con Google Calendar del producto.

Wix: páginas, blog, reservas y otras APIs

EasyChatBot conecta por API el catálogo de productos, los servicios de Bookings y las colecciones de Wix Stores. El resto del sitio (páginas del editor, blog, etc.) suele entrar con extracción web en Contexto, salvo que uses una API genérica.

Las APIs oficiales de Wix usan la misma idea que ya conoces: app headless en el panel de Wix, Client ID y Client secret, instalar la app en el sitio y declarar los permisos (scopes) que pida cada API. Documentación general: referencia de APIs Wix.

¿Puedo traer las páginas del sitio sin extraer URLs?

No hay un conector en EasyChatBot que exporte el HTML completo de cada página del editor Wix. En la documentación de Wix tampoco aparece un endpoint público del tipo «dame el contenido de la página por ID» para sustituir al 100 % la extracción web.

Lo más cercano sin rastrear el sitio:

  • Búsqueda del sitio (Site Search) — documentos con tipo SITE_PAGES: título, URL y texto que Wix indexa para búsqueda (no todo lo que ves en el lienzo). Requiere la app Wix Site Search en el sitio y permisos de lectura. Introducción Site Search.
  • Estructura del sitio — listado de páginas con metadatos (nombre, URL, SEO, si está oculta o con contraseña): útil para inventario y enlaces, no para el cuerpo de la página.
  • Blog — entradas publicadas con texto (CONTENT_TEXT, RICH_CONTENT) vía la API de posts. Listar posts.
  • Colecciones del Content Manager (CMS) — ítems de colecciones que tú defines en Wix (wix-data), con el contenido guardado en cada fila. Consultar ítems.

Estrategia habitual: combinar API donde el copy vive en blog o CMS, Site Search para páginas indexadas, y extracción web solo para huecos (páginas sin SEO, apps embebidas, contenido solo en el editor).

Si tu sitio expone datos propios, Wix permite HTTP Functions (Velo) como API a medida; en EasyChatBot puedes consumirlas con API JSON genérica en el modal de contexto.

¿Wix tiene reservas (Bookings) como WooCommerce Bookings?

Sí, Wix Bookings tiene APIs REST (servicios, disponibilidad, crear reservas, etc.). Introducción Wix Bookings. En la búsqueda del sitio también existen documentos BOOKING_SERVICES (metadatos buscables, no sustituyen consultar huecos).

Para servicios y huecos de citas 1:1 usa el conector Wix Bookings – servicios (sección anterior). En WooCommerce, si usas el plugin Bookings, el conector de productos puede opcionalmente enriquecer productos type=booking con disponibilidad resumida para el RAG (ver sección WooCommerce más abajo).

Para agendar citas en el chat, EasyChatBot ofrece la intención de calendario con Google Calendar cuando tu cuenta lo incluye; conectar reservas Wix de extremo a extremo sería un desarrollo aparte (permisos, pagos, formularios de reserva).

Otras APIs útiles para contexto (referencia Wix)

  • Eventos, foro, galería, restaurantes, programas online — muchas aparecen como tipos de documento en Site Search (EVENTS, FORUM_CONTENT, PROGALLERY_ITEM, RESTAURANTS_ITEMS, ONLINE_PROGRAMS).
  • Tienda — además del conector de productos, STORES_PRODUCTS en Site Search es otra vía de metadatos (no duplica Get Product).

Los conectores dedicados de EasyChatBot para blog, páginas o CMS en Wix pueden incorporarse en versiones futuras; si los necesitas con prioridad, contacta soporte de EasyChatBot.

WooCommerce (catálogo de productos)

En el modal elige Tipo de fuente → WooCommerce – productos (REST). Necesitas la URL HTTPS de la tienda (solo el dominio, sin /wp-json/) y claves REST con permiso de lectura (consumer key y consumer secret).

En 2. Probar la API validas credenciales y ves cuántos productos se importarían. EasyChatBot llama a GET /wp-json/wc/v3/products con Basic Auth (igual que Postman: no hace falta codificar manualmente en Base64 en el dashboard). Si el hosting o un firewall/CDN rechaza Basic Auth, el conector reintenta automáticamente con consumer_key y consumer_secret en la query (válido en HTTPS). Paginación hasta 100 productos por página hasta el máximo de ítems (por defecto 200, máximo 500).

La respuesta es un array JSON en la raíz (no hace falta list_json_path). Modo recomendado: un contexto por ítem con item_id_path = id y title_path = name.

Checklist manual en tu tienda:

  • WooCommerce activo y REST API habilitada (WooCommerce → Ajustes → Avanzado → REST API).
  • Permalinks distintos de «plain» (Ajustes → Enlaces permanentes: nombre de entrada, etc.).
  • Claves con permiso Read; la tienda accesible por HTTPS desde internet (el servicio Stream debe poder alcanzar la URL).
  • Si ves 403 con mensaje de firewall o CDN (p. ej. Cloudflare) en EasyChatBot pero Postman funciona desde tu PC: allowlist de la IP del servidor Stream o regla para /wp-json/wc/v3/* en el panel del hosting.

Parámetros del listado (REST): tabla clave/valor con los parámetros de consulta documentados en el listado v3 (ej. status = publish, stock_status = instock, category, featured). No confundas con propiedades del producto en el JSON: catalog_visibility (visible, catalog, search, hidden) no filtra en el servidor WooCommerce; si lo pones en esta tabla, EasyChatBot filtra cada ítem tras descargarlo. Para otros campos solo presentes en el JSON del producto, usa Condiciones del producto. Los parámetros REST (excepto catalog_visibility) también se añaden al GET de detalle por producto si los configuras.

Condiciones del producto: mismas reglas que en Wix (ruta, operador, valor) evaluadas después del listado y del detalle; los que no cumplan no se importan.

Opcional: Traer detalle completo por producto hace GET /products/{id} por ítem y sustituye el resumen del listado. Filtra el texto con Propiedades del producto a incluir en el texto (comodines images.*.src, categories[].name; vacío = todo). En Probar ahora, con detalle activo, verás hasta 5 productos de muestra (texto + JSON); la sync aplica el detalle a todos dentro del límite.

Variaciones y stock en el texto (productos type: variable): el detalle Woo devuelve attributes[].options con todas las tallas del atributo, pero el stock real está en GET /products/{id}/variations. Con detalle activo, por defecto EasyChatBot también trae variaciones (woo_fetch_product_variations) y las guarda en ecb_variations antes de generar el markdown. Usa rutas como ecb_variations.*.attributes.*.option y ecb_variations.*.price. Los interruptores (activos por defecto) recortan variaciones sin stock (outofstock; se mantiene onbackorder), no comprables o no publicadas, y alinean attributes[].options con las variaciones que quedan. Para ocultos de catálogo, Solo visibles en catálogo trata catalog_visibility: hidden en el producto. Excluir productos enteros del import sigue siendo parámetros REST (stock_status) o Condiciones del producto.

Opcional (requiere detalle activo y plugin WooCommerce Bookings en la tienda): Traer datos de reservas añade al JSON de cada producto type=booking un bloque con servicio, recursos y un resumen de huecos disponibles en una ventana de días (configurable). Sirve para que el bot responda sobre servicios y disponibilidad en la base de conocimiento; no crea reservas en Woo por sí solo.

Metadatos del producto (meta_data): el listado REST ya trae el array meta_data de cada producto (campos personalizados de tu tema o plugins). No hace falta activar el GET de detalle solo por eso. Tras Probar API, en Metadatos y tags aparece la tabla Metadatos WooCommerce (listado): cada fila muestra cuántos productos tienen valor no vacío frente a cuántos solo traen la clave vacía (con valor / presente). Si aún no habías guardado selección, se premarcan solo las claves con valor en la muestra; usa Marcar con valor para repetir ese criterio. También puedes Añadir clave manualmente. Las claves marcadas no se copian al texto del contexto: van a los metadatos del chunk en RAG (en la búsqueda de contexto verás woo_product_meta con key, value y type por producto). Tras cambiar la selección, sincroniza de nuevo y deja que se reindexe el RAG. Combínalo con Propiedades a incluir por ítem (listado) para nombre, precio, descripción corta, categorías, etc.

Ejemplo rápido (Fake Store)

URL: GET https://fakestoreapi.com/products

  • Forma: lista en la raíz
  • Modo: aplanar o un contexto por ítem
  • Markdown automático o plantilla de ejemplo del modal
  • Campo JSON para tags: category y tag por defecto catalogo