@oxvo/messenger

React and core web SDK package for OXVO Messenger.

Structure

• src/core/ shared controller and lazy-load engine
• src/react/ React provider, hook, launcher
• ../shared/core/ canonical shared source synced into src/core/

Install

npm install @oxvo/messenger

Full Settings Support

createOxvoMessengerController and OxvoMessengerProvider support the full modern settings surface used by /app/javascript/entrypoints/sdk.js.

You can pass settings using either settings or oxvoSettings (alias). When both are present, settings wins per key.

<OxvoMessengerProvider
  baseUrl="https://your-oxvo-domain"
  websiteToken="your-website-token"
  scriptUrl="https://static.oxvo.com/messenger/sdk.js"
  settings={{
    baseDomain: '',
    useBrowserLanguage: true,
    locale: 'en',
    position: 'right',
    launcherVisible: true,
    showPopoutButton: true,
    showUnreadMessagesDialog: true,
    widgetStyle: 'standard',
    theme: 'auto',
    type: 'expanded_bubble',
    launcherTitle: 'Welcome to OXVO',
    welcomeTitle: 'Welcome to OXVO',
    welcomeDescription: 'Ask us anything and we will be right here.',
    availableMessage: 'We are online and happy to help.',
    unavailableMessage: 'We are away right now, leave a message.',
    enableFileUpload: true,
    enableEmojiPicker: true,
    enableEndConversation: true,
    enableGifPicker: true,
    headerTextColor: '#ffffff',
    headerDecorationMode: 3,
    tabSpaces: ['Home', 'Chat'],
    convStarters: [{ text: 'I need help with my account', enabled: true }],
    convLinks: [
      { label: 'Docs', url: 'https://www.oxvo.com/docs', target: '_blank', enabled: true },
    ],
    homeBlocksOrder: ['Starters', 'Articles', 'Links', 'Apps'],
    avatarUrl: 'https://placehold.co/64x64',
    helpCenterSlug: 'help-center',
    preChatFormEnabled: true,
    preChatFormOptions: {
      pre_chat_message: 'Tell us about your issue.',
      pre_chat_fields: [],
    },
    apps: [
      {
        title: 'Docs',
        description: 'Product documentation',
        url: 'https://www.oxvo.com/docs',
        img_url: 'https://placehold.co/32x32',
      },
    ],
  }}
/>

Compatibility aliases accepted:

• darkMode -> theme
• hideMessageBubble -> inverted into launcherVisible (only when launcherVisible is not explicitly set)
• locale: 'auto' -> enables useBrowserLanguage automatically (unless useBrowserLanguage is explicitly set)

Live Chat Loader (Default Off)

Use liveChatLoader: true to show a lightweight launcher first and delay full SDK loading until idle/user interaction.

<OxvoMessengerProvider
  baseUrl="https://your-oxvo-domain"
  websiteToken="your-website-token"
  scriptUrl="https://static.oxvo.com/messenger/sdk.js"
  liveChatLoader={true}
/>

liveChatLoader is false by default.

Appearance + override precedence

liveChatLoader also accepts an object:

<OxvoMessengerProvider
  baseUrl="https://your-oxvo-domain"
  websiteToken="your-website-token"
  scriptUrl="https://static.oxvo.com/messenger/sdk.js"
  settings={{
    position: 'left',
    theme: 'dark',
    widgetStyle: 'flat',
  }}
  liveChatLoader={{
    enabled: true,
    appearance: {
      position: 'right',
      horizontalSpacing: 24,
      verticalSpacing: 24,
      messengerColor: '#2d6bff',
      type: 'expanded_bubble',
      launcherTitle: 'Support',
    },
  }}
/>

Precedence:

• defaults
• settings passed to init
• liveChatLoader.appearance (highest priority)

Note:

• widgetStyle is inherited from messenger settings and is not overridable via liveChatLoader.appearance.

Custom launcher

Use render in OxvoMessengerLauncher to completely replace the default placeholder bubble while still using load()/open() actions.

Test

npm test

Production Build

npm run build