Getting Started with the Shopify Connector: Live Cart and Browsing Context for Support

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, Gmail, 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" panel appears in the customer detail sidebar with two blocks: Now browsing and Cart. Both update in real time as the customer navigates your store — no refresh, no manual lookup.

Now browsing

The product the shopper is currently viewing — image, title, price. If they navigate to a different product or a collection page, the block updates within a second.

Cart

Itemized list with quantity, unit price, and a running total. Adding or removing items in another tab updates the panel for the agent watching that conversation.

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 — both run client-side, with no Shopify Admin API access. The Converge Events web pixel sends shopper events to Converge. The Converge Chat theme app embed loads the chat widget on the storefront and binds the visitor's identity to the events stream.

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

A connector_state_changed event is broadcast to any agent currently viewing that customer. The sidebar panel re-renders without a page refresh.

How is the shopper linked to a Converge visitor?

The chat widget emits a converge:visitor browser event with its visitor ID. A bridge script in the Converge Chat theme embed forwards this to Shopify's analytics layer as converge_visitor_bound. The Converge Events pixel listens for that bind event and stamps the visitor ID on every subsequent shopper event. The backend uses that ID to link Shopify's anonymous clientId to the right Converge customer.

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 with OAuth?

Owner Only

OAuth is the recommended path because it installs the Converge Events pixel for you in one click. You still have to enable the chat embed manually — Shopify theme app embeds are merchant-activated, that is a platform constraint, not a Converge one.

1
Open PlatformsConnectorsShopify
In Converge, click the Platforms tab, then in the Connectors section select Shopify. The setup card is owner-only.
2
Enter your .myshopify.com domain
Type your authoritative Shopify domain (e.g. mystore.myshopify.com). This is the only value Shopify will accept for the OAuth handshake.
3
Click "Connect Shopify"
You are redirected to Shopify to approve two scopes: write_pixels and read_customer_events. Nothing else is requested.
4
Approve on Shopify
Shopify shows the standard app authorization screen. Once you approve, Converge exchanges the code for a token, installs the Converge Events pixel automatically (webPixelCreate), and stores the authoritative shop domain.
5
You land back in Converge
The Shopify card now shows a green Connected badge. A toast appears with an Open theme editor action — that is the last step (see the next section).

Converge Connectors section showing the Shopify card with the .myshopify.com domain input and the Connect Shopify button

Pro Tip: If you see an error like 'Connected, but installing the events pixel failed' click Connect Shopify again. The reconnect retries the webPixelCreate step without reauthorizing the scopes.

Success Check: The Shopify card in Connectors shows a Connected badge and the toast offers a one-click link to the theme editor.

How do I enable the chat embed?

Shopify requires merchants to toggle theme app embeds on themselves — Converge cannot do this for you. The OAuth toast gives you a deep link straight to the right place in the theme editor, so it really is one click.

1
Click "Open theme editor" in the toast
A new tab opens directly on your current theme's App embeds panel, with the Converge Chat embed selected.
2
Toggle the Converge Chat embed on
The API Key is already populated from the OAuth flow. You do not need to paste anything.
3
Click Save in the theme editor
The chat widget is now live on every page of your storefront, and the events pixel is already running from the OAuth step.

Pro Tip: If you lost the toast, find the deep link on the connector card in Converge — it is regenerated from your stored shop domain so it always opens the right editor.

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

How do I connect without OAuth?

If you decline the OAuth scopes, use the "Connect without OAuth" link on the Shopify card. You will install both extensions yourself and paste the same API Key into each. The end result is identical — agents see the same live context panel.

1
Enter your shop domain in Converge
On the Shopify card, click Connect without OAuth and type your store domain (e.g. mystore.com or mystore.myshopify.com). It is normalized and used only as a display label, so a typo will not break anything.
2
Install the Converge app from the Shopify App Store
Search for "Converge" and install it on your store.
3
Open Online StoreThemesCustomizeApp embeds
You will see two embeds: Converge Chat and Converge Events. Toggle both on.
4
Paste the same API Key into both embeds
Copy the API Key from SettingsWidget in Converge. Paste it into the API Key field of both Converge Chat and Converge Events — they must match.
5
Click Save in the theme editor
Both the widget and the events pixel are now active.

Why the domain is metadata, not a credential: events are attributed to your company by API Key. The web pixel runs in Shopify's sandbox, so the beacon's Origin header is a Shopify URL — the shop domain in the event body is informational only. A wrong domain never silently breaks context.

Success Check: Both Converge Chat and Converge Events are toggled on in your theme editor, with the same API Key pasted into each.

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
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
Navigate to any product page
This fires product_viewed. Add one item to the cart to fire product_added_to_cart.
3
Open the chat widget and send "test"
This creates a Converge customer linked to the same visitor ID the pixel is using.
4
Open the conversation in your Converge inbox
The Shopify panel should appear in the sidebar with the product you viewed under Now browsing and the item you added under Cart.
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: double-check that both theme app embeds are toggled on, that both have the same API Key, and that you are testing on the storefront where the embeds are saved (not a 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

Prefer OAuth over manual setup

The OAuth path installs the events pixel and binds the authoritative shop domain in one step. Manual setup is a true fallback — use it only if you decline the scope grant.

Always enable both embeds

Converge Chat alone gives you a widget without context. Converge Events alone gives you context the agent cannot link to a conversation. You need both for the sidebar panel to populate.

Reuse the same API Key

Both theme embeds and the connector card all reference the same Widget API Key. Rotating the key in SettingsWidget breaks the pixel until you update both embeds to match.

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. This removes the stored token; you should also disable or uninstall the Converge app inside Shopify to stop the pixel from firing.

Frequently Asked Questions

What is the difference between a connector and an integration in Converge?

Integrations are inbound messaging channels — WhatsApp, Telegram, Gmail, 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 need Shopify Admin API access?

No. The Shopify connector uses two client-side extensions: the Converge Events web pixel and the Converge Chat theme app embed. Both run in Shopify's sandbox. The OAuth flow only requests write_pixels and read_customer_events — there is no read access to orders, customers, or inventory.

What does the agent see in the Shopify sidebar panel?

Two live blocks: Now browsing (product image, title, price for the page the shopper is currently on) and Cart (line items with quantities, prices, and total). Both update in real time as the customer navigates the store, driven by the connector_state_changed WebSocket event.

Do I have to use OAuth to connect Shopify?

No. OAuth is the recommended path because it installs the events pixel automatically. If you decline the scope grant, the manual fallback works identically — you install the Converge app, toggle on the Converge Chat and Converge Events embeds in your theme editor, and paste the same API Key into both.

Why does the manual setup ask for a domain if it does not have to match exactly?

Pixel events are attributed to your company by API Key, not by domain. The domain you type is shown to agents as a label so they recognize which store the context comes from. Typing the wrong domain will never block events or break the cart panel.

Who can connect Shopify in Converge?

Only the account owner. Connector setup lives under PlatformsConnectorsShopify and is gated to the owner role. Admins and agents see the live customer context 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.

See What Your Shopify Customers Are Doing While You Reply