Web Messenger Javascript Api

This document covers the FlowXO JavaScript API for programmatic control of the chat widget.

Getting Started

Most integrations only need a few lines of code. Here are the most common patterns:

Basic Setup with User Identity

Use window.onFlowXOInit to configure the widget and identify users before it connects:

<script>
  window.onFlowXOInit = async (connectionId) => {
    // Fetch user data from your backend
    const user = await fetchCurrentUser();

    return {
      member: user
        ? {
            id: user.id,
            name: user.displayName,
            email: user.email,
            metadata: {
              plan: user.plan,
              company: user.company,
            },
          }
        : undefined,
      config: {
        primaryColor: '#4F46E5',
        header: {
          title: 'Support',
        },
      },
    };
  };
</script>
<script
  src="https://messenger.flowxo.com/loader.js"
  data-connection="your-connection-id"
></script>

Auto-Open After Delay

Use the flowxo:ready event to interact with the widget after it initializes:

<script>
  document.addEventListener('flowxo:ready', (event) => {
    const { connectionId } = event.detail;

    // Open the widget after 30 seconds
    setTimeout(() => {
      FlowXO.open(connectionId);
    }, 30000);
  });
</script>
<script
  src="https://messenger.flowxo.com/loader.js"
  data-connection="your-connection-id"
></script>

Track Widget Events

Listen for user interactions and messages:

FlowXO.on('open', ({ connectionId }) => {
  analytics.track('widget_opened', { connectionId });
});

FlowXO.on('userMessage', ({ connectionId, message }) => {
  console.log('User sent:', message);
});

FlowXO.on('agentMessage', ({ connectionId, message }) => {
  // Show notification if widget is closed
  if (!FlowXO.isOpen(connectionId)) {
    showNotification('New message from support');
  }
});

Update User Identity on Login/Logout

// When user logs in
document.getElementById('login-btn').addEventListener('click', async () => {
  const user = await loginUser();
  FlowXO.identify({
    id: user.id,
    name: user.name,
    email: user.email,
  });
});

// When user logs out
document.getElementById('logout-btn').addEventListener('click', () => {
  FlowXO.logout();
});

Global API

The FlowXO API is exposed on window.FlowXO after the loader script initializes.

FlowXO.init(options)

Programmatically initialize a new widget instance. Use this for manual control instead of auto-initialization via data-connection attributes.

const widget = await FlowXO.init({
  connectionId: 'your-connection-id',
  config: {
    // Optional: configuration overrides
    primaryColor: '#6F5FE8',
  },
  user: {
    // Optional: user identity
    id: 'user-123',
    name: 'John Doe',
    email: 'john@example.com',
  },
});

Parameters:

Returns: Promise<WidgetInstance | undefined>

FlowXO.identify(member) / FlowXO.identify(connectionId, member)

Identify a user for personalization and conversation continuity.

// Single widget (uses first/default instance)
FlowXO.identify({
  id: 'user-123',
  name: 'John Doe',
  email: 'john@example.com',
  avatar: 'https://example.com/john.jpg',
  metadata: {
    plan: 'premium',
    signupDate: '2024-01-15',
  },
});

// Multiple widgets (specify connection ID)
FlowXO.identify('connection-id-1', {
  id: 'user-123',
  name: 'John Doe',
});

Member Properties:

Alias: FlowXO.setUser() - identical functionality

FlowXO.logout(connectionId?)

Clear user identity and optionally start a new conversation.

// Single widget
FlowXO.logout();

// Multiple widgets
FlowXO.logout('connection-id-1');

Alias: FlowXO.clearUser() - identical functionality

FlowXO.open(connectionId?)

Open the widget.

FlowXO.open();
FlowXO.open('connection-id-1'); // For multiple widgets

FlowXO.close(connectionId?)

Close the widget.

FlowXO.close();
FlowXO.close('connection-id-1'); // For multiple widgets

FlowXO.toggle(connectionId?)

Toggle the widget open/closed.

FlowXO.toggle();
FlowXO.toggle('connection-id-1'); // For multiple widgets

FlowXO.isOpen(connectionId?)

Check if the widget is currently open.

if (FlowXO.isOpen()) {
  console.log('Widget is open');
}

Returns: boolean

FlowXO.setConfig(config, connectionId?)

Update widget configuration at runtime. Changes are merged with existing config and persisted to local storage.

FlowXO.setConfig({
  primaryColor: '#FF5733',
  header: {
    title: 'Updated Title',
  },
});

Launcher Customization

Customize the launcher button appearance at runtime:

// Use a custom image as the launcher (full mode)
FlowXO.setConfig({
  launcher: {
    mode: 'full',
    shape: 'rounded',
    iconUrl: 'https://example.com/mascot.png',
    closeIconUrl: 'https://example.com/close.png',
  },
});

// Custom icon with circle shape (default mode)
FlowXO.setConfig({
  launcher: {
    mode: 'icon',
    shape: 'circle',
    iconUrl: 'https://example.com/chat-icon.svg',
    color: '#6F5FE8',
  },
});

// Square launcher with no shadow
FlowXO.setConfig({
  launcher: {
    mode: 'full',
    shape: 'none',
    iconUrl: 'https://example.com/square-mascot.png',
  },
});

Launcher Properties:

Note: Configuration changes are persisted to local storage and will be applied on subsequent page loads.

FlowXO.setLocale(locale, connectionId?)

Set the widget's language/locale for UI strings and localized content.

// Set to Spanish
FlowXO.setLocale('es');

// Set to French for a specific widget
FlowXO.setLocale('fr', 'support-widget');

Parameters:

This is a convenience method equivalent to FlowXO.setConfig({ language: locale }).

FlowXO.sendMessage(text, connectionId?)

Send a message programmatically as the user.

FlowXO.sendMessage('Hello, I need help with my order');

If the widget is closed, the message is queued and sent when opened.

FlowXO.getHistory(connectionId?)

Get the conversation history.

const messages = await FlowXO.getHistory();
console.log(messages);
// [
//   { id: "1", role: "user", text: "Hello", timestamp: "2024-01-15T10:00:00Z" },
//   { id: "2", role: "assistant", text: "Hi! How can I help?", timestamp: "2024-01-15T10:00:01Z" }
// ]

Returns: Promise<HistoryMessage[]>

HistoryMessage Properties:

FlowXO.clearConversation(connectionId?)

Clear the conversation and start fresh.

FlowXO.clearConversation();

FlowXO.destroy(connectionId?)

Destroy a widget instance, removing it from the DOM.

FlowXO.destroy();
FlowXO.destroy('connection-id-1'); // For multiple widgets

Events

Subscribe to widget events to react to user interactions and widget state changes.

FlowXO.on(event, callback)

Subscribe to a widget event.

FlowXO.on('message', (data) => {
  console.log('New message:', data);
});

FlowXO.off(event, callback)

Unsubscribe from a widget event.

const handler = (data) => console.log(data);
FlowXO.on('message', handler);

// Later...
FlowXO.off('message', handler);

Event Types

Event Example

// Track when users open/close the widget
FlowXO.on('open', ({ connectionId }) => {
  analytics.track('widget_opened', { connectionId });
});

FlowXO.on('close', ({ connectionId }) => {
  analytics.track('widget_closed', { connectionId });
});

// React to new messages
FlowXO.on('agentMessage', ({ connectionId, message }) => {
  // Show browser notification if widget is closed
  if (!FlowXO.isOpen(connectionId)) {
    showNotification('New message from support');
  }
});

Initialization Hook

Use window.onFlowXOInit to customize widget initialization. This callback is called for each widget instance before it connects, allowing you to set user identity and configuration dynamically.

<script>
  window.onFlowXOInit = async (connectionId) => {
    // Fetch user data from your backend
    const user = await fetchCurrentUser();

    return {
      // Set user identity (optional)
      member: user
        ? {
            id: user.id,
            name: user.displayName,
            email: user.email,
          }
        : undefined,

      // Override configuration (optional)
      config: {
        primaryColor: '#6F5FE8',
        header: {
          title: 'Help Center',
        },
      },
    };
  };
</script>
<script
  src="https://messenger.flowxo.com/loader.js"
  data-connection="your-connection-id"
></script>

Return Properties:

The callback receives connectionId as a parameter, which is useful when you have multiple widgets on the same page with different configurations.

Loaded Event

The flowxo:loaded event fires when the FlowXO API is ready but before any widgets are auto-initialized. Use this for programmatic initialization when you want full control over when widgets are created.

document.addEventListener('flowxo:loaded', (event) => {
  const { FlowXO } = event.detail;

  // API is ready - initialize widgets programmatically
  FlowXO.init({
    connectionId: 'support-bot',
    user: { id: currentUser.id, name: currentUser.name },
  });
});

Event Detail:

Use case: Load the script without data-connection to prevent auto-init, then use flowxo:loaded to initialize widgets conditionally (e.g., only for logged-in users, or after certain page conditions are met).

Ready Event

The flowxo:ready event fires when a widget instance has been initialized and is ready to use. Use this to interact with a specific widget after it's created.

document.addEventListener('flowxo:ready', (event) => {
  const { connectionId, instance } = event.detail;
  console.log('Widget ready:', connectionId);

  // Now safe to call API methods
  FlowXO.open(connectionId);
});

Event Detail:

For multiple widgets, the event fires once for each widget as it becomes ready.

Multiple Widget Instances

When embedding multiple widgets on a page, pass the connectionId parameter to target specific instances:

// Initialize two widgets
await FlowXO.init({ connectionId: 'sales-bot' });
await FlowXO.init({ connectionId: 'support-bot' });

// Control specific widgets
FlowXO.open('sales-bot');
FlowXO.close('support-bot');

// Identify user on specific widget
FlowXO.identify('sales-bot', {
  id: 'user-123',
  name: 'John',
});

When connectionId is omitted, the API operates on the first/default widget instance.

Debug Mode

Enable debug mode for development by adding ?fxo_debug=true to the page URL:

https://yoursite.com/page?fxo_debug=true

Debug mode provides:

• Detailed console logging
• Access to FlowXO._debug utilities

// When debug mode is enabled
FlowXO._debug.log('custom', 'Debug message');
FlowXO._debug.getInstances(); // Get all widget instances

Complete Example

<!DOCTYPE html>
<html>
  <head>
    <title>FlowXO Widget Example</title>
  </head>
  <body>
    <!-- Initialize callback (runs before widget connects) -->
    <script>
      window.onFlowXOInit = async (connectionId) => {
        // Optionally fetch user from your backend
        const user = await fetchCurrentUser().catch(() => null);

        return {
          member: user
            ? {
                id: user.id,
                name: user.name,
                email: user.email,
              }
            : undefined,
          config: {
            primaryColor: '#6F5FE8',
            header: {
              title: 'Help Center',
              subtitle: 'We typically reply within minutes',
            },
            launcher: {
              mode: 'full',
              shape: 'rounded',
              iconUrl: 'https://example.com/mascot.png',
              closeIconUrl: 'https://example.com/close.png',
            },
          },
        };
      };

      // React to widget ready event
      document.addEventListener('flowxo:ready', (event) => {
        const { connectionId } = event.detail;
        console.log('Widget ready:', connectionId);

        // Set up event listeners
        FlowXO.on('open', () => console.log('Widget opened'));
        FlowXO.on('close', () => console.log('Widget closed'));
        FlowXO.on('userMessage', ({ message }) =>
          console.log('User said:', message)
        );
      });
    </script>

    <!-- Load the widget -->
    <script
      src="https://messenger.flowxo.com/loader.js"
      data-connection="your-connection-id"
      async
    ></script>

    <!-- Your application code -->
    <script>
      // Identify user when they log in (after initial load)
      document
        .getElementById('login-btn')
        .addEventListener('click', async () => {
          const user = await loginUser();
          FlowXO.identify({
            id: user.id,
            name: user.name,
            email: user.email,
          });
        });

      // Clear identity on logout
      document.getElementById('logout-btn').addEventListener('click', () => {
        FlowXO.logout();
      });

      // Custom button to open widget
      document.getElementById('help-btn').addEventListener('click', () => {
        FlowXO.open();
      });
    </script>

    <button id="login-btn">Log In</button>
    <button id="logout-btn">Log Out</button>
    <button id="help-btn">Get Help</button>
  </body>
</html>

Configuration Options Reference

WebChatSettings

HeaderConfig

LauncherConfig

WidgetConfig

UrlFilterConfig

WelcomeConfig

LocalizedMessageChoice

MessagesConfig

MessageRoleConfig

ComposerConfig

AudioConfig

AttachmentsConfig

AttentionGetterConfig

PrivacyConfig

SecurityConfig

Other Configs

NoMessageBehaviorConfig

ChannelIdConfig

LocalizedString Type

Sample JSON

{
  "connectionId": "conn_abc123xyz",
  "name": "Acme Support Bot",
  "workspaceId": "ws_def456uvw",
  "organizationId": "org_ghi789rst",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "settings": {
    "mode": "popup",
    "initialState": "closed",
    "mobileInitialState": "closed",
    "mobileMode": "fullscreen",
    "primaryColor": "#4F46E5",
    "accentColor": "#7C3AED",
    "theme": "light",
    "backgroundColor": "#FFFFFF",
    "backgroundOpacity": 100,
    "customCss": ".fxo-header { font-weight: bold; }",
    "customCssUrl": "https://example.com/custom-widget.css",
    "language": "en",
    "languages": {
      "es": {
        "composer.placeholder": "Escribe un mensaje..."
      }
    },
    "autoplayAudio": false,
    "isTestConsole": false,
    "header": {
      "title": {
        "default": "Acme Support",
        "translations": { "es": "Soporte Acme" }
      },
      "subtitle": "We typically reply within minutes",
      "iconUrl": "https://example.com/logo.png",
      "iconBackground": "#E0E7FF",
      "hidden": false
    },
    "launcher": {
      "disabled": false,
      "position": "bottom-right",
      "offset": { "x": 10, "y": 20 },
      "color": "#4F46E5",
      "iconUrl": "https://example.com/chat-icon.svg",
      "closeIconUrl": "https://example.com/close-icon.svg",
      "mode": "icon",
      "shape": "circle"
    },
    "widget": {
      "size": "md",
      "urlFilter": {
        "include": ["https://example.com/support", "https://example.com/help"],
        "exclude": ["https://example.com/admin"]
      }
    },
    "welcome": {
      "message": "Hi there! How can I help you today?",
      "choices": [
        {
          "label": "Track my order",
          "value": "track_order",
          "type": "quickreply"
        },
        {
          "label": "Visit FAQ",
          "type": "url",
          "value": "https://example.com/faq",
          "urlTarget": "new_tab"
        }
      ],
      "suggestions": ["What are your hours?", "How do I return an item?"]
    },
    "messages": {
      "user": {
        "avatar": { "enabled": false },
        "bubbleColor": "#E0E7FF",
        "bubbleArrow": true
      },
      "assistant": {
        "avatar": { "enabled": true, "iconUrl": "https://example.com/bot-avatar.png" },
        "bubbleColor": "#F3F4F6",
        "bubbleArrow": true
      },
      "liveagent": {
        "avatar": { "enabled": true, "iconUrl": "https://example.com/agent-avatar.png" },
        "bubbleColor": "#FEF3C7",
        "bubbleArrow": true
      }
    },
    "composer": {
      "prompt": "Type your message...",
      "disabled": false,
      "audio": {
        "disabled": false,
        "maxLengthInSeconds": 120,
        "autosend": false
      },
      "attachments": {
        "disabled": false,
        "maxFileSizeInBytes": 10485760,
        "maxAttachments": 5,
        "types": ["image/*", "application/pdf"],
        "autosend": false,
        "imageOnly": false
      }
    },
    "attentionGetter": {
      "text": "Need help? We're here for you!",
      "delayInSeconds": 30,
      "durationInSeconds": 10,
      "expirationInDays": 7,
      "intensity": "moderate",
      "playSound": true,
      "soundUrl": "https://example.com/notification.mp3"
    },
    "attribution": {
      "disabled": false,
      "text": "Powered by Flow XO",
      "url": "https://flowxo.com"
    },
    "privacy": {
      "forgetChat": false,
      "zeroFootprint": false,
      "collectIp": true
    },
    "newMessageSound": {
      "enabled": true,
      "soundUrl": "https://example.com/message-sound.mp3"
    },
    "security": {
      "allowedDomains": ["example.com", "*.example.com"],
      "allowEvaluation": false
    },
    "settingsPanel": {
      "enabled": true,
      "features": {
        "soundToggle": true,
        "clearConversation": true
      }
    },
    "messagePreview": {
      "enabled": true
    },
    "hostedPage": {
      "enabled": true
    },
    "noMessageBehavior": {
      "type": "typing_indicator",
      "loadingMessageText": "Connecting you with support...",
      "cycleIntervalMs": 3000,
      "timeoutSeconds": 30
    },
    "channelId": {
      "prefix": "acme",
      "separator": "_"
    }
  }
}

Next Steps

• Customizing the Web Messenger — UI-based settings (colors, avatars, features, privacy)
• Customizing with CSS — CSS variables, class selectors, and advanced styling recipes
• Using Metadata — Identify users, pass custom data, and collect visitor information
• Installation & Embedding Options — Widget, hosted page, and embed options