> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# React Convocore Widget

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

# Convocore Widget

The Convocore Widget is a React component that allows you to easily integrate Convocore chatbots and voice interfaces into your React applications.

## Installation

```bash theme={null}
npm install convocore-widget
# or
yarn add convocore-widget
# or
pnpm add convocore-widget
```

## Basic Usage

### Single Widget

```jsx theme={null}
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

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

```jsx theme={null}
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",
              divClass: "first-widget-container", // unique class for the div
            },
          ]}
          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

```jsx theme={null}
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: "jane@example.com",
                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;
```

## Component 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 Options

| 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.

   ```jsx theme={null}
   <ConvocoreWidget containerId="widget-1" />
   <ConvocoreWidget containerId="widget-2" />
   ```

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

   ```jsx theme={null}
   <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.
   ```jsx theme={null}
   configs={[{ divClass: "unique-widget-class-1" }]}
   ```

## User Data Configuration

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

```jsx theme={null}
{
  user: {
    name: 'John Doe',
    email: 'john@example.com',
    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:

```jsx theme={null}
{
  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:

```jsx theme={null}
{
  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"
  }
}
```