Relay SDK

This page covers the small client-side SDK for the Relay chat widget. Use window.$relay.push(...) when you want to pass customer context into the widget or control it from your site.

Start with the queue

Initialize the queue once on pages where you want to talk to the widget:

<script>
  window.$relay = window.$relay || []
</script>

You can push commands before or after the widget script loads. Relay will process the queued commands when the widget is ready.

Identify the visitor

Use identify as soon as your site knows who the visitor is. This lets Relay attach the session to the right contact and shop context.

<script>
  window.$relay = window.$relay || []

  window.$relay.push([
    "identify",
    {
      name: "Jane Doe",
      email: "[email protected]",
      shopName: "acme.myshopify.com",
      data: {
        plan: "Plus",
        shopifyUserId: "1234567890",
        shopifyShopDomain: "acme.myshopify.com"
      },
      segments: ["VIP", "Beta"]
    }
  ])
</script>

The most useful fields are:

• name: the visitor name you want to show in Relay
• email: the visitor email
• shopName: the store or shop name
• data: custom attributes you want Relay to keep on the contact
• segments: segment names to assign to the contact

If you only know the basics, keep it simple:

<script>
  window.$relay = window.$relay || []
  window.$relay.push(["identify", { email: "[email protected]", name: "Jane Doe" }])
</script>

Assign segments only

If you only want to assign segments and do not want to send name, email, or shop name yet, push an identify payload with just segments:

<script>
  window.$relay = window.$relay || []

  window.$relay.push([
    "identify",
    {
      segments: ["VIP", "Beta", "Wholesale"]
    }
  ])
</script>

This is the smallest supported way to tag a visitor with Relay segments from the widget SDK.

Open, close, or toggle the chat

You can also control the widget from buttons, links, or app events:

<script>
  window.$relay = window.$relay || []

  window.$relay.push(["open"])
  window.$relay.push(["close"])
  window.$relay.push(["toggle"])
</script>

Hide or show the widget

Use hide and show when you need the widget bubble to disappear temporarily — for example, when one of your own modals would be obscured by the launcher on mobile.

<script>
  window.$relay = window.$relay || []

  window.$relay.push(["hide"])
  window.$relay.push(["show"])
</script>

Hiding the widget removes both the launcher and the chat panel from the page. Showing it brings them back without losing the conversation.

A common pattern is to wire this into your modal lifecycle:

<script>
  const modal = document.querySelector("#bulk-edit-modal")

  modal.addEventListener("open", () => window.$relay.push(["hide"]))
  modal.addEventListener("close", () => window.$relay.push(["show"]))
</script>

Move the widget at runtime

The widget defaults to bottom-right. You can switch it to bottom-left (or back) at any time with position:

<script>
  window.$relay = window.$relay || []

  window.$relay.push(["position", "bottom-left"])
  window.$relay.push(["position", "bottom-right"])
</script>

If you only need to set the position once at install time, use the data-widget-position script attribute instead — see Chat widget.

A full widget example

This is a common pattern when you already know the signed-in customer before the widget loads:

<script>
  window.$relay = window.$relay || []

  window.$relay.push([
    "identify",
    {
      name: "Jane Doe",
      email: "[email protected]",
      shopName: "acme.myshopify.com"
    }
  ])
</script>

<script
  src="https://app.superrelay.ai/widget/widget.js"
  data-relay-token="YOUR_WIDGET_TOKEN"
  data-relay-api-url="https://YOUR_API_HOST"
  defer
></script>

If you are still installing the widget itself, go back to Chat widget.