Mensaje de lanzamiento externo (clientes) #
Asunto: Tu agente de IA ya puede leer los metaobjects de Shopify
Tu agente de IA de Spoki ya puede responder con el contenido que guardas en los metaobjects de Shopify, no solo con lo que aparece en el producto.
Muchas tiendas guardan en los metaobjects los detalles que varían según el país o el idioma: colores y revestimientos, imágenes, precios, disponibilidad, plazos de entrega. Hasta ahora el agente solo podía leer los productos, así que no podía decirle a un cliente en Francia qué colores de un sofá se venden en Francia. Ahora sí puede.
Qué puede hacer el agente
- Ver qué tipos de metaobject tiene tu tienda.
- Leer las entradas de un tipo y buscarlas por nombre, por ejemplo un modelo y un país.
- Seguir los enlaces entre entradas, productos e imágenes.
El agente solo lee el contenido publicado y visible en tu storefront. Nunca modifica nada en tu tienda.
Qué tienes que hacer
Las nuevas opciones están desactivadas de forma predeterminada. Si no haces nada, tu agente sigue funcionando exactamente igual que hoy. Para usarlas:
- Añade los permisos de metaobject a la app de Shopify que has conectado a Spoki: read_metaobjects, read_metaobject_definitions y read_files, junto a read_products.
- En Spoki, abre tu integración de Shopify en AI Agents > Integrations and Tools y guárdala de nuevo, o crea una nueva.
- Activa las tres opciones nuevas: List Metaobject Definitions, Get Metaobjects, Get Metaobject.
La guía paso a paso está más abajo, tanto para una app existente como para una nueva. Si necesitas ayuda, escribe al soporte de Spoki.
Mensaje de lanzamiento interno (Support, CS, Sales, equipo de IA) #
Asunto: El agente de IA puede leer los metaobjects de Shopify (activación opcional por cliente)
La herramienta de Shopify del agente de IA tiene tres opciones nuevas de solo lectura que leen los metaobjects directamente de la tienda del cliente. Se creó para poltronesofà, cuyo producto es un contenedor genérico, mientras que los colores, las imágenes, los precios y la disponibilidad por país viven en los metaobjects.
Qué se ha publicado
- Tres opciones en la integración de Shopify: List Metaobject Definitions, Get Metaobjects, Get Metaobject.
- El agente lee en tiempo real desde Shopify con las credenciales del propio cliente. En Spoki no se almacena nada.
- Solo se devuelve el contenido publicado: tipos con acceso al storefront, entradas Active, productos Active.
- No hizo falta ningún cambio en la aplicación web. Las opciones aparecen en el formulario existente de la integración de Shopify.
A quién afecta
A nadie, hasta que active la función. Las opciones están desactivadas de forma predeterminada y las integraciones existentes siguen funcionando sin cambios.
Qué debe hacer un cliente para usarlo
- Añadir read_metaobjects, read_metaobject_definitions y read_files a su app de Shopify. También es obligatorio read_products; los clientes que siguieron nuestra guía de configuración ya lo tienen.
- Volver a guardar la integración de Shopify en Spoki (o crear una nueva), para que se vuelvan a comprobar los permisos.
- Activar las tres opciones y guardar.
- Añadir al prompt del agente una frase que indique que el contenido que depende del país está en los metaobjects.
Qué debe saber el equipo de Support
| Síntoma | Causa | Qué hacer |
|---|---|---|
| Las tres opciones muestran «Missing required permissions» | A la app de Shopify le falta uno de los cuatro scopes | Seguir la guía de configuración que aparece más abajo y volver a guardar la integración |
| Las opciones no aparecen en una integración antigua | La integración se guardó antes del lanzamiento | Abrirla y volver a guardar las credenciales |
| El agente dice que un tipo o una entrada no existe | El tipo no tiene acceso al storefront, o la entrada está en Draft | Activar el acceso al storefront en la definición del metaobject y poner la entrada en Active |
| El agente responde desde el producto e ignora los metaobjects | El prompt no los menciona | Añadir la frase del prompt que aparece en la guía |
| El agente no encuentra una entrada | La búsqueda solo compara palabras del nombre de la entrada | Nombrar las entradas con el modelo y el país, o preguntar con el nombre exacto |
Límites que conviene tener en cuenta
- El agente debe conocer el país del cliente a partir de la conversación. No se detecta automáticamente.
- La búsqueda funciona sobre el nombre de la entrada. Si una tienda nombra las entradas de otra forma, el agente tiene que recorrerlas una a una, lo que es más lento.
- Probado en staging con una tienda de prueba (5 de 5 preguntas sobre países respondidas correctamente). Todavía no lo ha usado ningún cliente real.
Estado y responsable
Pull request spoki-ai #658, a la espera de la revisión del equipo de IA. Seguimiento en la tarea de Notion Shopify MetaObjects.
Guía de configuración: antes de empezar #
Necesitas cuatro permisos de Shopify (scopes) en la app conectada a Spoki, y tus metaobjects deben estar publicados.
| Scope | Para qué sirve | ¿Es probable que ya esté? |
|---|---|---|
| read_metaobjects | Leer las entradas de los metaobjects | No, nuevo |
| read_metaobject_definitions | Leer los tipos de metaobject y sus campos | No, nuevo |
| read_files | Leer las imágenes y los archivos vinculados a una entrada | No, nuevo |
| read_products | Leer los productos vinculados a una entrada | Sí, si seguiste la guía de Spoki para Shopify |
Si falta uno de los cuatro, las tres opciones permanecen desactivadas en Spoki con el aviso «Missing required permissions».
Hay dos cosas que debes comprobar en el admin de Shopify, en Content > Metaobjects:
- El acceso al storefront está activado en cada definición de metaobject que el agente deba leer. Los tipos sin acceso al storefront quedan ocultos para el agente.
- Las entradas están en Active, no en Draft. Las entradas en Draft quedan ocultas para el agente.
A continuación, sigue la guía que corresponda a tu app:
- A. Conectaste Spoki con un Client ID y un Client Secret (app del Dev Dashboard).
- B. Conectaste Spoki con un token de acceso de Admin API (custom app antigua creada en el admin de tu tienda).
- C. Todavía no tienes una app, o prefieres una independiente.
A. App existente con Client ID y Client Secret (Dev Dashboard) #
Añades los scopes publicando una nueva versión de tu app. El Client ID y el Client Secret no cambian.
- Abre el Shopify Dev Dashboard y selecciona la app que conectaste a Spoki.
- En el menú de la izquierda, haz clic en Versions y luego en Create version (arriba a la derecha). El formulario se abre precargado con los datos de tu versión actual.
- En la sección API access, localiza el campo Scopes. Conserva todo lo que ya esté ahí y añade, separados por comas: read_metaobjects,read_metaobject_definitions,read_files. Añade también read_products si no está en la lista.
- Deja el resto de campos como están y haz clic en Release al final del formulario.
- En el admin de tu tienda Shopify, ve a Settings > Apps and sales channels, abre la app y aprueba los permisos actualizados si Shopify te lo pide.
- Continúa con la sección «En Spoki» más abajo.
Usa el campo Scopes, no Optional scopes: los optional scopes no se conceden automáticamente.
B. App existente con un token de acceso de Admin API (custom app antigua) #
Esta es la app descrita en el artículo de ayuda actual, Connect Shopify to Spoki AI Sales Agent, creada en el admin de tu tienda en Develop apps. Los scopes se añaden en la configuración de la app.
- En el admin de Shopify, ve a Settings > Apps and sales channels > Develop apps.
- Abre la app que creaste para Spoki (por ejemplo, «Spoki AI Integration»).
- Abre la pestaña Configuration. En Admin API integration, haz clic en Edit (o Configure).
- Busca y marca read_metaobjects, read_metaobject_definitions y read_files. Comprueba que read_products esté marcado.
- Haz clic en Save.
- Continúa con la sección «En Spoki» más abajo. Usa el mismo token de acceso de Admin API de antes.
La pestaña Configuration enumera los scopes que tiene la app actualmente. Haz clic en Edit en Admin API integration para cambiarlos:

Escribe «metaobject» en el filtro para encontrar los dos scopes de metaobject, marca los de read_, luego filtra por «files» y marca read_files:

Después de guardar, abre la pestaña API credentials. Si Shopify muestra un nuevo token de acceso de Admin API con Reveal token once, cópialo y sustituye el token en tu integración de Spoki. El token se muestra solo una vez.
Por confirmar antes de enviar: si Shopify siempre emite un token nuevo tras un cambio de scopes en estas apps más antiguas. Las capturas de arriba son de nuestra tienda de prueba, donde los scopes ya están añadidos; no cambié los scopes allí para comprobarlo.
C. App nueva #
Shopify ya no permite crear las custom apps antiguas en el admin de la tienda, así que una app nueva se crea en el Dev Dashboard. El recorrido completo está en el artículo de ayuda del método nuevo: Connect your Shopify store to Spoki AI Sales Agent (Dev Dashboard). La única diferencia es la lista de scopes.
- Abre el Shopify Dev Dashboard y crea una app.
- Crea su primera versión. En API access > Scopes, introduce los scopes de la guía de Spoki y añade los de metaobject. La lista completa:
read_products,read_product_listings,write_product_listings,read_orders,write_orders,read_customers,write_customers,read_draft_orders,write_draft_orders,read_metaobjects,read_metaobject_definitions,read_files
- Haz clic en Release.
- Instala la app en tu tienda.
- En la página Settings de la app, copia el Client ID y el Client secret.
- Continúa con la sección «En Spoki» más abajo y crea una nueva integración de Shopify con estas credenciales.
Si el agente solo necesita leer productos y metaobjects, bastan los cuatro scopes de la sección «Antes de empezar». En ese caso, las opciones de pedidos y clientes permanecen desactivadas en Spoki.
En Spoki: activa las opciones #
Spoki comprueba los permisos de Shopify al guardar la integración, así que hay que volver a guardarla después de cambiar los scopes.
Si ya tienes una integración de Shopify
- Ve a AI Agents > Integrations and Tools.
- Abre tu integración de Shopify y vuelve a guardar las credenciales, sin cambiarlas.
- En la lista de opciones de Shopify, activa List Metaobject Definitions, Get Metaobjects y Get Metaobject.
- Guarda.
Si estás creando una nueva
- Ve a AI Agents > Integrations and Tools y haz clic en Add Tools, luego en Create Integration y después en Shopify.
- Elige Dev Dashboard (Recommended) e introduce un nombre, una descripción, el nombre de tu tienda, el Storefront Access Token, el Client ID y el Client Secret. Si se trata de una app más antigua, elige Admin API Token (Legacy).
- Haz clic en Add Integration. Aparece la lista de opciones.
- Activa las tres opciones de metaobject, más las demás que uses, y haz clic en Create.
- Abre tu agente, ve a su pestaña Tools, haz clic en Add Tools y selecciona la integración.
El formulario de integración de Shopify en Spoki, con los dos métodos de conexión en la parte superior:

Las tres opciones de metaobject están al final de la lista de opciones de Shopify. Cuando la app tiene todos los permisos, se pueden activar todas las opciones:

Indica al agente dónde buscar
Añade al prompt del agente una frase como esta, adaptada a tu tienda:
Los colores, las imágenes, los precios y la disponibilidad dependen del país del cliente y están guardados en los metaobjects de Shopify de la tienda, no en los productos. Consúltalos siempre con las herramientas de metaobject antes de responder, y no inventes nunca la información.
Sin esta frase, el agente podría responder basándose solo en el producto.
Comprueba que funciona #
Abre el Playground del agente y formula una pregunta cuya respuesta dependa de un metaobject, por ejemplo «¿En qué colores está disponible el sofá Lario para Francia?». El agente debería responder solo con las entradas de ese país.

En nuestra tienda de prueba de staging, el agente respondió correctamente a estas cinco preguntas:
| Pregunta | Respuesta del agente |
|---|---|
| ¿En qué colores está disponible el sofá Lario para Francia? | Solo Grigio perla, 1.540 EUR |
| ¿En qué colores está disponible el sofá Lario para Italia? | Sabbia, Grigio perla, Blu notte |
| ¿Se vende el sofá Taormina en España? | No, solo en Italia |
| ¿Se vende el sofá Dolomiti en España? | No, solo en Italia y Francia |
| ¿Está disponible el sofá Siena en Terracotta en Italia? | No, en Italia solo Cuoio naturale |
Si algo no funciona
| Qué ves | Qué debes comprobar |
|---|---|
| «Missing required permissions» en las tres opciones | Falta uno de los cuatro scopes, o la tienda no ha aprobado la actualización de la app. Corrígelo y luego vuelve a guardar la integración |
| Las opciones no están en la lista | Vuelve a guardar las credenciales de la integración |
| El agente no encuentra un tipo de metaobject | El acceso al storefront está desactivado para esa definición en Shopify |
| El agente no encuentra una entrada | La entrada está en Draft, o su nombre no contiene las palabras de la pregunta |
| El agente ignora los metaobjects | Añade la frase del prompt indicada arriba |
