Embedding Chatbot

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.

Open agent settings

Navigate to your agent and access the Settings section.

Enable public access

In the settings panel, locate and toggle on the Public Access option to make your agent available for embedding.

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.

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.

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

Add the container element

Add this container to your HTML

<div id="artaios-chatbot-root"></div>

Load and initialize the script

Add this script after the container element:

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

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

Artaios supports three display modes:

Floating Button

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.

In-Place

The chat interface is rendered directly in the page, always visible and expanded. Ideal for dedicated support pages or embedded chat sections.

Modal

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.

Set the display mode using the type property in your configuration (see Technical configuration 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 for visual examples (default: `floatingButton`)
`userToken`	`string`	JWT token for user identification and session persistence (see 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

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

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:

// 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:

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:

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:

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

Open the chat as a centered overlay:

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:

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.

Want to connect via WebSocket to build your own frontend? Drop us a message at lorenz.stirnweis@arttacsolutions.de.

Getting started

Agent Configuration

Multi Agent Systems

Advanced Features

Artaios Agents Studio

Platform

Integration

Set up your public chatbot

Step 1: Enable public access

Step 2: Embed the widget

Add the container element

Load and initialize the script

Widget types

Floating Button

In-Place

Modal

Step 3: Configure your chatbot (optional)

Configuration reference

Technical

Content

Images

Styling / Theming

Theme

Audio

Voice configuration

User identification

Configuration examples

Minimal setup

Customer support bot

Fully customized with theming

With audio capabilities

Troubleshooting

Next steps

​Set up your public chatbot

​Step 1: Enable public access

​Step 2: Embed the widget

​Add the container element

​Load and initialize the script

​Widget types

Floating Button

In-Place

Modal

​Step 3: Configure your chatbot (optional)

​Configuration reference

​Technical

​Content

Images

​Styling / Theming

Theme

​Audio

Voice configuration

​User identification

​Configuration examples

​Minimal setup

​Customer support bot

​Fully customized with theming

​Modal dialog

​With audio capabilities

​Troubleshooting

​Next steps

Set up your public chatbot

Step 1: Enable public access

Step 2: Embed the widget

Add the container element

Load and initialize the script

Widget types

Step 3: Configure your chatbot (optional)

Configuration reference

Technical

Content

Styling / Theming

Audio

User identification

Configuration examples

Minimal setup

Customer support bot

Fully customized with theming

Modal dialog

With audio capabilities

Troubleshooting

Next steps