Convocore Widget

A React component for easily integrating Convocore widgets in React applications.

Installation

npm install convocore-widget
# or
yarn add convocore-widget
# or
pnpm add convocore-widget

Usage

Single Widget

import React from "react";
import { ConvocoreWidget } from "convocore-widget";

const MyApp = () => {
  return (
    <div>
      <h1>My Convocore Widget</h1>
      <ConvocoreWidget
        configs={[
          {
            ID: "your-widget-id", // YOUR AGENT ID
            region: "eu", // YOUR ACCOUNT REGION
            render: "bottom-right", // can be 'full-width' or 'bottom-left' or 'bottom-right'
            // modalMode: true, // Set this to 'true' to open the widget in modal mode
          },
        ]}
      />
    </div>
  );
};

export default MyApp;

Multiple Widgets on the Same Page

Important: When using multiple widgets on the same page, always use unique containerId and unique className values for each widget to prevent conflicts.

import React from "react";
import { ConvocoreWidget } from "convocore-widget";

const MyApp = () => {
  return (
    <div>
      <h1>My Convocore Widgets</h1>

      <div className="widget-section">
        <h2>Widget 1</h2>
        <ConvocoreWidget
          configs={[
            {
              ID: "first-widget-id", // YOUR AGENT ID
              region: "eu", // YOUR ACCOUNT REGION
              render: "full-width", // can be 'full-width' or 'bottom-left' or 'bottom-right'
              divClass: "first-widget-container", // unique id fo the dev
            },
          ]}
          className="first-widget-container"
          height="400px"
          width="200px"
          containerId="widget-1" // unique id
        />
      </div>

      <div className="widget-section">
        <h2>Widget 2</h2>
        <ConvocoreWidget
          configs={[
            {
              ID: "second-widget-id",
              region: "na",
              render: "full-width",
              divClass: "second-widget-container",
            },
          ]}
          className="second-widget-container"
          height="400px"
          width="200px"
          containerId="widget-2"
        />
      </div>
    </div>
  );
};

export default MyApp;

Advanced Configuration

import React from "react";
import { ConvocoreWidget } from "convocore-widget";

const MyApp = () => {
  return (
    <div>
      <h1>Advanced Configuration</h1>

      <div className="widget-section">
        <h2>Widget with User Data & VF Variables</h2>
        <ConvocoreWidget
          configs={[
            {
              ID: "your-widget-id",
              region: "eu",
              render: "bottom-right",

              // Custom user data
              user: {
                name: "Jane Smith",
                email: "[email protected]",
                phone: "+1987654321",
                customField: "Custom user value",
              },

              // Custom user ID
              userID: "custom-user-123",

              // VF variables injection
              vf_variables: {
                from_vg: "This is injected from React component",
                custom_var: "Custom variable value",
              },

              // Auto-start chat
              autostart: true,
            },
          ]}
        />
      </div>

      <div className="widget-section">
        <h2>Widget with Custom Styling</h2>
        <ConvocoreWidget
          configs={[
            {
              ID: "another-widget-id",
              region: "eu",
              render: "bottom-left",

              // Modal mode
              modalMode: true,

              // Custom stylesheets
              stylesheets: [
                "https://vg-bunny-cdn.b-cdn.net/vg_live_build/styles.css",
                "/path/to/your/custom.css",
              ],

              // Theme customization
              variables: {
                roundedImageURL: "https://example.com/rounded-image.jpg",
                avatarImageUrl: "https://example.com/avatar.jpg",
                headerImageUrl: "https://example.com/header.jpg",
                bannerImageUrl: "https://example.com/banner.jpg",
              },
            },
          ]}
        />
      </div>
    </div>
  );
};

export default MyApp;

Props

ConvocoreWidget Props

| Prop | Type | Description | Default | | ------------- | --------------------- | ---------------------------------- | -------------- | | configs | WidgetConfig[] | Array of widget configurations | Required | | className | string | CSS class for the container | '' | | style | React.CSSProperties | Custom styles for the container | {} | | containerId | string | Unique ID for the widget container | Auto-generated | | height | string | Height of the container | '500px' | | width | string | Width of the container | '100%' |

WidgetConfig

| Property | Type | Description | Required | | -------------- | -------------------- | ------------------------------------------- | -------- | | ID | string | The ID of the widget | Yes | | region | string | The region of the widget (e.g., 'eu', 'na') | Yes | | render | string | The rendering position | Yes | | divClass | string | Custom class for the container div | No | | user | object | User data (name, email, phone, etc.) | No | | userID | string | Custom user ID | No | | autostart | boolean | Whether to auto-start the chatbot | No | | modalMode | boolean | Whether to open the widget in modal mode | No | | stylesheets | string[] | List of custom stylesheet URLs | No | | vf_variables | Record<string,any> | Voice Flow variables to inject | No | | variables | object | Theme customization (avatarImageUrl, etc.) | No |

Best Practices

Using Multiple Widgets

When using multiple widgets on the same page:

1. Always use unique container IDs: Set a unique containerId for each ConvocoreWidget component to ensure proper isolation.

   <ConvocoreWidget containerId="widget-1" />
   <ConvocoreWidget containerId="widget-2" />

2. Use unique class names: Assign unique className values to each widget to prevent CSS conflicts.

   <ConvocoreWidget className="first-widget-container" />
   <ConvocoreWidget className="second-widget-container" />

3. Use unique divClass in configs: If you specify divClass in your widget configs, make sure they are unique.

   configs={[{ divClass: "unique-widget-class-1" }]}

Failure to use unique identifiers may result in widgets not displaying correctly or conflicts in functionality.

User Data Configuration

You can provide user information to the widget using the user property:

{
  user: {
    name: 'John Doe',
    email: '[email protected]',
    phone: '+1234567890',
    // You can add any custom fields here
    customField: 'Custom value'
  }
}

Voice Flow Variables

You can inject variables into Voice Flow using the vf_variables property:

{
  vf_variables: {
    from_vg: 'This is injected from React component',
    user_tier: 'premium',
    custom_var: 'Custom variable value'
  }
}

Theme Customization

You can customize the widget's appearance using the variables property:

{
  variables: {
    roundedImageURL: "https://example.com/rounded-image.jpg",
    avatarImageUrl: "https://example.com/avatar.jpg",
    headerImageUrl: "https://example.com/header.jpg",
    bannerImageUrl: "https://example.com/banner.jpg"
  }
}