IntegrationsShopify

Chat Widget Tutorial

This guide adds the floating Octocom chat widget to a Shopify store using the app embed — no code and no script tag required.

Enable the app embed in your theme. Connecting Shopify automatically adds the storefront domains to Octocom; if the widget does not appear, verify those domains under Web Chat settings using the checks below.

Revenue tracking

Connecting or reconnecting Shopify automatically activates Octocom's checkout tracking for that store. No custom checkout script is required. Additional stores connected to the same business each get their own activation.

The Metrics -> Sales tab is available to everyone with metrics access and is shown by default. If you previously hid it, show it again in your Metrics tab preferences.

Purchase attribution requires a shopper who has opened Octocom chat in the same browser and a completed Shopify checkout. Tracking respects Shopify's analytics consent, so not every checkout is recorded. It starts with future eligible checkouts; it does not import historical orders.

When Shopify reports the order, the purchase also stores its numeric Shopify order ID as order_id, the ID the Admin API uses in gid://shopify/Order/<order_id>. Use it to match attributed purchases to Shopify orders, for example in conversation_purchase_index. Purchases recorded before this was added have no order ID.

If Shopify reports a tracking activation error during connection, check the app's permissions and reconnect. Contact Octocom if tracking is missing on a store connected before automatic activation was introduced.

Logged-in customer detection

The Shopify app embed automatically passes a logged-in storefront customer's email, full name and Shopify customer ID to Octocom. New conversations are associated with that customer instead of appearing anonymous. No custom JavaScript setting or theme edits are needed.

The widget uses Shopify's Liquid customer object. This applies to Shopify-rendered theme pages where the embed is enabled, including the inline chat embed. Headless storefronts need to supply their own customer context.

Local storage keyConversation metadata keyPurpose
octocom:data:emailchat-widget:emailAlso sets the Octocom customer's email
octocom:data:namechat-widget:nameAlso sets the Octocom customer's display name
octocom:data:shopify_customer_idchat-widget:shopify_customer_idShopify's numeric customer ID, stored as a string
octocom:data:shopify_shop_domainchat-widget:shopify_shop_domainPermanent .myshopify.com store domain

Customer context is available in memory at startup. It is persisted when the visitor opens chat. If chat was used previously, the extension also reconciles the existing stored identity on startup. Logged-out visitors have no automatic customer email, name or Shopify customer ID.

The extension clears customer identity immediately when a standard Shopify logout link or form is used. It rechecks Shopify-rendered HTML when the page regains focus, becomes visible, is restored from browser history, and every 30 seconds while visible. This also picks up logins or account switches that happen without a full page reload. Detection from an asynchronous login is eventual, not an instantaneous Shopify login event. If the account changes, Octocom starts a fresh chat session and removes the previous customer's history from the widget. The same account keeps its chat across page loads.

Custom themes can request a fresh check after their own login or logout flow:

document.dispatchEvent(new Event("octocom:refresh-customer"));

Network failures or pages without the customer marker leave the last known identity unchanged. The extension manages the four keys above; unrelated custom metadata is preserved. Automatic Shopify values take precedence over conflicting URL or custom-script values for these keys.

Copilot and Python actions can use the metadata for customer lookups. See Shopify Custom Actions. This browser context can be edited by the visitor. For sensitive account data or changes, use the appropriate customer authentication.

Store requirements

A Shopify subscription is not required to launch the widget. You can pay by invoice, Stripe, or another arrangement with our team. During onboarding, choose I'll be paying via another method to continue without subscribing through Shopify. Connecting a store to an existing account does not require a new plan.

This only works on Shopify-hosted storefronts

The app embed is injected by your Shopify theme, so it only runs on pages Shopify renders — your .myshopify.com storefront and any custom domain pointed at it.

If your storefront is a headless / custom build (Hydrogen, Next.js, or any site that only uses Shopify for checkout or order data), the theme editor has no effect on it. Add the widget with a script tag instead, following Launch Chat Widget.

Stores often run both: for example a custom site on example.com that syncs orders to a Shopify storefront on us.example.com. In that setup the app embed covers us.example.com only, and example.com needs the script tag. Not sure which you have? Open the page and view source — Shopify-rendered storefronts include cdn.shopify.com asset URLs.

1. Enable the app embed

  1. Navigate to your Shopify store's admin page.

  2. Under "Sales channels" click "Online store".

  3. Select the theme you'd like to add the widget to, then click "Customize".

  4. In the left sidebar, click "App embeds".

  5. Enable the widget.

  6. Save your theme.

Octocom isn't listed under App embeds

Install the Octocom app on that specific store, then reopen the theme editor. Each Shopify store needs its own installation. You do not need to approve a Shopify subscription for the widget to appear.

If it is still missing, contact your account manager for help.

2. Whitelist your storefront domain

The widget will only render on domains you have explicitly allowed. This step applies to Shopify exactly as it does to any other site — the app embed loads Octocom, and Octocom then checks the domain before showing anything.

  1. Go to the Octocom Dashboard.
  2. Navigate to Settings → Channels → Web Chat → Deployment.
  3. Add the domain your customers actually visit — the storefront domain shown in the browser address bar (for example example.com), not your example.myshopify.com admin domain.
  4. Enable deployment using the toggle, and click Save.

Octocom web chat settings

Each hostname needs its own entry

Domains are matched by exact hostname, so every storefront hostname you want the widget on has to be listed separately:

  • example.com and us.example.com are different hostnames — list both.
  • www.example.com and example.com are treated as the same, so you only need one of them.
  • Locale paths on one hostname (example.com/us/, example.com/nl/) are all covered by that single entry.

3. Verify it works

Open your storefront in a private/incognito window and confirm the chat launcher appears. If it doesn't:

What you seeLikely cause
Widget missing on a Shopify pageDomain not whitelisted, or deployment toggle off — recheck step 2
Widget missing on one domain but working on anotherThat hostname isn't in the Deployment list
Widget missing on your main site, working on the Shopify oneMain site is a custom storefront — use the script tag guide
Octocom missing from App embedsApp not installed on that store — see the callout in step 1
Widget appears in the theme editor preview but not liveTheme changes weren't saved, or you published a different theme

You can also restrict the widget to specific pages (for example /faq or /contact) from the same Deployment tab.

On this page