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

# Web Chat

<video autoPlay muted loop playsInline className="w-full aspect-video rounded-xl" src="https://mintcdn.com/ksg-ea85c748/GhigIKRqXPG8pHif/videos/vivi_webchat.mp4?fit=max&auto=format&n=GhigIKRqXPG8pHif&q=85&s=7373b5ff32eb03d91fe44e605936e13a" data-path="videos/vivi_webchat.mp4" />

**Web Chat** is a communication channel that allows end users to interact with your virtual agent directly from your website. We provide a **customizable**, **embeddable** chat widget that supports **real-time interactions**, ensuring a seamless, branded user experience.

Once you create a Web Chat channel, you'll be directed to a configuration screen where you can customize the widget's appearance and behavior before deploying it to your website. Updates are previewed live on the right-hand side to help you visualize your changes.

***

## Appearance Configuration

Configuration options to customize the look and feel of the chat widget using the live preview panel include:

<Steps>
  <Step title="General Settings">
    * **Privacy Policy** Link Add a configurable link to the agent's privacy policy within the chat widget.
    * **Sounds Effects** Toggle Enable or disable sound effects for agent responses and states.
    * **Reply Format** Toggle Switch between real-time streaming responses and full responses delivered all at once.
    * **File Upload** Toggle Enable or disable file uploads so the agent can receive and understand user-submitted files during chat.
    * **Agent Reasoning** Toggle Enable or disable agent reasoning mode, allowing reasoning-based agents with streaming enabled to display real-time workflow highlights while the final response is being computed.
  </Step>

  <Step title="Chat Window">
    * Customize **colors** for the header background, header text, accents, and highlights. You can adjust the color using hex codes or the color picker.
    * Set **theme** to Light, Dark, or Auto (match user's system preference).
    * Choose an **avatar**, using a custom image or letter.
  </Step>

  <Step title="Chat Button">
    * Choose between **custom text, custom image, or both** for the button.
    * Adjust **size and color** of the button.
  </Step>

  <Step title="Fallback Message">
    * Define a **custom message** and **icon** that will appear if chat services are temporarily unavailable.
  </Step>

  <Step title="Domain Restriction">
    * Add the **domain(s)** where the agent will be hosted. A domain is typically the homepage of your website.
  </Step>
</Steps>

***

## Agent Installation

To deploy your agent, navigate to the **Installation** tab. You will need to embed the provided code on every page where you want the chat widget to appear.

<Tabs>
  <Tab title="Website">
    You will be provided with a JavaScript code snippet to embed on your website. The script initializes the chat window using your unique agent channel ID.

    *Example Snippet*

    ```html theme={null}
    <script async src="https://<your-agent-url>/chatbot.js"></script>
    <script>
      window.addEventListener('load', function() {
        window.initViviChatbot({
          channelId: 'your-channel-id'
        });
      });
    </script>
    ```
  </Tab>

  <Tab title="SharePoint Online">
    Deploy the VIVI chatbot to SharePoint Online using an SPFx package. Choose your deployment scope:

    <AccordionGroup>
      <Accordion title="All Sites (Tenant-Wide)">
        Deploys the chatbot across all modern SharePoint pages in your organization using an SPFx Application Customizer.

        <Steps>
          <Step title="Download the SPFx Package">
            Download the pre-built SharePoint Framework solution package (.sppkg) file for your environment.
          </Step>

          <Step title="Upload to App Catalog">
            Go to your SharePoint Admin Center > **More features** > **Apps** > **App Catalog**. Upload the `.sppkg` file.
          </Step>

          <Step title="Deploy the Solution">
            When prompted, check **"Make this solution available to all sites in the organization"** and click **Deploy**.
          </Step>

          <Step title="Configure Channel ID">
            Go to SharePoint Admin Center > **More features** > **Apps** > **Tenant Wide Extensions**. Find **"ViviChatbot"** and set its properties:

            ```json theme={null}
                        {
                          "channelId": "your-channel-id"
                        }
            ```
          </Step>

          <Step title="Verify Installation">
            Navigate to any modern SharePoint page. The VIVI chatbot should appear in the bottom-right corner.

            <Note>
              It may take a few minutes for the extension to propagate across all sites.
            </Note>
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="Per-Page (Web Part)">
        Deploys the chatbot to specific modern Site Pages only, using the Web Part included in the same SPFx package.

        <Steps>
          <Step title="Download the SPFx Package">
            Download the pre-built SharePoint Framework solution package (.sppkg) file for your environment.
          </Step>

          <Step title="Upload to App Catalog">
            Go to your SharePoint Admin Center > **More features** > **Apps** > **App Catalog**. Upload the `.sppkg` file.
          </Step>

          <Step title="Deploy the Solution">
            When prompted, **do not** check "Make this solution available to all sites in the organization". Click **Deploy**.
          </Step>

          <Step title="Add the Web Part to a Page">
            Open the target page in Edit mode, click **+** to add a web part, and search for **"Vivi Chatbot"**. Open the Property Pane and enter your Channel ID.
          </Step>

          <Step title="Verify Installation">
            Publish the page and confirm the chatbot appears in the bottom-right corner.

            <Warning>
              Web Parts can only be added to modern Site Pages. System views such as Document libraries, Site Contents, and Lists do not support web parts.
            </Warning>
          </Step>
        </Steps>
      </Accordion>
    </AccordionGroup>

    <Note>
      Switching between deployment scopes requires re-uploading the app package.
    </Note>
  </Tab>
</Tabs>

## Optional Parameters

You can pass optional parameters to further control the chat session. These parameters are added inside a `config` block in your JavaScript embed snippet.

<ResponseField name="welcomeMessage" type="string">
  A custom greeting shown when the chat widget loads.

  <Expandable title="snippet">
    ```javascript theme={null}
    window.initViviChatbot({
      channelId: "your-channel-id",
      config: {
        welcomeMessage: "Hi 👋, How can I help you?",
      },
    });
    ```
  </Expandable>
</ResponseField>

<ResponseField name="threadId" type="UUID">
  A persistent or custom thread ID for the session. If not provided, a unique thread ID will be generated automatically.

  <Expandable title="snippet">
    ```javascript theme={null}
    window.initViviChatbot({
      channelId: "your-channel-id",
      threadId: "your-custom-thread-id"
    });
    ```
  </Expandable>
</ResponseField>

<ResponseField name="userId" type="UUID">
  A unique identifier to tie the session to a specific user. If not provided, a unique user ID will be generated and stored in `localStorage`.

  <Expandable title="snippet">
    ```javascript theme={null}
    window.initViviChatbot({
      channelId: "your-chanel-id",
      userId: "your-user-id"
    });    
    ```
  </Expandable>
</ResponseField>

<ResponseField name="persistentThread" type="boolean">
  If `true`, the thread ID will be stored in `localStorage` and persist across browser sessions. When `false` (default), it will be stored in `sessionStorage` and cleared when the tab is closed.

  <Expandable title="snippet">
    ```javascript theme={null}
    window.initViviChatbot({
      channelId: "your-channel-id",
      persistentThread: true
    });   
    ```
  </Expandable>
</ResponseField>

<ResponseField name="onEventEmitted" type="string">
  Use this option to listen to the events emitted by the chatbot and do something with them (i.e. tracking analytics). When listening to chatbot events, you'll receive an event object with the following structure:

  ```typescript theme={null}
  {
    type: "<event_type";
    data?: <event_data>;
  }
  ```

  <Expandable title="supported events">
    <AccordionGroup>
      <Accordion title="message-sent" description="When user sends a message">
        ```javascript theme={null}
        {
        	type: "message-sent",
        	data: {
        		message: "<human_message_content>"
        	}
        }
        ```
      </Accordion>

      <Accordion title="message-received" description="When AI responds to a message">
        ```javascript theme={null}
        {
        	type: "message-received",
        	data: {
        		message: "<ai_message_content>"
        	}
        }
        ```
      </Accordion>

      <Accordion title="chatbot-opened" description="When a chatbot widget opens">
        ```javascript theme={null}
        {
        	type: "chatbot-opened"
        }
        ```
      </Accordion>

      <Accordion title="chatbot-closed" description="When a chatbot closes">
        ```javascript theme={null}
        {
        	type: "chatbot-closed"
        }
        ```
      </Accordion>

      <Accordion title="conversation-restarted" description="When a conversation is restarted">
        ```javascript theme={null}
        {
        	type: "conversation-restarted"
        }
        ```
      </Accordion>

      <Accordion title="input-mode-changed" description="When a voice input mode changes">
        ```javascript theme={null}
        {
        	type: "input-mode-changed",
        	data: {
        		mode: "text" | "voice"
        	}
        }
        ```
      </Accordion>

      <Accordion title="voice-conversation-started" description="When a voice conversation begins">
        ```javascript theme={null}
        {
        	type: "voice-conversation-started"
        }
        ```
      </Accordion>

      <Accordion title="voice-conversation-ended" description="When a voice conversation ends">
        ```javascript theme={null}
        {
        	type: "voice-conversation-ended"
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Expandable>
</ResponseField>

**Example Implementation**

```html theme={null}
<script async src="https://<your-agent-url>/chatbot.js"></script>
<script>
  window.addEventListener('load', function () {
    window.initViviChatbot({
      channelId: 'your-channel-id',
      config: {
        welcomeMessage: 'Hi 👋, How can I help you?',
        threadId: 'user-thread-id',
        userId: 'user-123',
        persistentThread: true,
		onEventEmitted: (event) => {
  		  switch (event.type) {
			case "message-sent":
			  // Do something when message is sent
			  break;
			case "voice-conversation-started":
			  // Do something when voice conversation start
			  break;
		  }
		}
      }
    });
  });
</script>
```

***

## Best Practices

* **Match** your brand's colors and logo on the web chat channel to ensure a cohesive experience.
* Set a **clear and friendly** initial greeting to guide users.
* Enable `persistentThread` to give returning users continuity in their conversations.