> ## 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"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.