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

# Chat

> Deploy an AI-powered chat widget on your website

## Overview

The Chat channel provides a customizable web chat widget that you can embed on your website. It enables real-time conversations with your visitors powered by your AI agent.

<Info>
  **Plan availability:** Available on all plans. See [Plans & Billing](/features/settings/plans).
</Info>

## Features

<CardGroup cols={2}>
  <Card title="Instant Responses" icon="bolt">
    Your agent responds to visitors immediately, 24/7
  </Card>

  <Card title="Customizable Design" icon="palette">
    Match your brand with custom colors and styling
  </Card>

  <Card title="Human Takeover" icon="user">
    Seamlessly take over conversations when needed
  </Card>

  <Card title="Rich Media" icon="image">
    Support for images, links, and formatted text
  </Card>
</CardGroup>

## Installing the Chat Widget

### Basic Installation

Add the following code to your website, just before the closing `</body>` tag:

```html theme={null}
<!-- Clarky Chat Widget -->
<script src="https://clarky.ai/embed/<bot-id>/chat.js"></script>
```

<Note>
  You can find your bot ID in **Settings > Share** in your Clarky dashboard.
</Note>

### Configuration Options

Customize the widget behavior with additional options:

```javascript theme={null}
<script src="https://clarky.ai/embed/<bot-id>/chat.js"></script>
```

### Advanced Integration

<Tabs>
  <Tab title="WordPress">
    For WordPress sites:

    <Steps>
      <Step title="Access Theme Editor">
        Go to **Appearance > Theme Editor** in your WordPress admin.
      </Step>

      <Step title="Edit Footer Template">
        Find and edit your `footer.php` file.
      </Step>

      <Step title="Add Code">
        Paste the Clarky embed code before the closing `</body>` tag.
      </Step>

      <Step title="Save Changes">
        Save the file and test your site.
      </Step>
    </Steps>

    <Warning>
      Always create a backup before editing theme files.
    </Warning>
  </Tab>

  <Tab title="Shopify">
    For Shopify stores:

    <Steps>
      <Step title="Go to Theme Editor">
        Navigate to **Online Store > Themes > Customize**.
      </Step>

      <Step title="Edit theme.liquid">
        Click **Actions > Edit code** and find `theme.liquid`.
      </Step>

      <Step title="Add Code">
        Paste the embed code before `</body>`.
      </Step>

      <Step title="Save and Test">
        Save changes and test on your store.
      </Step>
    </Steps>
  </Tab>

  <Tab title="React/Next.js">
    For React or Next.js applications:

    ```jsx theme={null}
    import { useEffect } from 'react';

    function App() {
      useEffect(() => {
        // Load Clarky script
        const script = document.createElement('script');
        script.src = 'https://clarky.ai/embed/<bot-id>/chat.js';
        script.async = true;
        document.body.appendChild(script);

        return () => {
          document.body.removeChild(script);
        };
      }, []);

      return <div>Your App</div>;
    }
    ```
  </Tab>

  <Tab title="Google Tag Manager">
    Using Google Tag Manager:

    <Steps>
      <Step title="Create New Tag">
        In GTM, create a new **Custom HTML** tag.
      </Step>

      <Step title="Paste Code">
        Add the Clarky embed code to the tag.
      </Step>

      <Step title="Set Trigger">
        Set trigger to **All Pages** or specific pages.
      </Step>

      <Step title="Publish">
        Save and publish your GTM container.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Customizing Appearance

### Colors and Branding

Customize your chat widget to match your brand:

<Steps>
  <Step title="Navigate to Interface Settings">
    Go to **Settings > Interface** in your dashboard.
  </Step>

  <Step title="Customize Colors">
    Configure:

    * **Header Background**: The color of the chat widget header
    * **Header Text**: The color of text in the header
    * **Primary Color**: Buttons and accents
    * **Background**: Chat background color
  </Step>

  <Step title="Upload Avatar">
    Add a custom avatar image that appears in the chat.
  </Step>

  <Step title="Save Changes">
    Changes apply immediately to your widget.
  </Step>
</Steps>

### Greeting Message

Set a welcoming first message:

1. Go to **Settings > Interface**
2. Edit the **Chat Greeting** field
3. This message appears when users open the chat

**Example:**

```
👋 Hi there! I'm here to help. What can I assist you with today?
```

### Starter Prompts

Add quick-click options for common questions:

```json theme={null}
[
  "What are your business hours?",
  "Tell me about your services",
  "How can I contact you?",
  "I need help with an order"
]
```

Users can click these to start a conversation quickly.

## Chat Widget Features

### Real-Time Messaging

* **Instant delivery**: Messages send and receive in real-time
* **Typing indicators**: Show when the agent is typing
* **Read receipts**: Know when messages are read
* **Message history**: Conversations persist across sessions

### Rich Content

Your agent can send various content types:

<AccordionGroup>
  <Accordion title="Text Messages">
    Standard text responses with formatting support (bold, italic, lists, etc.)
  </Accordion>

  <Accordion title="Links and Buttons">
    Interactive elements that direct users to relevant pages or actions.
  </Accordion>

  <Accordion title="Images">
    Product photos, diagrams, or helpful visuals.
  </Accordion>

  <Accordion title="Cards">
    Structured information like product cards or feature highlights.
  </Accordion>
</AccordionGroup>

### Human Takeover

When a conversation needs human attention:

1. You'll receive a notification
2. Click to join the conversation
3. The user is notified a human has joined
4. You can take over or assist the AI agent

<Info>
  The AI agent continues to suggest responses even during human takeover, helping you respond faster.
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Position Strategically">
    Place the chat widget where it's visible but not intrusive. Bottom-right is most common, but bottom-left works well for RTL languages.
  </Accordion>

  <Accordion title="Set Expectations">
    In your greeting, clearly state what the agent can help with. This prevents frustration and improves user experience.
  </Accordion>

  <Accordion title="Use Starter Prompts">
    Well-crafted starter prompts guide users toward topics your agent handles well and reduce confusion.
  </Accordion>

  <Accordion title="Monitor and Iterate">
    Review conversations regularly to identify areas where your agent struggles, then add knowledge to improve responses.
  </Accordion>

  <Accordion title="Enable Human Takeover">
    Always have a human agent available to take over when needed, especially during business hours.
  </Accordion>

  <Accordion title="Test Mobile Experience">
    Ensure your chat widget works well on mobile devices, as many users will access it from phones.
  </Accordion>
</AccordionGroup>

## Testing Your Chat Widget

Before going live:

<Steps>
  <Step title="Test on Staging">
    If you have a staging or test site, deploy there first.
  </Step>

  <Step title="Try Different Scenarios">
    Ask various types of questions:

    * Common questions (hours, location)
    * Product inquiries
    * Support requests
    * Edge cases
  </Step>

  <Step title="Test on Multiple Devices">
    Check desktop, tablet, and mobile devices.
  </Step>

  <Step title="Verify Handoff">
    Test the human takeover feature to ensure smooth transitions.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget Not Appearing">
    If the widget doesn't show:

    1. Verify the embed code is in the HTML
    2. Check browser console for JavaScript errors
    3. Ensure the bot ID is correct
    4. Clear browser cache and reload
  </Accordion>

  <Accordion title="Styling Issues">
    If the widget looks wrong:

    1. Check for CSS conflicts with your site
    2. Verify custom colors are valid hex codes
    3. Try disabling site-wide CSS temporarily
  </Accordion>

  <Accordion title="Messages Not Sending">
    If messages fail to send:

    1. Check your internet connection
    2. Verify the bot is active in Clarky dashboard
    3. Check browser console for errors
  </Accordion>
</AccordionGroup>

## Analytics and Insights

Track chat widget performance:

* **Conversations started**: How many users engage
* **Response time**: How quickly the agent responds
* **Completion rate**: Percentage of conversations resolved
* **Popular questions**: Most common user inquiries
* **Handoff rate**: How often human agents take over

<Card title="View Analytics" icon="chart-line" href="/features/dashboard/analytics">
  Learn more about tracking your chat performance
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Customize Interface" icon="palette" href="/features/settings/interface">
    Match your brand with custom styling
  </Card>

  <Card title="Monitor Conversations" icon="messages" href="/features/inbox/overview">
    See what users are asking
  </Card>

  <Card title="Improve Knowledge" icon="brain" href="/features/knowledge/overview">
    Enhance responses with better training
  </Card>

  <Card title="Enable Voice" icon="phone" href="/guides/channels/voice">
    Add phone support to complement chat
  </Card>
</CardGroup>