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

# How to embed the widget

> Learn how to embed the copilot in your app

the chat widget enables you to interact with the Copilot from your dashboard and see the changes in realtime.
OpenCopilot is a react web app that you can embed in your app.

there are several ways you can integrate the Copilot Chat widget into your application/webpage

<CardGroup cols={2}>
  <Card title="As a JavaScript File" href="#using-simple-js-script-recommended" icon="js" />

  <Card title="As a React Component (via npm)" href="#as-a-react-component" icon="react" />
</CardGroup>

### Using simple js script (recommended)

1. Download the latest build from [GitHub](https://github.com/openchatai/OpenCopilot/actions)
   and extract the zip file.

2. Include the provided JavaScript file in the head of your document (use `http://localhost:8888/pilot.js` for local setup).
   ```html
   <script src="https://cloud.opencopilot.so/pilot.js"></script>
   ```

3. Init the copilot (when document fully loads) by calling the `initAiCoPilot` function and passing the required options.

   ```html
   <script>
     const options = {
        apiUrl: "https://api.opencopilot.so/backend" // your base url where your are hosting OpenCopilot at (the API), usually it's http://localhost:8888/backend
        socketUrl: "https://api.opencopilot.so" // your socket server, usually it's http://localhost:8888/socket
        initialMessage: "Hey! happy to help.", // optional: you can pass an array of messages that will be sent to the copilot when it's initialized
        token: "your_copilot_token_goes_here", // you can get your token from the dashboard
        triggerSelector: "#triggerSelector", // the selector of the element that will trigger the copilot when clicked
        headers: {
          // optional: you can pass your authentication tokens to the copilot or any other header you want to send with every request
          Authorization: "Bearer your_auth_token_goes_here",
          AnyKey: "AnyValue"
        },
        containerProps: {
          // optional: you can pass any props to the container div
          className: "your-custom-class-name",
          style: {
              position: "fixed",
              height: "100%",
              bottom: "0",
              right: "0",
              width: "400px",
            },
        } 

      }
      window.addEventListener("DOMContentLoaded", ()=>initAiCoPilot(options)); // window.onload
   </script>
   ```

### As a React Component

1. Install the widget from npm.

   <Tabs>
     <Tab title="npm">
       ```bash
        npm install @openchatai/copilot-widget 
       ```
     </Tab>

     <Tab title="yarn">
       ```bash
        yarn add @openchatai/copilot-widget 
       ```
     </Tab>

     <Tab title="pnpm">
       ```bash
       pnpm add @openchatai/copilot-widget 
       ```
     </Tab>
   </Tabs>

2. Use the Component inside your application

```jsx
import { CopilotWidget,Root } from "@openchatai/copilot-widget"; // import the component
import '@openchatai/copilot-widget/index.css' // the required styles
const options = {
  apiUrl: "https://api.opencopilot.so/backend" // your base url where your are hosting OpenCopilot at (the API), usually it's http://localhost:8888/backend
  socketUrl: "https://api.opencopilot.so" // your socket server, usually it's http://localhost:8888/socket
  initialMessage: "Hey! happy to help.", // optional: you can pass an array of messages that will be sent to the copilot when it's initialized
  token: "your_copilot_token_goes_here", // you can get your token from the dashboard
  defaultOpen: true,
  headers: {
    // optional: you can pass your authentication tokens to the copilot or any other header you want to send with every request
    Authorization: "Bearer your_auth_token_goes_here",
    AnyKey: "AnyValue"
  },
}
const containerProps = {
  // optional: you can pass any props to the container div
  className: "your-custom-class-name",
  style: {
      position: "fixed",
      height: "100%",
      bottom: "0",
      right: "0",
      width: "400px",
    },
}
function Widget(){
  return (
    <Root containerProps={containerProps} options={options}>
    <CopilotWidget triggerSelector='#copilot-trigger' />
    </Root>
  )
}
```

## Options

<ResponseField name="Options" type="Object">
  <Expandable title="properties">
    <ResponseField name="initialMessage" type="string">
      The message that will be first present when the copilot is initialized
    </ResponseField>

    <ResponseField name="token" type="string">
      Your copilot token
    </ResponseField>

    <ResponseField name="triggerSelector" type="string">
      The selector of the element that will trigger the copilot when clicked
    </ResponseField>

    <ResponseField name="apiUrl" type="string">
      the url of the copilot api.
    </ResponseField>

    <ResponseField name="headers" type="Object">
      An object of headers that will be sent with every request (can be used to authenticate your api requests)
    </ResponseField>

    <ResponseField name="containerProps" type="Object">
      An object of props that will be passed to the container div
    </ResponseField>

    <ResponseField name="socketUrl" type="string">
      The url of the socket url that will be used to send and receive messages
    </ResponseField>
  </Expandable>
</ResponseField>

## Available options

| Option            | Description                                                                                               | type                    |
| ----------------- | --------------------------------------------------------------------------------------------------------- | ----------------------- |
| `initialMessage`  | The message that will be first present when the copilot is initialized                                    | `string`                |
| `token`           | Your copilot token                                                                                        | `string`                |
| `triggerSelector` | The selector of the element that will trigger the copilot when clicked                                    | `string`                |
| `apiUrl`          | the url of the copilot api.                                                                               | `string`                |
| `headers`         | An object of headers that will be sent with every request (can be used to authenticate your api requests) | `Record<string,string>` |
| `containerProps`  | An object of props that will be passed to the container div                                               | `Record<string,string>` |
| `socketUrl`       | The url of the socket url that will be used to send and receive messages                                  | `string`                |

## FAQ

<AccordionGroup>
  <Accordion title="The copilot widget is not showing up">
    Make sure that the `triggerSelector` is correct and the element exists in
    the dom,instead you can set `defaultOpen` to `true` to make the copilot open by default.
    if that did not work, please [open an issue on our GitHub repo](https://github.com/openchatai/OpenCopilot/issues/new)
  </Accordion>

  <Accordion title="The copilot widget is so small">
    The copilot widget is responsive and it's width is set to 100% by default of the container, you can change that by passing the
    `containerProps` option and setting the width to whatever you want.
  </Accordion>
</AccordionGroup>