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

# Deploy the Chat Widget

> Embed the AGO chat widget on your website with authentication and customization

Add the AGO chat widget to your website, customize its appearance, and set up authentication.

## Prerequisites

* An AGO instance with at least one agent configured
* Admin access to get your base path URL and configure allowed domains
* Access to your website's HTML or CMS

***

<Steps>
  <Step title="Get Your Base Path URL">
    1. Navigate to **Settings** > **Integrations**
    2. Find your **base path URL**
    3. Add the domain where you will embed the widget to the **allowed domains** list
  </Step>

  <Step title="Add the Widget Script">
    Add the following code to your website, just before the closing `</body>` tag:

    ```html theme={null}
    <script>
        window.AGO = {
            basepath: "https://YOUR-DOMAIN.useago.com/",
            prompt: "Hello, how can I help you today?",
        }
    </script>
    <script async src="https://useago.github.io/widgetjs/frame.js"></script>
    ```

    Replace `YOUR-DOMAIN` with your actual base path.

    <Tip>The `async` attribute ensures the widget does not block your page from loading.</Tip>
  </Step>

  <Step title="Customize Appearance">
    You can customize the widget's look and feel through the configuration object:

    ```html theme={null}
    <script>
        window.AGO = {
            basepath: "https://YOUR-DOMAIN.useago.com/",
            prompt: "Hello, how can I help you today?",
            colors: {
                button: "#0069ED",
            },
        }
    </script>
    ```

    For the full list of configuration options (position, size, colors, behavior), see [Widget Configuration](../features/widget-configuration-admin).
  </Step>

  <Step title="Set Up Authentication">
    #### Anonymous Users (default)

    By default, the widget works without authentication. Users are identified by a session cookie. This is suitable for public-facing help widgets.

    #### Authenticated Users

    To identify users and personalize responses, pass a signed JWT token:

    ```html theme={null}
    <script>
        window.AGO = {
            basepath: "https://YOUR-DOMAIN.useago.com/",
            jwt: "eyJhbGciOiJIUzI1NiIs...",
        }
    </script>
    ```

    The JWT token should contain user claims (email, name, plan, etc.) signed with your widget secret key.

    See [Widget & SDK Authentication](../security/widget-authentication) for the full authentication setup, including JWT signing and claim mapping.
  </Step>

  <Step title="Test the Widget">
    1. Load your website with the widget code added
    2. Click the widget button — it should open the chat interface
    3. Send a test message and verify the agent responds
    4. Check that the correct agent is handling the conversation
    5. Test in multiple browsers (Chrome, Firefox, Safari) and on mobile

    #### Troubleshooting

    | Issue                  | Cause                                   | Fix                                                  |
    | ---------------------- | --------------------------------------- | ---------------------------------------------------- |
    | Widget does not appear | Script not loaded or incorrect basepath | Check browser console for errors                     |
    | "Unauthorized" error   | Domain not allowed                      | Add your domain to allowed origins in Administration |
    | Wrong agent responds   | Permission configuration                | Check agent permission assignments                   |
    | CORS errors            | Domain not allowed                      | Add your domain to allowed origins in Administration |
  </Step>

  <Step title="Advanced -- Use the JavaScript SDK">
    For building custom chat interfaces with full control over messaging, events, and UI, use the JavaScript SDK (`@useago/sdk`). The SDK connects to the same backend as the widget but gives you programmatic access to conversations, messages, and agent interactions.

    See [SDK Integration](../features/sdk-integration) for installation and usage, and [Client Functions](../features/client-functions) for registering browser-side functions that agents can invoke.
  </Step>
</Steps>

## Related

* [Widget Configuration](../features/widget-configuration-admin) — full configuration reference
* [Widget & SDK Authentication](../security/widget-authentication) — authentication setup
* [API Key Authentication](../security/api-key-authentication) — server-to-server authentication
* [SDK Integration](../features/sdk-integration) — JavaScript SDK reference
* [Client Functions](../features/client-functions) — programmatic widget control