Getting Started Guide ~8 min read

See What Your Shopify Customers Are Doing While You Reply

Converge Converge Team
•

A shopper messages you asking about a discount on "that black hoodie." Without context, you ask which one. With the Shopify connector enabled, you already see the exact product they are looking at, the size in their cart, and the running total — before you type a word. This guide covers the install, the one theme setting you have to fill in yourself, and what the sidebar panel shows.

Who can set this up? Connecting Shopify requires Owner Only permissions, and the Converge chat widget has to be enabled first — the Connectors section lives inside it. Once connected, every agent sees the live context panel in the customer sidebar.

What is a connector?

A connector is an external app that pushes live customer context into Converge — it is not a messaging channel. Shopify is the first connector. Future connectors (WooCommerce, Calendly, Stripe) follow the same pattern: they enrich the customer sidebar with data from the tool your shopper is using right now.

Converge already separates two ideas. Integrations are the platforms customers message you from — WhatsApp, Telegram, Messenger, Email, the embedded chat widget. Connectors are the apps that tell you what those same customers are doing outside the inbox.

Integration

Inbound message channel. Telegram, WhatsApp, Discord, the chat widget. Produces messages your team replies to.

Connector

External context source. Shopify today; more apps later. Pushes state (browsing, cart) into the sidebar without creating messages.

Success Check: You can explain in one sentence why a Shopify event in the sidebar is not the same thing as a Shopify message in the inbox.

What do agents see?

A "Shopify" row appears in the contact's Details sidebar, and clicking it expands the live context. The row itself carries a badge with the number of items in the cart and how long ago the last event arrived, so an agent can read the state without opening anything.

Now browsing

The product the shopper is currently viewing — image, title, price. On a non-product page the block becomes Current page instead, with the page title as a link you can open.

Cart

Line items with quantity and price, and the total in the store's currency. An add-to-cart shows the item that was added; the full itemized list arrives the moment the shopper opens their cart page.

The panel is read-only. Agents cannot edit the cart or apply discounts from inside Converge — that stays in Shopify. The goal is context, not control: agents see exactly what the shopper sees so the reply lands on the first try.

Pro Tip: When a customer asks an ambiguous question like 'how much is shipping on this?' check the Now browsing block before replying. You will almost always answer in one message instead of three.
Success Check: You know the panel shows the current page and the live cart, and that every agent sees it in their sidebar — not only the owner.

How does the Shopify connector work?

Two Shopify extensions feed the panel, and both run client-side on your storefront. The Converge Events web pixel sends shopper events to Converge. The Converge Chat theme app embed loads the chat widget and binds the visitor's identity to the events stream. Neither one can read your orders, customers, or products.

1

Customer browses the store

The Converge Events pixel subscribes to Shopify's standard customer events — page_viewed, product_viewed, cart_viewed, product_added_to_cart, product_removed_from_cart, checkout_started, search_submitted, collection_viewed.

2

Pixel beacons the event to Converge

Each event is sent via sendBeacon to a public endpoint. Events are attributed to your company by API Key, with an event-name allowlist, an 8 KB payload cap, and a per-key rate limit (20 events / 10 seconds).

3

Backend updates connector state

The event is mapped into a state patch (current product, current cart) and stored per visitor. Conversation history is not affected — this is sidebar state, not a message.

4

WebSocket pushes the update to agents

Once the state is linked to a Converge contact, a connector_state_changed event is broadcast to any agent viewing that customer. The sidebar panel re-renders without a page refresh.

How is the shopper linked to a Converge visitor?

The chat widget hands its visitor ID to a bridge script in the Converge Chat embed, which publishes it into Shopify's analytics layer. The Converge Events pixel picks it up and stamps that ID on every subsequent shopper event, which is how Shopify's anonymous client ID gets matched to the right Converge contact. Without the chat embed there is no ID to stamp, so events arrive with nowhere to show.

Success Check: You can name the two extensions (Converge Chat embed and Converge Events pixel) and explain why the connector does not need access to Shopify orders or customers.

How do I connect Shopify?

Owner Only

The install starts on Shopify, not in Converge. You install the Converge app on your store, approve two scopes, and Shopify sends you back to attach the store to your Converge account. Shopify only lets an app install its own web pixel through this flow, so there is no manual alternative.

  1. 1
    Open PlatformsWidgetConnectors

    In Converge, click the Platforms icon in the sidebar, open the Widget card, and scroll to the Connectors section at the bottom. It renders for owners only.

  2. 2
    Click "Install from Shopify App Store"

    This opens the Converge listing on the Shopify App Store. Install it on the store you want to connect. Starting the install from your Shopify admin instead works exactly the same way.

  3. 3
    Approve the two scopes

    Shopify shows its standard authorization screen asking for write_pixels and read_customer_events. Nothing else is requested — no orders, no customers, no products.

  4. 4
    Finish the link in Converge

    Shopify returns you to a Converge page that attaches the store. Sign in as the owner if you are prompted — the account you land in is the one the store is attached to. Converge then installs the Converge Events pixel and records your .myshopify.com domain.

  5. 5
    You land back on PlatformsWidget

    The Shopify card shows a green Connected badge next to your shop domain, and a toast offers an Open theme editor action — that is the last step (see the next section).

The Connectors section at the bottom of the Converge Widget platform page, showing the Shopify card and its Install from Shopify App Store button
Pro Tip: The link Shopify returns you on is single-use and expires. If you see "Connection link expired" or the connect fails after you approved, reopen the Converge app from your Shopify admin rather than reloading — that mints a fresh link.
Success Check: The Shopify card shows a Connected badge with your .myshopify.com domain, and a toast offers a one-click link to the theme editor.

How do I enable the chat embed?

Theme app embeds belong to your theme, not to the app, so Shopify makes you turn this one on yourself. The toast from the connect step deep-links straight to the right panel in the theme editor.

  1. 1
    Click "Open theme editor" in the toast

    A new tab opens on your current theme's App embeds panel with the Converge Chat embed activated.

  2. 2
    Paste your API Key into the embed

    The embed has its own API Key field, and it starts empty — the connect step sets the key on the events pixel, not on your theme. Copy the key from the embed snippet on PlatformsWidget (the data-api-key value) and paste it in. The widget does not load while the field is blank.

  3. 3
    Click Save in the theme editor

    The chat widget is now live on every page of your storefront, and the events pixel has been running since the connect step.

Converge Events is not in this list. It is an app pixel, which Shopify installs and runs on your behalf when you approve the scopes. There is nothing to toggle and no second key to paste — only Converge Chat appears under App embeds.

Success Check: You can see the Converge chat button on your live storefront and the App embeds panel shows Converge Chat enabled with your API Key filled in.

How do I verify it is working?

Open your storefront in one tab, your Converge inbox in another, and send a message to yourself. The Shopify panel should appear in your customer sidebar within seconds.

  1. 1
    Open the storefront in an incognito window

    An incognito window guarantees a fresh visitor ID, so the test conversation does not collide with any existing customer.

  2. 2
    Open the chat widget and send "test"

    Do this before you browse. Sending the first message is what creates the Converge contact that the shopping context attaches to.

  3. 3
    Browse a product and add it to the cart

    A product page fires product_viewed; adding an item fires product_added_to_cart. Open the cart page too, so the full itemized cart is sent.

  4. 4
    Open the conversation and expand the Shopify row

    In the Details sidebar, click Shopify. You should see the product you viewed under Now browsing and the item you added under Cart.

  5. 5
    Navigate to a different product

    The Now browsing block should update within a second or two without you reloading the inbox.

If nothing appears: check that the Converge Chat embed is toggled on with your API Key saved, that the Shopify card in Converge still shows Connected, and that you are testing on the published storefront rather than a theme preview link.

Success Check: Browsing to a new product on the storefront updates the Now browsing block in the Converge sidebar within seconds.

Best practices

Enable the widget before you connect

The Connectors section only renders inside an enabled Converge widget integration. If you cannot find it on PlatformsWidget, turn the widget on first.

Finish the chat embed, not only the connect

The connect step gets you the events pixel. Without the chat embed and its API Key, events arrive with no conversation to attach them to and the sidebar stays empty.

Keep the chat embed's key in sync

The embed stores a copy of your Widget API Key. If that key ever changes in Converge, paste the new one into the theme embed or the widget stops loading on your storefront.

Check Now browsing before answering ambiguous questions

If a shopper writes "is this in stock?" with no link, look at the panel first. It is faster than asking and the customer feels understood.

Disconnect cleanly when leaving Shopify

If you stop using the connector, click the delete icon on the Shopify card in Converge. That removes the stored token and every saved context snapshot. Uninstall the Converge app inside Shopify too, so the pixel stops firing.

Frequently Asked Questions

What is the difference between a connector and an integration in Converge?
Integrations are inbound messaging channels — WhatsApp, Telegram, Email, the chat widget. Connectors are external apps that push customer context into the sidebar, like Shopify showing the current product and cart. Connectors never become a message source; they only enrich what agents see while replying.
Does Converge read my Shopify orders or customers?
No. The app requests two scopes, write_pixels and read_customer_events, and uses the Admin API once — to install the Converge Events pixel on your store. It has no read access to orders, customers, products, or inventory. Everything the agent sees comes from the two storefront extensions, which run client-side.
What does the agent see in the Shopify sidebar panel?
A collapsible Shopify row in the contact's Details sidebar, badged with the number of items in the cart and how long ago the last event arrived. Expanding it shows Now browsing (product image, title, price) — or Current page when the shopper is not on a product — and Cart, with each line's quantity and price plus the total. It re-renders live on the connector_state_changed WebSocket event.
Where does the Shopify install start?
On Shopify. You install the Converge app from the Shopify App Store, approve the two scopes, and Shopify returns you to Converge to attach the store to your company. There is no way to start the connection by typing your domain into Converge, and no manual pixel install — Shopify only lets an app install its own web pixel through OAuth.
Do I still have to paste an API Key anywhere?
Yes, once — into the Converge Chat theme app embed. OAuth installs the Converge Events pixel with your key already set, but the chat embed belongs to your theme, not to the app, so it keeps its own API Key field. The widget does not load until that field is filled. Copy the key from the embed snippet on PlatformsWidget.
Who can connect Shopify in Converge?
Only the account owner. The Connectors section sits at the bottom of PlatformsWidget and renders for owners only. Admins and agents see the live customer context in the sidebar but cannot add, remove, or reconfigure connectors.
Can the pixel see the wrong company's customers?
No. Each event is attributed to a company by the Converge API Key in the pixel settings. The pixel runs per-store and is rate-limited per key plus shopify client ID, with an event-name allowlist and an 8 KB payload cap. Worst case is write-only nuisance context scoped to a single store.

What's next?

The Shopify connector is live. Here are related guides that pair well with it:

  • Widget Guide — customize the chat widget that the Shopify embed loads on your storefront
  • Replies Guide — set up quick replies that reference the customer's current product or cart
  • Inbox Guide — find the customer sidebar, filters, and bulk actions that surround the Shopify panel

Need more help?

Our support team is here for you. Click the chat widget in the bottom right corner to start a conversation.

We typically respond within minutes during business hours.