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

---

1. 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
2. Add the Widget Script

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

   <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.

   The async attribute ensures the widget does not block your page from loading.
3. Customize Appearance

   You can customize the widget’s look and feel through the configuration object:

   <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.

4. 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:

   <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 for the full authentication setup, including JWT signing and claim mapping.

5. 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

6. 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 for installation and usage, and Client Functions for registering browser-side functions that agents can invoke.

Related

• Widget Configuration — full configuration reference
• Widget & SDK Authentication — authentication setup
• API Key Authentication — server-to-server authentication
• SDK Integration — JavaScript SDK reference
• Client Functions — programmatic widget control