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 Channels > Widget & SDK
   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?",
           panelWidth: "700px",
           colors: {
               button: "#0069ED",
           },
       }
   </script>
   

   panelWidth sets how wide the chat panel is (default 550px). For the full list of configuration options, see Widget Options. To move the widget or restyle it with your own CSS, see Custom CSS Styling.

4. Set Up Authentication

   Anonymous Users (default)

   By default, the widget works without authentication. The widget stores an anonymous visitor ID in browser local storage (ago-widget-id). Clearing that storage changes the visitor identity; when storage is unavailable, it uses a temporary random ID. 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: "YOUR_SIGNED_JWT",
       }
   </script>
   

   Issue the JWT through your authentication service and configure its public JWKS URL in AGO. AGO verifies signatures using RS256, RS384, RS512, or ES256. Include the user claims you need, such as email, name, and plan. A shared-secret HS256 token is not supported by this JWT flow.

   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