# Embed

> Add your agent to any website as a chat widget, with a script tag, npm package, or iframe.

Source: https://docs.getlinkai.com/getting-started/embed

Put your agent on your website as a chat widget. Customers start a conversation without leaving the page, and every thread lands in your [Inbox](https://docs.getlinkai.com/products/inbox).

**Warning: Allowed domains are required**
The widget only loads on domains you add to the allowed list. This stops others from copying your embed code, using up your limits, or reaching your conversations. Add your domains before you embed. See [Set up the widget](#set-up-the-widget).

## Widget styles

Pick the style that fits your site.

### Standard button

A chat button that expands into a full chat drawer.

- Chat button with your agent avatar or an animated orb
- Drawer-style chat window
- Glass, white, or black background
- Optional animated border

### Floating input

A minimal floating input field that expands into the full chat.

- Floating input field
- Custom accent color
- Expansion animation
- Voice input, if enabled

## Set up the widget

### Open the widget settings

Open **My Agents**, select your agent, and go to the **Deploy** tab. On the **Website** row ("Chat widget on your website"), turn the toggle on and open its settings.

### Choose a style

**Standard button:**
- **Style:** Glass, White, or Black background
- **Chat Button Title:** the welcome line on the button, for example "Hi, let's chat!"
- **Button Avatar:** agent avatar or animated orb
- **Border:** simple or animated gradient

**Floating input:**
- **Accent Color:** border, send button, and focus ring color
- **Button Avatar:** agent avatar or animated orb
- **Suggested questions:** when the floating input opens, up to three starter questions appear as bubbles. Configure them on the agent: up to four questions, 120 characters each.

**Orb animations (both styles):** Glint, Orb, Command, Mana, or Halo. Mana, Command, Glint, and Halo accept custom hex colors.

### Add allowed domains

1. In the **Website** settings, find **Domain Security Settings**.
2. Click **Add Domain** and enter your domain, for example `example.com`.
3. For subdomains, use a wildcard: `*.example.com`.
4. Add every domain where the widget will appear.
5. Click **Save**.

| Entry | What it allows |
|-------|----------------|
| `example.com` | Only that exact domain |
| `*.example.com` | All subdomains, such as `app.example.com` and `shop.example.com` |
| `example.com` and `www.example.com` | Both, if your site uses both |
| `localhost:3000` or `127.0.0.1:3000` | Local development |

Any other domain is blocked and the widget won't appear.

### Copy the embed code

The embed code appears once at least one allowed domain is saved. Choose an [embedding method](#embedding-methods), click **Copy Code**, and paste it into your site.

### Check that it loads

Open a page on an allowed domain and look for the widget.

**Check:**
You should see the chat button or floating input on the page. Send a test message and the agent replies.

---

## Embedding Methods

### Method 1: Script Tag (Recommended)

Works on any website including WordPress, Shopify, Wix, Squarespace, and custom sites.

```html
<script>
  window.chatbotConfig = { 
    chatbotId: 'your-agent-id',
    apiUrl: 'https://dashboard.getlinkai.com'
  };
  
  (function() {
      var script = document.createElement('script');
      script.src = window.chatbotConfig.apiUrl + '/chatbot.js?v=' + Date.now();
      document.head.appendChild(script);
  })();
</script>
```

**Where to place this code:**
- **WordPress**: Use a custom HTML block or add to your theme's footer
- **Shopify**: Add to `theme.liquid` before the closing `</body>` tag
- **Wix**: Use the "Custom Code" feature in site settings
- **Squarespace**: Add to Footer Code Injection in site settings
- **Custom Sites**: Place before the closing `</body>` tag

### Method 2: NPM Package (React/Next.js)

For React or Next.js applications, use our NPM package:

```bash
npm install @linkai/widget
```

Then import and use the component:

```tsx
import { LinkAIWidget } from '@linkai/widget';

function App() {
  return (
    <div>
      {/* Your app content */}
      <LinkAIWidget agentId="your-agent-id" />
    </div>
  );
}
```

### Method 3: Direct Iframe Embed

When you need more control over placement:

**Button Embed**
```html
<iframe 
  src="https://dashboard.getlinkai.com/embed/your-agent-id/button"
  style="position: fixed; bottom: 20px; right: 20px; border: none; width: 400px; height: 600px; z-index: 9999;"
  allow="microphone"
></iframe>
```

**Window Embed (Full Chat Interface)**
```html
<iframe 
  src="https://dashboard.getlinkai.com/embed/your-agent-id/window"
  style="border: none; width: 100%; height: 600px;"
  allow="microphone"
></iframe>
```

---

## Platform guides

### WordPress

1. Install a custom HTML plugin (e.g., "Insert Headers and Footers")
2. Go to **Settings > Insert Headers and Footers**
3. Paste the embed code in the **Footer** section
4. Save changes

**Alternative:** Add to your theme's `footer.php` file before `</body>`

### Shopify

1. Go to **Online Store > Themes**
2. Click **Actions > Edit code**
3. Open `theme.liquid`
4. Paste the embed code before the closing `</body>` tag
5. Save changes

### Wix

1. Go to **Settings > Custom Code**
2. Click **+ Add Custom Code**
3. Paste the embed code
4. Set placement to **Body - End**
5. Apply to all pages
6. Save and publish

### Squarespace

1. Go to **Settings > Advanced > Code Injection**
2. Paste the embed code in the **Footer** section
3. Save changes

### Webflow

1. Go to **Project Settings > Custom Code**
2. Paste the embed code in the **Footer Code** section
3. Save and publish

---

## Public agent pages

You can also publish a branded chat page, with no embed snippet required. See [Pages](https://docs.getlinkai.com/products/pages).

- URL: `https://pages.getlinkai.com/@your-handle`
- The page uses your workspace [brand](https://docs.getlinkai.com/account/branding) (logo and accent) unless you turn brand off
- Assign the agent that should answer
- Edit title, handle, and SEO in Ally's Pages view, then publish

Use a public page when you want a shareable link (bio, ads, QR) instead of a widget on an existing site. Domain allowlisting still applies to the embed widget, not to the public page host.

## Widget features

### Real-Time Chat
- Instant message delivery
- Typing indicators
- Conversation persistence

### Voice Input
Voice mode allows customers to speak to your agent directly from the widget.

- Voice-to-text transcription (if enabled)
- Real-time audio processing
- Multi-language support

### File Attachments
- Upload images and documents (if enabled)
- Drag-and-drop support

### Mobile Optimization
- Responsive design
- Touch-friendly interface
- Optimized for all screen sizes

### Theme Support
The widget automatically detects and synchronizes with your website's light/dark theme.

---

## Programmatic control

Control the widget from your own JavaScript:

### Opening the Widget
```javascript
const widget = document.querySelector('linkai-widget');
if (widget && widget.openChat) {
  widget.openChat();
}
```

### Closing the Widget
```javascript
const widget = document.querySelector('linkai-widget');
if (widget && widget.closeChat) {
  widget.closeChat();
}
```

### Listening to Events
```javascript
window.addEventListener('linkai-widget-opened', () => {
  console.log('Widget opened');
});

window.addEventListener('linkai-widget-closed', () => {
  console.log('Widget closed');
});
```

---

## Troubleshooting

### Widget Not Appearing

**Check Domain Configuration:**
1. Verify your domain is added to the allowed domains list
2. Ensure the domain matches exactly (including `www` if applicable)
3. Check browser console for error messages

**Check Embed Code:**
1. Verify the `chatbotId` is correct
2. Ensure the script is placed before the closing `</body>` tag
3. Check for JavaScript errors in the browser console

**Clear Cache:**
1. Clear your browser cache
2. Hard refresh the page (Ctrl+Shift+R or Cmd+Shift+R)
3. Try in an incognito/private window

### Domain Validation Error

A "Domain validation failed" error means domain security is blocking a domain that isn't on your allowed list.

**To Fix:**
1. Verify the domain is added to your allowed domains list in the dashboard
2. Check the exact domain in your browser's address bar. It must match exactly
3. If you're using `www`, add both `example.com` and `www.example.com`
4. For subdomains, use wildcard notation: `*.example.com`
5. Wait a few minutes after adding domains for changes to propagate
6. Clear your browser cache and hard refresh (Ctrl+Shift+R or Cmd+Shift+R)

**Common Mistakes:**
- Forgetting to include `www` when your site uses it
- Using `http://` instead of `https://` in the domain list (only add the domain name, not the protocol)
- Typos in the domain name
- Using the widget on a subdomain without wildcard configuration

### Voice Features Not Working

1. Verify voice is enabled in your agent settings
2. Check browser permissions for microphone access
3. Ensure you're using HTTPS (voice requires secure context)
4. Test in a supported browser (Chrome, Edge, Safari)

---

## Next steps

**[Configure Agent](https://docs.getlinkai.com/agents/configure-agent)**:
Set the instructions, persona, and welcome message the widget uses.

**[Channels](https://docs.getlinkai.com/agents/channels)**:
Add phone, SMS, WhatsApp, Instagram, and more.

**[Pages](https://docs.getlinkai.com/products/pages)**:
Share a branded chat link instead of embedding.

**[Analytics](https://docs.getlinkai.com/account/analytics)**:
Track conversations and performance.

Need help? Email [support@getlinkai.com](mailto:support@getlinkai.com).