Omnix
Home Embed Web Chat

Client Integration: Embed Web Chat

Omnix includes a client-side Web Chat widget that you can embed on any public website or customer portal. This guide details how to install the snippet, customize its behavior, and pre-fill contact identity to match authenticated users.

1. Quick Start Snippet

Copy and paste this snippet right before the closing </body> tag on your website:

  • workspaceId: Your unique tenant/subscription workspace ID.
  • channelId: The specific Web Chat channel ID configured in your Channels panel.

2. Pre-filling Contact Identity

If your website contains a user login session, you can pass known contact fields (name, email, phone) to the widget on initialization. This avoids forcing users to re-fill their details, and maps their chats to their existing Omnix CRM record.

omnix('init', {
  workspaceId: "ws_abc123",
  channelId: "chn_webchat_998877",
  contact: {
    identifiers: {
      email: "[email protected]",
      phone: "+15551234567"
    },
    profile: {
      firstName: "Jane",
      lastName: "Smith"
    },
    context: {
      membershipTier: "premium",
      accountId: "acc_94812"
    }
  }
});
  • identifiers: Used to match the user in the Omnix CRM. If matched, their previous chat history is loaded securely.
  • context: Key-value metadata that is stored on the contact profile. Your agents can view these values directly in the Unified Inbox.

3. Widget Customization Options

You can pass extra parameters to the initialization config to control branding and behavior:

omnix('init', {
  workspaceId: "ws_abc123",
  channelId: "chn_webchat_998877",
  config: {
    theme: "dark", // "light" | "dark" | "system"
    primaryColor: "#4f46e5",
    greetingMessage: "Hello! How can we help you today?",
    position: "right", // "left" | "right"
    launcherIcon: "bubble", // "bubble" | "support" | "arrow"
    showAgentAvatars: true
  }
});

4. Javascript API (Events & Actions)

The widget exposes functions you can trigger from your website code:

Open or Close the Widget

// Open the chat box
omnix('open');

// Close the chat box
omnix('close');

// Toggle state
omnix('toggle');

Listen to Widget Events

// Triggered when a new message is received from an agent
omnix('on', 'message_received', function(message) {
  console.log("New message from agent:", message.text);
});

// Triggered when the user opens the widget window
omnix('on', 'widget_opened', function() {
  console.log("Chat window opened");
});