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

# Embedding Chatbot

> Integrate your agents into chatbots and messaging platforms

## Set up your public chatbot

The public chatbot is an embeddable chat widget that you can integrate into your website. This guide walks you through the complete setup process.

## Step 1: Enable public access

Before embedding your chatbot, configure your agent's public settings.

<Steps>
  <Step title="Open agent settings">
    Navigate to your agent and access the **Settings** section.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/arttacsolutions/images/agent_settings.png" alt="Agent settings panel" />
    </Frame>
  </Step>

  <Step title="Enable public access">
    In the settings panel, locate and toggle on the **Public Access** option to make your agent available for embedding.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/arttacsolutions/images/agent_settings_opened.png" alt="Public access toggle" />
    </Frame>
  </Step>

  <Step title="Add your domain">
    Enter the domain where you'll be embedding the chatbot. This should be your website's URL (for example, `docs.yourcompany.com`). This ensures the chatbot only loads on authorized domains. You can use `http://localhost:port` for testing purposes.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/arttacsolutions/images/agent_settings_enabled.png" alt="Domain allowlist configuration" />
    </Frame>
  </Step>

  <Step title="Save and copy your Agent Key">
    Press **Save URL** to confirm your settings. You'll see your **Agent Key** displayed, copy this key — you'll need it in the next step to embed the chatbot on your website.
  </Step>
</Steps>

## Step 2: Embed the widget

Add the Artaios chatbot to your website using the following code.

### Add the container element

Add this container to your HTML

```html theme={null}
<div id="artaios-chatbot-root"></div>
```

### Load and initialize the script

Add this script after the container element:

```html theme={null}
<script>
  document.addEventListener('DOMContentLoaded', function() {
    const scriptElement = document.createElement('script');
    scriptElement.src = 'https://static.arttacsolutions.com/js/artaios.js/latest/artaios.umd.js';
    scriptElement.async = true;

    scriptElement.onload = function() {
      setTimeout(function() {
        try {
          if (window.artaios && typeof window.artaios.initialize === 'function') {
            window.artaios.initialize({
              agentKey: 'YOUR_AGENT_KEY',
              elementId: 'artaios-chatbot-root',
              type: 'floatingButton',
              placeholder: 'Write a message...',
              welcomeMessage: 'Hi! How can I help you?'
            });
          }
        } catch (error) {
          console.error('Failed to initialize Artaios chatbot:', error);
        }
      }, 200);
    };

    scriptElement.onerror = function(error) {
      console.error('Failed to load Artaios chatbot script:', error);
    };

    document.head.appendChild(scriptElement);
  });
</script>
```

Replace `YOUR_AGENT_KEY` with the Agent Key you copied from the agent settings.

<Check>
  When the page loads, you see the chatbot launcher button and you can open a conversation.
</Check>

### Widget types

Artaios supports three display modes:

<CardGroup cols={3}>
  <Card title="Floating Button" icon="comment">
    A collapsible chat widget that appears as a button in the bottom corner of your page (position configurable). Users click to expand the chat interface.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/arttacsolutions/images/floating_button.png" alt="Floating button widget collapsed in bottom left corner" />
    </Frame>
  </Card>

  <Card title="In-Place" icon="window">
    The chat interface is rendered directly in the page, always visible and expanded. Ideal for dedicated support pages or embedded chat sections.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/arttacsolutions/images/inPlace.png" alt="In-place widget rendered opened in the center" />
    </Frame>
  </Card>

  <Card title="Modal" icon="window-maximize">
    A centered overlay dialog that opens from a launcher button. The chat appears over a semi-transparent backdrop (clicking the backdrop closes it). On mobile screens (\<600px), the modal goes full-screen.
  </Card>
</CardGroup>

Set the display mode using the `type` property in your configuration (see [Technical configuration](#technical) below).

## Step 3: Configure your chatbot (optional)

You can customize the chatbot's appearance and behavior by passing additional parameters to `window.artaios.initialize()`.

### Configuration reference

The `initialize` function accepts an `ArtaiosOptions` object organized into the following categories:

#### Technical

Core technical configuration for the chatbot widget:

| Property            | Type                                       | Description                                                                                                       |
| ------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `agentKey`          | `string`                                   | Your agent identifier (required)                                                                                  |
| `connectionKey`     | `string`                                   | **Deprecated** — use `agentKey` instead. Only needed for legacy non-AMAS agents                                   |
| `elementId`         | `string`                                   | ID of the container element (default: `artaios-chatbot-root`)                                                     |
| `type`              | `'floatingButton' \| 'inPlace' \| 'modal'` | Chat widget display type - see [Widget types](#widget-types) for visual examples (default: `floatingButton`)      |
| `userToken`         | `string`                                   | JWT token for user identification and session persistence (see [User identification](#user-identification) below) |
| `enableAttachments` | `boolean`                                  | Allow users to attach files in the chat (default: `false`)                                                        |

#### Content

Content and messaging configuration:

| Property                   | Type       | Description                                            |
| -------------------------- | ---------- | ------------------------------------------------------ |
| `placeholder`              | `string`   | Custom placeholder text for the message input field    |
| `welcomeMessage`           | `string`   | Custom message displayed when chat opens               |
| `disclaimer`               | `string`   | Legal disclaimer displayed at the start of the chat    |
| `persistentDisclaimer`     | `string`   | Disclaimer that remains visible throughout the chat    |
| `hintQuestions`            | `string[]` | Array of suggested questions to help users get started |
| `feedbackInputPlaceholder` | `string`   | Placeholder for feedback input field                   |
| `feedbackInputCaptionText` | `string`   | Caption text for feedback section                      |

##### Images

The `images` object allows you to customize branding:

| Property                       | Type      | Description                                                                 |
| ------------------------------ | --------- | --------------------------------------------------------------------------- |
| `images.assistant`             | `string`  | URL to custom assistant avatar image                                        |
| `images.assistantNoBackground` | `boolean` | Whether the assistant image has no background (default: `false`)            |
| `images.launcher`              | `string`  | URL to a custom launcher button icon (floating button and modal modes only) |

#### Styling / Theming

Visual appearance and styling configuration:

| Property              | Type      | Description                                                       |
| --------------------- | --------- | ----------------------------------------------------------------- |
| `launcherTooltip`     | `string`  | Tooltip text shown when hovering over the launcher button         |
| `launcherRight`       | `boolean` | Position launcher on the right side (default: `false`)            |
| `launcherExtraShadow` | `boolean` | Add extra shadow effect to the launcher button (default: `false`) |
| `font`                | `string`  | Custom font family for the chat widget                            |

##### Theme

The `theme` object allows you to customize colors and appearance:

| Property                      | Type      | Description                                                  |
| ----------------------------- | --------- | ------------------------------------------------------------ |
| `theme.dark`                  | `boolean` | Enable dark mode (default: `false`)                          |
| `theme.accentColor`           | `string`  | Primary accent color (hex format)                            |
| `theme.assistantMessage.bg`   | `string`  | Background color for assistant messages                      |
| `theme.assistantMessage.text` | `string`  | Text color for assistant messages                            |
| `theme.userMessage.bg`        | `string`  | Background color for user messages                           |
| `theme.userMessage.text`      | `string`  | Text color for user messages                                 |
| `theme.launcher.bg`           | `string`  | Background color for the launcher button when chat is closed |
| `theme.launcher.bgOpen`       | `string`  | Background color for the launcher button when chat is open   |

#### Audio

<Note>
  Audio features are only available if you have subscribed to the appropriate tier and saved an ElevenLabs API key in the platform settings.
</Note>

Audio input/output configuration:

| Property             | Type      | Description                                                       |
| -------------------- | --------- | ----------------------------------------------------------------- |
| `enableAudio`        | `boolean` | Enable audio input/output capability (default: `false`)           |
| `playAudioByDefault` | `boolean` | Auto-play audio responses when audio is enabled (default: `true`) |

##### Voice configuration

The `voiceConfig` object configures audio output voice settings (requires `enableAudio: true`):

| Property                         | Type      | Description                                    |
| -------------------------------- | --------- | ---------------------------------------------- |
| `voiceConfig.model_id`           | `string`  | Voice model to use (e.g., `eleven_turbo_v2_5`) |
| `voiceConfig.voice_id`           | `string`  | Specific voice identifier                      |
| `voiceConfig.speed`              | `number`  | Speech speed (0.5 to 2.0)                      |
| `voiceConfig.stability`          | `number`  | Voice consistency (0.0 to 1.0)                 |
| `voiceConfig.similarity_boost`   | `number`  | Voice similarity level (0.0 to 1.0)            |
| `voiceConfig.use_speaker_boost`  | `boolean` | Enhance speaker clarity                        |
| `voiceConfig.style_exaggeration` | `number`  | Emotional expression level (0.0 to 1.0)        |

#### User identification

Pass a `userToken` (a JWT with a `sub` claim) to enable chat history persistence across sessions. Without a token, each page load starts a fresh conversation.

You can update the token after initialization — for example, after a user logs in:

```javascript theme={null}
// After the user authenticates on your site
window.artaios.updateUserToken('eyJhbGciOiJIUz...');
```

This updates the active WebSocket connection without reinitializing the widget.

### Configuration examples

#### Minimal setup

Just the essentials:

```javascript theme={null}
window.artaios.initialize({
  agentKey: 'YOUR_AGENT_KEY',
  elementId: 'artaios-chatbot-root',
  welcomeMessage: 'Welcome to our support chatbot!'
});
```

#### Customer support bot

With hint questions and feedback:

```javascript theme={null}
window.artaios.initialize({
  agentKey: 'YOUR_AGENT_KEY',
  elementId: 'artaios-chatbot-root',
  type: 'floatingButton',
  launcherTooltip: 'Need help? Chat with us!',
  welcomeMessage: 'Hi! How can I assist you today?',
  hintQuestions: [
    'How do I reset my password?',
    'What are your business hours?',
    'How do I contact support?'
  ],
  feedbackInputPlaceholder: 'Tell us how we did...',
  placeholder: 'Type your question here...'
});
```

#### Fully customized with theming

Complete customization with branding and theme:

```html theme={null}
<script>
  document.addEventListener('DOMContentLoaded', function() {
    const scriptElement = document.createElement('script');
    scriptElement.src = 'https://static.arttacsolutions.com/js/artaios.js/latest/artaios.umd.js';
    scriptElement.async = true;

    scriptElement.onload = function() {
      setTimeout(function() {
        if (!window.artaios || typeof window.artaios.initialize !== 'function') return;

        window.artaios.initialize({
          agentKey: 'YOUR_AGENT_KEY',
          elementId: 'artaios-chatbot-root',
          type: 'floatingButton',
          placeholder: 'Write a message...',
          welcomeMessage: 'Hello! How can I help you?',
          launcherRight: false,
          launcherExtraShadow: true,
          hintQuestions: [
            'What products do you offer?',
            'How do I get started?',
            'Where can I find documentation?'
          ],
          theme: {
            dark: false,
            accentColor: '#4e8cff',
            assistantMessage: {
              bg: '#f5f5f5',
              text: '#333333'
            },
            userMessage: {
              bg: '#4e8cff',
              text: '#ffffff'
            },
            launcher: {
              bg: '#4e8cff',
              bgOpen: '#333333'
            }
          },
          images: {
            assistant: 'https://static.arttacsolutions.com/img/icon_atthene_interaction.svg',
            assistantNoBackground: false
          }
        });
      }, 200);
    };

    document.head.appendChild(scriptElement);
  });
</script>
```

#### Modal dialog

Open the chat as a centered overlay:

```javascript theme={null}
window.artaios.initialize({
  agentKey: 'YOUR_AGENT_KEY',
  elementId: 'artaios-chatbot-root',
  type: 'modal',
  welcomeMessage: 'Hello! Ask me anything.',
  theme: {
    launcher: {
      bg: '#4e8cff',
      bgOpen: '#333333'
    }
  }
});
```

#### With audio capabilities

Enable voice interaction:

```javascript theme={null}
window.artaios.initialize({
  agentKey: 'YOUR_AGENT_KEY',
  elementId: 'artaios-chatbot-root',
  enableAudio: true,
  playAudioByDefault: true,
  voiceConfig: {
    model_id: 'eleven_turbo_v2_5',
    voice_id: 'JBFqnCBsd6RMkjVDRZzb',
    speed: 1.0,
    stability: 0.5,
    similarity_boost: 0.8,
    use_speaker_boost: false,
    style_exaggeration: 0.0
  }
});
```

## Troubleshooting

* **Launcher does not appear**: Confirm you added the container element and that `elementId` matches the container `id`.
* **Loads locally but not in production**: Verify your production domain is allowlisted in agent settings.
* **Console shows a script error**: Confirm the `scriptElement.src` URL is reachable from your site.
* **Agent Key error**: Ensure you copied the full Agent Key without extra spaces or characters.

## Next steps

* **Monitor performance**: Review agent analytics to see how visitors use the chatbot.
* **Test thoroughly**: Verify the widget works across devices and browsers.
* **Iterate on configuration**: Tune welcome text, theme, and launcher placement based on user feedback.
* **Collect user feedback**: Use the feedback feature to continuously improve responses.

<Tip>
  Want to connect via WebSocket to build your own frontend? Drop us a message at [lorenz.stirnweis@arttacsolutions.de](mailto:lorenz.stirnweis@arttacsolutions.de).
</Tip>