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>

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.