Skip to main content
VoiceAgentby AZ Digital

Merchant documentation

Set up and operate VoiceAgent

A practical guide to configuring the storefront assistant, testing it safely, understanding its limits, and managing review data.

Last updated: October 4, 2026

Before activation

  1. Install through Shopify. Complete Shopify's app installation and permission flow for the intended store.
  2. Confirm store eligibility. Confirm the store and voice experience are directed only to adults, maintain legally required age and market controls, and accept responsibility for current provider terms and applicable law. A current confirmation is recorded immediately; no separate AZ Digital approval is required.
  3. Review synchronized knowledge. Confirm products, collections, legal policies, and approved FAQs are current. The app rechecks live Shopify storefront data before product and cart actions.
  4. Configure the agent. Choose the supported language behavior, one of the available launch voices, response style, privacy review mode, retention, and usage stops.
  5. Test before publishing. Complete a successful test conversation, switch on the “Voice agent” app embed in your theme, save the theme, then open a normal storefront page so the app can observe the live runtime.

Language support

Typed answers follow the shopper’s language. Voice can follow the shopper’s language or always speak one language you choose. Product searches translate general keywords into the store catalog language while preserving brands, model numbers and SKUs. Test the languages used by your shoppers; quality can vary.

Shopper controls

A shopper starts microphone use explicitly, can interrupt or end a session, and must separately confirm every proposed cart mutation.

Session limits

A voice connection lasts up to 3 minutes and 20 turns, and a typed conversation answers up to 10 questions. Idle, no-speech, usage, concurrency, cost, abuse, provider, and technical stops also apply. Accessible timing can be enabled without changing the hard session and safety limits.

Billing and usage

The Usage page reports connected voice minutes, completed typed answers and estimated app charges. Shopify hosts plan approval and remains the source of the final bill.

Add information outside Shopify

Open Knowledge and choose Add answer, or pick a topic starter such as Pickup and hours. Write the question shoppers ask and the answer you want the assistant to give, for example contact hours, care instructions, compatibility, pickup details or gift services. Choose Publish answer to make it live, or Save without publishing to keep it private. Under More options you can set the answer's language, add other ways shoppers ask, choose a date to stop showing it, add a source link or import the text from a UTF-8 text or Markdown file.

A live answer keeps its published version until you choose Publish changes. You can unpublish or delete an answer from its page, and you can keep up to 100 answers. A source link is for your reference only; the app does not crawl it. Current Shopify prices, stock and policies take priority over a store answer.

What the assistant can do

  • Search and compare published storefront products.
  • Explain current product facts and current store policies when the source is available.
  • Open products and hand shoppers to the store contact route.
  • Propose cart actions and perform them only after a fresh, explicit shopper confirmation and server-side revalidation.
  • Provide anonymous outcome, quality, usage, and protection analytics without claiming that the app caused a sale.

What is not supported

  • Customer profiles, order history or status, refunds, cancellations, order changes, payment data, or customer-account authentication.
  • Checkout-page extensions, phone calls, SMS, or WhatsApp.
  • Cart actions everywhere. They work only in stores that sell in USD, JPY, or KRW, for shoppers who are not signed in, and for ordinary one-time purchases. They do not cover subscriptions, bundles, customized items, or products with quantity rules or volume pricing. Outside those cases the assistant still shows products and links, and shoppers use the store's own cart buttons.
  • Medical, legal, compliance, age-verification, or product-suitability advice.
  • Automatic cart changes, unconfirmed purchases, or claims that an app interaction generated revenue.

Voice privacy and review retention

After a shopper starts voice mode, microphone audio and generated audio are processed by Google Gemini or OpenAI according to the saved voice. Typed chat uses OpenAI. VoiceAgent does not retain raw audio or source-language transcripts in its server database, logs, or analytics. A temporary encrypted conversation memory lets the assistant follow up within a conversation and expires with it. Provider-side processing and retention, and that memory, are described in the privacy policy.

OpenAI voice uses analytics only. Google voice configurations can optionally retain a redacted English summary or redacted English turn review retained for 7, 30, or 90 days. Anonymous operational accounting and aggregate analytics use separate retention periods.

The widget stores a signed, shop-bound anonymous device token in the shopper's browser for up to 30 days. It supports device-level abuse and usage limits and is not a Shopify customer-account login.

Redacted display messages and public product cards stay in the same browser tab across page changes for up to 30 minutes of inactivity. End conversation clears this history. After a page change, select Resume voice to reconnect the microphone; typed chat can continue with the next message. A bounded set of recent redacted messages helps the assistant understand follow-up questions after reconnecting.

Troubleshooting

The widget does not appear

Confirm the current eligibility checklist is complete, the latest configuration is active, the theme app embed is enabled and saved, the page type is allowed, and a normal storefront page was opened outside the Theme Editor within the last 15 minutes.

A voice session will not start

Check microphone permission, store and plan usage stops, concurrency, provider availability, eligibility state, required Shopify scopes, and the status information. A blocked start should fail closed rather than silently changing providers or models.

Product information looks stale

Select Check again in Knowledge and verify the item is published to the Online Store. The assistant should avoid presenting a fact that cannot be verified from current Shopify data.

More help

Follow the safe ticket guidance on the support page.