Ruby Relay Chat Widget

Drop-in live chat for your website. One component, real-time conversations, fully customizable.

Prerequisites

• A Ruby Relay account with an API key
• A connected Slack workspace (conversations are routed to your team via Slack)

Quick Start

React

npm install ruby-relay-chat-widget

import { RubyRelayChat } from 'ruby-relay-chat-widget';

function App() {
  return (
    <RubyRelayChat
      apiKey="your-api-key"
      position="bottom-right"
      theme={{ preset: 'default' }}
    />
  );
}

CDN

<script src="https://cdn.rubyrelay.com/chat-widget/ruby-relay-widget.min.js"></script>

<script>
  window.RubyRelayConfig = {
    apiKey: 'your-api-key',
    position: 'bottom-right',
    theme: { preset: 'default' }
  };
</script>

Configuration

Required

| Option | Type | Description | |--------|------|-------------| | apiKey | string | Your Ruby Relay API key |

Optional

| Option | Type | Default | Description | |--------|------|---------|-------------| | clientID | string | null | Unique identifier for the user | | clientEmail | string | null | User's email address | | page | string | Current URL | Page context for the chat session | | position | string | 'bottom-right' | 'bottom-right', 'bottom-left', 'top-right', or 'top-left' | | welcomeMessage | string | 'Start a conversation!' | Placeholder text when the chat is empty | | headerTitle | string | 'Live Chat' | Chat window header text | | showSenderNames | boolean | true | Display sender names on messages | | defaultOpen | boolean | false | Open the chat window on page load | | debug | boolean | false | Enable debug logging to the console | | viewport | string | 'auto' | Responsive override: 'auto', 'desktop', or 'mobile' | | customLink | object \| null | null | Custom link in the header menu (see below) | | theme | object | null | Theme configuration (see below) |

Custom Link

Add a link to the header menu, perfect for pointing visitors to a help center or knowledge base.

{
  customLink: {
    text: 'Help Center',
    url: 'https://help.example.com'
  }
}

Pass customLink: null explicitly to disable the link and prevent server-side configuration from overriding it.

Themes

Start with a preset, override individual colors, or both. When you provide both, the preset applies first and your custom colors replace those values.

{
  theme: {
    preset: 'default',
    userMessageColor: '#007bff',
    chatBackgroundColor: '#ffffff',
    textColor: '#333333',
    headerColor: '#343a40'
  }
}

All colors must be hex format (#XXXXXX).

Presets

| Preset | Description | |--------|-------------| | default | Clean, professional blue | | light | Bright, minimal white | | dark | Modern dark mode | | minimal | Simple monochrome | | vibrant | Bold and colorful | | funk | Playful purple gradients | | deep | Rich, deep tones | | swiss | Clean red and white | | tosh | Elegant black and white |

Server-Side Configuration

Control your widget's appearance from the Ruby Relay dashboard, no client-side code changes required. Save your theme, position, header text, and other settings once, and they apply everywhere the widget is installed.

How it works:

1. Widget initializes and fetches configuration from the API
2. The widget stays hidden until the API responds (or retries exhaust)
3. Server config merges with any local props you provided
4. The widget renders with the final merged result

Merge priority: local props > server config > defaults.

Anything you pass directly (via props or window.RubyRelayConfig) wins. Properties you leave out fall through to your server-side values, then to defaults.

// Minimal setup. Theme, position, headerTitle, and everything else
// comes from your server-side configuration.
<RubyRelayChat apiKey="your-api-key" />

// Theme is set locally, so the server-side theme is ignored.
// But headerTitle, position, etc. still come from the server.
<RubyRelayChat
  apiKey="your-api-key"
  theme={{ preset: 'dark' }}
/>

If the API is unreachable, the widget retries up to 3 times, then renders with local props and defaults.

Instant rendering: When you provide all UI options locally (position, welcomeMessage, headerTitle, showSenderNames, defaultOpen, customLink, and theme), the widget renders immediately without waiting for the API. The connection resolves in the background.

Standalone Widget API

The CDN version exposes window.RubyRelayWidget for programmatic control:

// Manual initialization (alternative to window.RubyRelayConfig)
window.RubyRelayWidget.init({
  apiKey: 'your-api-key',
  position: 'bottom-left'
});

// Tear down and clean up
window.RubyRelayWidget.destroy();

TypeScript

Full type definitions ship with the package:

import { RubyRelayChat } from 'ruby-relay-chat-widget';
import type { WidgetConfig } from 'ruby-relay-chat-widget';

const config: WidgetConfig = {
  apiKey: 'your-api-key',
  position: 'bottom-right',
  theme: { preset: 'dark' }
};

function App() {
  return <RubyRelayChat {...config} />;
}

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+
• iOS Safari 14+
• Chrome Mobile

Support

• Website
• Help
• Email

License

MIT - see LICENSE for details.