> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmo.humanizing.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Embedding the Widget
> Step-by-step guide to embedding the chat widget on your website
## Getting Your Embed Code
The embed code is available from your agents deployment page in the Cosmo dashboard.
Open your agent from the Agents list in your workspace.
Click on the **Deployment** tab in the agent settings.
Copy the JavaScript snippet provided.
## Basic Embedding
Add the following script to your website, typically just before the closing body tag:
```html theme={null}
```
Replace YOUR\_AGENT\_ID with your actual agent ID from the dashboard.
## Embedding Methods
### Method 1: Script Tag (Recommended)
The simplest method - works with any website:
```html theme={null}
<\!DOCTYPE html>
My Website
<\!-- Your website content -->
<\!-- Chat Widget (place before closing body) -->
```
### Method 2: Dynamic Loading
Load the widget after page load for better performance:
```javascript theme={null}
window.addEventListener("load", function() {
const script = document.createElement("script");
script.src = "https://chat.humanizing.com/embed.js";
script.setAttribute("data-agent-id", "YOUR_AGENT_ID");
script.async = true;
document.body.appendChild(script);
});
```
## Configuration Options
Configure the widget behavior using data attributes:
| Attribute | Type | Description |
| ----------------- | ------- | ---------------------------------------------------- |
| data-agent-id | string | **Required.** Your agent ID from the dashboard |
| data-position | string | Widget position: bottom-right (default), bottom-left |
| data-open-on-load | boolean | Auto-open widget when page loads |
| data-hide-button | boolean | Hide the floating chat button |
## Page and Custom Context
The widget can send page context and custom values with each chat request. Use this when one agent should adapt to the page, location, department, or campaign where it is embedded.
The embed script automatically provides these prompt placeholders:
| Placeholder | Description |
| ------------------- | --------------------------------------------- |
| `{{ page_url }}` | Current page URL without query string or hash |
| `{{ page_origin }}` | Current site origin |
| `{{ page_path }}` | Current path on the site |
For example, on `https://example.com/products/widget?utm_source=newsletter#details`, `{{ page_url }}` is `https://example.com/products/widget`, `{{ page_origin }}` is `https://example.com`, and `{{ page_path }}` is `/products/widget`.
To pass your own values, add a `context` object to `humanizing.init`:
```html theme={null}
```
Then add matching placeholders in **Playground → Instructions (System prompt)**:
```text theme={null}
You are answering for the {{ location }} location.
If the visitor asks about appointments, route them to the {{ department }} team.
```
Learn where to add prompt placeholders, which built-in values are available, and how custom context is validated.
## Verifying Your Installation
After adding the embed code:
1. **Clear your cache** - Ensure you are seeing the latest version of your site
2. **Look for the chat button** - A floating button should appear in the corner
3. **Click to open** - The chat interface should open smoothly
4. **Test a conversation** - Send a test message to verify the connection
Use your browser developer tools (F12) to check for any JavaScript errors if the widget does not appear.
## Troubleshooting
* Verify the agent ID is correct
* Check that your agent is deployed (not in draft mode)
* Ensure no JavaScript errors in the console
* Check for CSS conflicts with z-index
* Verify your domain is allowed in agent settings
* Check that your site uses HTTPS
* Ensure no ad blockers are interfering
* The widget is designed to be responsive
* Avatar panel is hidden on mobile (expected behavior)
* Check viewport meta tag is present
If clicking the copy button does nothing, your browser may be blocking clipboard access.
* Ensure the site is loaded over **HTTPS**
* Check that your browser has not blocked clipboard permissions for this site (look for the permissions icon in the address bar)
* As a fallback, manually select the code and use **Ctrl+C** / **Cmd+C** to copy
## Security Considerations
The widget only works on domains you have authorized in your agent settings. Unauthorized domains will see a connection error.
* Always use HTTPS on your website
* Keep your agent ID confidential (though it is visible in page source)
* Configure allowed domains in the dashboard
## Next Steps
Learn about features available to your visitors.
Configure welcome messages and questions.
Customize the widget appearance.
Track widget usage and conversations.