Shopify store assistant

The AgentRow app for Shopify connects a Shopify store to an app in your AgentRow organisation. It puts that app's chat window on the store's pages, signs in shoppers who are logged in to the store, and lets your agents use the store through Shopify store tools: search products, check stock, read the store's policies, look up orders and change the shopper's cart. The assistant is an ordinary AgentRow app and agent, so the rest of this guide applies to it: the workflow, knowledge bases, memory, the hand-off to your team, the inbox and the run logs.

The app asks Shopify for read access only: products, inventory, orders, customers and the store's legal policies. Cart changes are made in the shopper's own browser, on the store's cart, never through the store's admin.

#Setting up the Shopify app

The app is not listed in the Shopify App Store yet (see "Not built yet" below), so it cannot be installed from there today. The steps below describe the app once it is installed on a store.

1. Prepare the app in AgentRow. Create a chat app (conversational or support) with an agent. A support app lets the assistant hand conversations to your team (Apps and end users).
2. Install the AgentRow app on the store, then open it in the Shopify admin (Apps → AgentRow). Opening it connects the store, and the page shows three steps.
3. Link to AgentRow. Link to AgentRow opens AgentRow in a new tab. Sign in (or create an account), pick the Organisation and the Storefront app that answers shoppers, and choose Link store. Then go back to the page in the Shopify admin and press Refresh.
4. Turn the chat on in your theme. Open the theme editor, open App embeds, switch on AgentRow chat and save. Until the store is linked, the chat stays hidden on the storefront.
5. Give the assistant the store. Create Shopify store tools and attach them to the agent, add a Shopify store node to the app's Chat (in), and publish the app (below).

About linking:

• Linking needs developer access to the organisation.
• The link from the Shopify admin works once, for one hour. An expired or used link says so: open the AgentRow app in the Shopify admin and choose Link again.
• A store is linked to one organisation at a time. Linking a store that another organisation has linked is refused (SHOPIFY_ALREADY_LINKED) until its Shopify integration is removed there.
• If the app's Allowed origins (Auth context tab) list sites, linking adds the store's domains to them.
• Once the store is linked, the page names the organisation and the app, with Open AgentRow and Change the app (link the store to another app).
• If Shopify has not granted every permission the app needs, for example after an update, the page lists the missing ones; approve them in Shopify and press Refresh.

#Shopify store tools

Create them under Tools → New tool with the type Shopify store, and pick an Action. Each tool runs one action; its input, description and safety level follow the action. The store is not part of the tool: the app chooses it with its Shopify store node, so the same tools and agents can serve another store in another app. Attach the tools to the agent like any other tool (Tools).

• Search products: products matching the shopper's words, or the store's products in alphabetical order when there are none; 5 by default and at most 10, each with its price, availability, variants, page link and picture. The result also says how many products the store sells, so a search that matches nothing is not read as an empty store.
• Get a product: one product by its handle, with its description, options and every variant.
• Check stock: whether each variant can be bought now, and how many are in stock when the store tracks stock.
• Store policies: the store's published policies (refund, shipping, privacy, terms of service, contact) with their links.
• Order status: one order by its number and the email it was placed with: payment, fulfilment and tracking. A wrong email answers exactly like a missing order, and a conversation can make 10 order lookups every 10 minutes (ORDER_LOOKUP_LIMITED).
• Find my orders: the signed-in shopper's own recent orders. It is offered to the model only when the shopper is logged in to the store; otherwise the run trace shows it withheld (missing_auth_claims).
• Add to cart, View cart, Change cart quantity, Apply discount code and Checkout link: the cart tools, described below.

Only products that are active and published to the store's Online Store are found. Order lookups reach the last 60 days of orders. A store call that fails comes back as a named error, and every store action is a tool call in the run trace with its input and result.

#The Shopify store node

On the app's Workflow tab, add a Shopify store node (in the Channels group of the palette), pick its Store, and connect it from the square port under Chat (in). Every agent in the app then uses that store, and the node reads "Every agent in this app uses" followed by the store's name. An app has at most one Shopify store node. The picker lists the stores linked to the organisation (Integrations → Shopify stores); a store is linked from the Shopify admin, not created here.

• An app whose agents have Shopify store tools and no Shopify store node on Chat (in) is refused at save and publish, naming the agent.
• A run can reach only its app's store; a store tool called without one fails with SHOPIFY_STORE_NOT_ATTACHED.
• An agent's own test chat has no app, so it shows a Test store picker when the agent has store tools. Pick one of the linked stores: nothing is picked for you, and the choice is kept for that agent in your browser.

#The storefront chat window

The chat window on the store is the AgentRow chat widget (The chat widget), started by the AgentRow chat app embed. Its welcome message, suggested prompts, position and the rest of the chat settings come from the app's Install tab; the theme editor settings below change it on that theme.

Shoppers who are logged in to the store are signed in to the chat by their customer account, with their name and email when the store shares them. Their conversations follow them across devices, and Find my orders works for them. Anonymous shoppers stay anonymous and can still ask about an order with its number and email.

The theme editor settings (App embeds → AgentRow chat):

• Chat window: open the chat when the page loads; show what the assistant is doing (short lines such as "Searching products"); show past conversations.
• Look: colour scheme (as set in AgentRow, light, dark, or match the shopper's device), accent colour, the store's font, corner radius, panel width and height, and stacking order (z-index), to raise the chat if part of the theme covers it.
• Product pictures: on or off, and their size from 0 to 360 px (0 means as wide as the reply).
• Advanced: Custom CSS, added inside the chat window after its own styles, and Custom script, which runs before the chat starts as function (options, AgentRow). It gets the options AgentRow.init takes (renderers, css, theme, strings and so on), and it may change them, return new ones, or return false to start the chat itself. If the script fails, the chat does not start, and the theme editor shows the error on the page.

The settings take effect when you save the theme.

#Product pictures in replies

Search products and Get a product return each product's picture and page link, and their descriptions tell the model to show a product as its picture, then its name linked to its page, then its price. The storefront chat window shows pictures served from the store's Shopify files (cdn.shopify.com or the store's own /cdn/shop/ path) as pictures; any other picture stays a link. The chat widget on other websites shows every picture as a link.

#Cart tools: the chat window does the cart step

A shopper's cart lives in their browser, so the cart tools do their cart step in the shopper's chat window, on the store's own cart:

1. The agent calls the tool. When it names a product (to add it or change its quantity), AgentRow finds the product and the variant the shopper means (the only variant, an exact title, every option value, or a unique part of a title) and refuses before the cart is touched: PRODUCT_NOT_FOUND, VARIANT_REQUIRED (listing the choices, sold-out ones marked), VARIANT_NOT_FOUND or VARIANT_AMBIGUOUS, and SOLD_OUT when adding a sold-out variant.
2. The chat window changes the cart and reports back: the model sees the items, quantities, totals and discount codes. Shopify's cart enforces stock itself; its refusal comes back as CART_REFUSED with Shopify's words.
3. If the chat window does not answer within 20 seconds (the page was closed or reloaded), the call fails with CHAT_WINDOW_NO_ANSWER and nothing was changed.

The cart tools:

• Add to cart: 1 to 20 of the product.
• View cart: the items, subtotal, discounts, total and discount codes.
• Change cart quantity: a new quantity up to 50; 0 removes the item.
• Apply discount code: says whether the code applies; a code that does not apply is taken off again. A conversation can try 5 codes every 10 minutes (DISCOUNT_TRIES_LIMITED).
• Checkout link: the store's checkout for the current cart; an empty cart has none (CART_EMPTY).

After a change the chat window refreshes the theme's cart icon where the theme supports it, and it emits client_action: events (The chat widget). Cart tools are offered to the model only in the chat window on the store's pages: in a test chat, over Slack or in a server run the run trace shows them withheld (no_chat_window_cart).

#What the merchant and the shopper see

• The merchant sees the AgentRow page in the Shopify admin (the link and its status, and the way to the theme editor), the chat window settings in the theme editor, and in AgentRow: Integrations → Shopify stores (each linked store with its domain, status, last error and Unlink), the app's inbox and conversations, and every run's trace.
• The shopper sees the chat launcher on the store's pages, answers with product pictures and links, their cart changing when they ask, a checkout link and, when logged in, their own orders. On a support app a person can take over as on any website (The chat widget).

#Unlinking and uninstalling

• Unlink (Integrations → Shopify stores): store tools that use the store fail by name, and the storefront chat stops until the store is linked again from the AgentRow page in the Shopify admin. The app stays installed in Shopify.
• Uninstalling the app from Shopify removes AgentRow's access to the store at once and marks the store revoked on the Shopify stores tab; reinstalling restores the link.
• When Shopify asks for a shopper's data to be erased, that shopper's conversations and memory in the linked organisation are deleted. When it asks for the store's data to be erased, the store's link is removed.

#Not built yet

Planned, not available yet:

• syncing the store's products and policies into a knowledge base automatically;
• a store-assistant template and a setup wizard that create the app, agent, tools and Shopify store node for you;
• billing through Shopify, and a listing in the Shopify App Store;
• write actions such as return requests, behind approval;
• several stores in one app;
• event tools: tools that a website's own page answers through the chat window, on any website.

Until the sync exists, the store tools read products and policies live; add other store content, such as FAQs, to a knowledge base yourself (Knowledge bases).