Nuova funzionalità: Agente AI legge Shopify Metaobjects #
Versione piattaforma: 20.8.0 · Feature
Il tuo agente AI ora può leggere i contenuti che il tuo negozio conserva nei metaobjects di Shopify: colori, rivestimenti, immagini, prezzi, disponibilità e tempi di consegna che cambiano in base al paese o alla lingua. Quando un cliente chiede quali colori di un divano sono venduti in Francia, l’agente fornisce la risposta per la Francia.
L’agente legge in tempo reale da Shopify, quindi le sue risposte seguono sempre il tuo negozio. Legge solo contenuti pubblicati e non modifica mai nulla nel tuo negozio.
Questa funzione è disattivata per impostazione predefinita, quindi nulla cambia finché non la attivi. Per utilizzarla:
- Aggiungi le autorizzazioni read_metaobjects, read_metaobject_definitions e read_files all’app Shopify collegata a Spoki.
- Salva nuovamente la tua integrazione Shopify in AI Agents → Integrations and Tools.
- Attiva le tre nuove opzioni: List Metaobject Definitions, Get Metaobjects e Get Metaobject.
Quindi aggiungi una frase al prompt del tuo agente dicendo che i contenuti che dipendono dal paese sono conservati nei metaobjects.


Messaggio di rilascio esterno (clienti) #
Oggetto: Il tuo agente AI può ora leggere i metaobject di Shopify
Il tuo agente AI Spoki può ora rispondere con i contenuti che tieni nei metaobject di Shopify, non solo con quelli presenti sul prodotto.
Molti store tengono nei metaobject i dettagli che variano per Paese o lingua: colori e rivestimenti, immagini, prezzi, disponibilità, tempi di consegna. Finora l’agente poteva leggere solo i prodotti, quindi non poteva dire a un cliente in Francia quali colori di un divano sono in vendita in Francia. Ora può farlo.
Cosa può fare l’agente
- Vedere quali tipi di metaobject ha il tuo store.
- Leggere le voci di un tipo e cercarle per nome, ad esempio un modello e un Paese.
- Seguire i collegamenti tra voci, prodotti e immagini.
L’agente legge solo i contenuti pubblicati e visibili sulla vetrina del tuo store. Non modifica mai nulla nel tuo store.
Cosa devi fare
Le nuove opzioni sono disattivate per impostazione predefinita. Se non fai nulla, il tuo agente continua a funzionare esattamente come oggi. Per usarle:
- Aggiungi i permessi sui metaobject all’app Shopify che hai collegato a Spoki: read_metaobjects, read_metaobject_definitions e read_files, accanto a read_products.
- In Spoki, apri la tua integrazione Shopify in AI Agents > Integrations and Tools e salvala di nuovo, oppure creane una nuova.
- Attiva le tre nuove opzioni: List Metaobject Definitions, Get Metaobjects, Get Metaobject.
La guida passo passo è più in basso, sia per un’app già esistente sia per una nuova. Se hai bisogno di aiuto, scrivi al supporto Spoki.
Messaggio di rilascio interno (Support, CS, Sales, team AI) #
Oggetto: L’agente AI può leggere i metaobject di Shopify (attivazione su richiesta del cliente)
Lo strumento Shopify dell’agente AI ha tre nuove opzioni in sola lettura che leggono i metaobject direttamente dallo store del cliente. È stato realizzato per poltronesofà, il cui prodotto è un contenitore generico, mentre colori, immagini, prezzi e disponibilità per Paese si trovano nei metaobject.
Cosa è stato rilasciato
- Tre opzioni nell’integrazione Shopify: List Metaobject Definitions, Get Metaobjects, Get Metaobject.
- L’agente legge i dati in tempo reale da Shopify con le credenziali del cliente. In Spoki non viene salvato nulla.
- Vengono restituiti solo i contenuti pubblicati: tipi con accesso allo storefront, voci Active, prodotti Active.
- Non è stato necessario modificare la web app. Le opzioni compaiono nel form esistente dell’integrazione Shopify.
Chi è coinvolto
Nessuno, finché non attiva la funzione. Le opzioni sono disattivate per impostazione predefinita e le integrazioni esistenti continuano a funzionare senza modifiche.
Cosa deve fare un cliente per usarla
- Aggiungere read_metaobjects, read_metaobject_definitions e read_files alla propria app Shopify. È richiesto anche read_products; i clienti che hanno seguito la nostra guida di configurazione lo hanno già.
- Salvare di nuovo l’integrazione Shopify in Spoki (o crearne una nuova), così i permessi vengono ricontrollati.
- Attivare le tre opzioni e salvare.
- Aggiungere al prompt dell’agente una frase che indica che i contenuti che dipendono dal Paese si trovano nei metaobject.
Cosa deve sapere il Support
| Sintomo | Causa | Cosa fare |
|---|---|---|
| Le tre opzioni mostrano “Missing required permissions” | All’app Shopify manca uno dei quattro scope | Seguire la guida di configurazione qui sotto, poi salvare di nuovo l’integrazione |
| Le opzioni non compaiono su un’integrazione precedente | L’integrazione è stata salvata prima del rilascio | Aprirla e salvare di nuovo le credenziali |
| L’agente dice che un tipo o una voce non esiste | Il tipo non ha accesso allo storefront, oppure la voce è in Draft | Abilitare l’accesso allo storefront sulla definizione del metaobject e impostare la voce su Active |
| L’agente risponde dal prodotto e ignora i metaobject | Il prompt non li menziona | Aggiungere la frase del prompt indicata nella guida |
| L’agente non trova una voce | La ricerca confronta solo le parole nel nome della voce | Nominare le voci con modello e Paese, oppure chiedere con il nome esatto |
Limiti da tenere presenti
- L’agente deve conoscere il Paese del cliente dalla conversazione. Non viene rilevato automaticamente.
- La ricerca funziona sul nome della voce. Se uno store nomina le voci in modo diverso, l’agente deve scorrerle una per una, e questo è più lento.
- Testato in staging su uno store di prova (5 domande su 5 relative ai Paesi risposte correttamente). Non ancora usato da un cliente reale.
Stato e responsabile
Pull request spoki-ai #658, in attesa della review del team AI. Tracciata nel task Notion Shopify MetaObjects.
Guida di configurazione: prima di iniziare #
Servono quattro permessi Shopify (scope) sull’app collegata a Spoki, e i tuoi metaobject devono essere pubblicati.
| Scope | Perché serve | Probabilmente già presente? |
|---|---|---|
| read_metaobjects | Leggere le voci dei metaobject | No, nuovo |
| read_metaobject_definitions | Leggere i tipi di metaobject e i loro campi | No, nuovo |
| read_files | Leggere le immagini e i file collegati a una voce | No, nuovo |
| read_products | Leggere i prodotti collegati a una voce | Sì, se hai seguito la guida Spoki per Shopify |
Se manca uno dei quattro, le tre opzioni restano disattivate in Spoki con l’avviso “Missing required permissions”.
Due cose da controllare nel tuo admin Shopify, in Content > Metaobjects:
- L’accesso allo storefront è attivo per ogni definizione di metaobject che l’agente deve leggere. I tipi senza accesso allo storefront restano nascosti all’agente.
- Le voci sono Active, non Draft. Le voci Draft restano nascoste all’agente.
Poi segui la guida che corrisponde alla tua app:
- A. Hai collegato Spoki con un Client ID e un Client Secret (app del Dev Dashboard).
- B. Hai collegato Spoki con un token di accesso Admin API (vecchia custom app creata nell’admin del tuo store).
- C. Non hai ancora un’app, oppure preferisci usarne una dedicata.
A. App esistente con Client ID e Client Secret (Dev Dashboard) #
Aggiungi gli scope rilasciando una nuova versione della tua app. Il Client ID e il Client Secret restano gli stessi.
- Apri la Shopify Dev Dashboard e seleziona l’app che hai collegato a Spoki.
- Nel menu a sinistra, fai clic su Versions, poi su Create version (in alto a destra). Il form si apre già compilato con i dati della versione attuale.
- Nella sezione API access, trova il campo Scopes. Lascia tutto quello che c’è già e aggiungi, separati da virgole: read_metaobjects,read_metaobject_definitions,read_files. Aggiungi anche read_products se non è nell’elenco.
- Lascia gli altri campi così come sono e fai clic su Release in fondo al form.
- Nell’admin del tuo store Shopify, vai su Settings > Apps and sales channels, apri l’app e approva i permessi aggiornati se Shopify te lo chiede.
- Continua con la sezione «In Spoki» più in basso.
Usa il campo Scopes, non Optional scopes: gli optional scopes non vengono concessi automaticamente.
B. App esistente con un token di accesso Admin API (vecchia custom app) #
Questa è l’app descritta nell’articolo di help attuale, Connect Shopify to Spoki AI Sales Agent, creata nell’admin del tuo store in Develop apps. Gli scope si aggiungono nella configurazione dell’app.
- Nel tuo admin Shopify, vai su Settings > Apps and sales channels > Develop apps.
- Apri l’app che hai creato per Spoki (ad esempio «Spoki AI Integration»).
- Apri la scheda Configuration. In Admin API integration, fai clic su Edit (o Configure).
- Cerca e seleziona read_metaobjects, read_metaobject_definitions e read_files. Verifica che read_products sia selezionato.
- Fai clic su Save.
- Continua con la sezione «In Spoki» più in basso. Usa lo stesso token di accesso Admin API di prima.
La scheda Configuration elenca gli scope che l’app ha oggi. Fai clic su Edit in Admin API integration per modificarli:

Digita «metaobject» nel filtro per trovare i due scope sui metaobject, seleziona quelli read_, poi filtra per «files» e seleziona read_files:

Dopo aver salvato, apri la scheda API credentials. Se Shopify mostra un nuovo token di accesso Admin API con Reveal token once, copialo e sostituisci il token nella tua integrazione Spoki. Il token viene mostrato una sola volta.
Da confermare prima dell’invio: se Shopify emette sempre un nuovo token dopo una modifica degli scope su queste app più vecchie. Le schermate qui sopra sono del nostro store di test, dove gli scope sono già stati aggiunti; non ho modificato gli scope lì per verificarlo.
C. Nuova app #
Shopify non consente più di creare le vecchie custom app nell’admin dello store, quindi una nuova app si crea nel Dev Dashboard. La procedura completa è nell’articolo di help del nuovo metodo: Connect your Shopify store to Spoki AI Sales Agent (Dev Dashboard). L’unica differenza è l’elenco degli scope.
- Apri la Shopify Dev Dashboard e crea un’app.
- Crea la prima versione. In API access > Scopes, inserisci gli scope della guida Spoki e aggiungi quelli dei metaobject. L’elenco completo:
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
- Fai clic su Release.
- Installa l’app sul tuo store.
- Nella pagina Settings dell’app, copia il Client ID e il Client secret.
- Continua con la sezione «In Spoki» più in basso e crea una nuova integrazione Shopify con queste credenziali.
Se l’agente deve solo leggere prodotti e metaobject, sono sufficienti i quattro scope della sezione «Prima di iniziare». In quel caso le opzioni su ordini e clienti restano disattivate in Spoki.
In Spoki: attiva le opzioni #
Spoki verifica i permessi Shopify quando salvi l’integrazione, quindi va salvata di nuovo dopo la modifica degli scope.
Se hai già un’integrazione Shopify
- Vai su AI Agents > Integrations and Tools.
- Apri la tua integrazione Shopify e salva di nuovo le credenziali, senza modificarle.
- Nell’elenco delle opzioni Shopify, attiva List Metaobject Definitions, Get Metaobjects e Get Metaobject.
- Salva.
Se ne stai creando una nuova
- Vai su AI Agents > Integrations and Tools e fai clic su Add Tools, poi su Create Integration, poi su Shopify.
- Scegli Dev Dashboard (Recommended) e inserisci un nome, una descrizione, il nome del tuo store, lo Storefront Access Token, il Client ID e il Client Secret. Per un’app più vecchia, scegli invece Admin API Token (Legacy).
- Fai clic su Add Integration. Compare l’elenco delle opzioni.
- Attiva le tre opzioni sui metaobject, più le altre che usi, e fai clic su Create.
- Apri il tuo agente, vai alla scheda Tools, fai clic su Add Tools e seleziona l’integrazione.
Il form di integrazione Shopify in Spoki, con i due metodi di collegamento in alto:

Le tre opzioni sui metaobject sono in fondo all’elenco delle opzioni Shopify. Quando l’app ha tutti i permessi, si possono attivare tutte le opzioni:

Indica all’agente dove cercare
Aggiungi al prompt dell’agente una frase come questa, adattata al tuo store:
Colori, immagini, prezzi e disponibilità dipendono dal Paese del cliente e sono salvati nei metaobject Shopify dello store, non nei prodotti. Cercali sempre con gli strumenti sui metaobject prima di rispondere, e non inventare mai le informazioni.
Senza questa frase l’agente potrebbe rispondere basandosi solo sul prodotto.
Verifica che funzioni #
Apri il Playground dell’agente e fai una domanda la cui risposta dipende da un metaobject, ad esempio «In quali colori è disponibile il divano Lario per la Francia?». L’agente dovrebbe rispondere solo con le voci di quel Paese.

Sul nostro store di test in staging l’agente ha risposto correttamente a queste cinque domande:
| Domanda | Risposta dell’agente |
|---|---|
| In quali colori è disponibile il divano Lario per la Francia? | Solo Grigio perla, 1.540 EUR |
| In quali colori è disponibile il divano Lario per l’Italia? | Sabbia, Grigio perla, Blu notte |
| Il divano Taormina è in vendita in Spagna? | No, solo in Italia |
| Il divano Dolomiti è in vendita in Spagna? | No, solo in Italia e in Francia |
| Il divano Siena è disponibile in Terracotta in Italia? | No, in Italia solo Cuoio naturale |
Se qualcosa non va
| Cosa vedi | Cosa controllare |
|---|---|
| “Missing required permissions” sulle tre opzioni | Manca uno dei quattro scope, oppure lo store non ha approvato l’aggiornamento dell’app. Correggi e poi salva di nuovo l’integrazione |
| Le opzioni non sono nell’elenco | Salva di nuovo le credenziali dell’integrazione |
| L’agente non trova un tipo di metaobject | L’accesso allo storefront è disattivato per quella definizione in Shopify |
| L’agente non trova una voce | La voce è in Draft, oppure il suo nome non contiene le parole usate nella domanda |
| L’agente ignora i metaobject | Aggiungi la frase del prompt indicata sopra |
