Live Chat SDK - Relay Pilot

Overview

Once installed, the Relay Pilot widget exposes a global function:

code

relaychat()

You can use this function to:

Open or close the chat window
Hide or show the widget
Pass visitor information
Listen for events (messages, unread count, open/close, etc.)
Fully remove the widget from the page

Basic Installation

Add the following embed code to your website, ideally just before the closing </body> tag.

html

<script>
  (function(w,d,s,f,js,fjs){
    w.relaychat = w.relaychat || function(){
      (w.relaychat.q = w.relaychat.q || []).push(arguments)
    };
    js = d.createElement(s);
    fjs = d.getElementsByTagName(s)[0];
    js.id = 'relay-chat';
    js.src = f;
    js.async = 1;
    fjs.parentNode.insertBefore(js, fjs);
  })(window, document, 'script', 'https://app.relaypilot.io/widget/relay-chat.js');

  relaychat('init', {
    widgetId: 'YOUR_WIDGET_ID'
  });
</script>

Replace YOUR_WIDGET_ID with the Widget ID found in your Relay Pilot dashboard.

Opening & Closing the Widget

code

relaychat('open');    // Open the chat window
relaychat('close');   // Close the chat window
relaychat('toggle');  // Toggle open / closed

Example: Custom Chat Button

html

<button onclick="relaychat('open')">
  Chat with us
</button>

Hiding & Showing the Widget

Hide or show the widget without destroying it:

code

relaychat('hide');   // Hide widget completely
relaychat('show');   // Show widget again

Example: Hide Chat on Checkout Page

code

if (window.location.pathname === '/checkout') {
  relaychat('hide');
}

Removing the Widget Entirely

Completely removes the widget from the page and memory.

code

relaychat('shutdown');
// or
relaychat('destroy');

Use this only if you do not plan to re-enable the widget.

Passing Visitor Information

During Initial Load

code

relaychat('boot', {
  widgetId: 'YOUR_WIDGET_ID',
  visitor: {
    name: 'John Smith',
    email: 'john@example.com'
  }
});

Updating After Load

code

relaychat('update', {
  visitor: {
    name: 'Jane Doe',
    email: 'jane@example.com'
  }
});

This is useful when a user logs in or updates their profile.

Checking Widget State

code

relaychat('isOpen');     // true / false
relaychat('isReady');    // true / false
relaychat('getState');   // Full state object

Example response:

code

{
  isOpen: false,
  isReady: true,
  isHidden: false,
  isOnline: true,
  unreadCount: 2,
  conversationId: 'abc-123',
  view: 'home'
}

Events

Subscribe to widget events using:

code

relaychat('on', EVENT_NAME, callback);

Available Events

Widget Ready

code

relaychat('on', 'ready', function(state) {
  console.log('Chat widget is ready');
});

Chat Opened

code

relaychat('on', 'open', function() {
  console.log('Chat opened');
});

Chat Closed

code

relaychat('on', 'close', function() {
  console.log('Chat closed');
});

New Message

code

relaychat('on', 'message', function(message) {
  console.log('New message:', message.body);
});

Unread Count Changed

code

relaychat('on', 'unreadCount', function(data) {
  console.log('Unread messages:', data.count);
});

Removing Event Listeners

typescript

function myHandler(data) {
  // ...
}

relaychat('on', 'message', myHandler);
relaychat('off', 'message', myHandler);

Common Implementation Examples

Auto-Open Chat on Contact Page

code

relaychat('on', 'ready', function() {
  if (window.location.pathname === '/contact') {
    relaychat('open');
  }
});

Show Chat Only After Login

code

relaychat('init', { widgetId: 'YOUR_WIDGET_ID' });
relaychat('hide');

function onLogin(user) {
  relaychat('update', {
    visitor: {
      name: user.name,
      email: user.email
    }
  });

  relaychat('show');
}

Custom Unread Badge

code

relaychat('on', 'unreadCount', function(data) {
  document.getElementById('my-badge').textContent =
    data.count > 0 ? data.count : '';
});

React Example

code

useEffect(() => {
  const handleUnread = (data) => setUnreadCount(data.count);

  window.relaychat('on', 'unreadCount', handleUnread);

  return () => {
    window.relaychat('off', 'unreadCount', handleUnread);
  };
}, []);

Troubleshooting

Ensure the embed script loads before calling relaychat()
Confirm your Widget ID is correct
Check browser console for JavaScript errors
Verify no ad blockers or CSP rules are blocking the widget script