Skip to main content

Embedding an agent into a webpage

This feature allows you to seamlessly embed your agent as a widget into any website. Customize the look and feel of your chat widget and its launch experience to match your branding using the intuitive AI editor. You can access the editor on the Deploy tab.

There are three tabs in the embedded editor:

  • Chat Window - design the appearance of your chat window with full control over its visual elements. Adjust colors for text, icons, and the background, and define the shape of the chat window to align with your brand.

  • AI Button - personalize the style and placement of the button that activates the chat widget on your website.

    AIbutton

  • Launch - specify the URLs where your custom chat widget will be embedded to ensure secure and authorized usage. Specifying the correct URLs is essential, as the chat widget will not function without them. You can add multiple URLs and easily access the embed code, which can be copied into the website's header for seamless integration.

Here's an example of how you can use the chat widget. After customizing your widget, enter a URL (of your choice) in the Launch tab, as shown below. Also, embed the component code into your website's header to render a chat dialog.

Launch

There are different ways to add the embed code to your site, depending on the technology you use. However, ensure that the code is injected as HTML on your page.

For instance, if you're using Google Tag Manager, you can create a new 'Custom HTML' tag and configure it to trigger on DOM Ready.

Navigate to the URL to access your AI chat widget:

Custom UI deployment​

If you need full control over the chat experience — your own branding, layout, and behavior — you can use the custom deployment mode instead of the standard embed script. This gives you an embed key and API endpoint that you can integrate directly into your own code.

Switching to custom mode​

  1. Open your agent's Deploy tab and go to the embed editor.
  2. If you haven't generated a widget yet, click Generate Widget first.
  3. Check "Use custom UI integration" at the top of the editor.
  4. The editor switches to show:
    • Your embed key with a copy button
    • The API endpoint with a copy button
    • A Quick Start Guide with integration steps
    • Ready-to-use code samples for initializing sessions, sending messages, and a React hook example
    • Security best practices for your integration
  5. Add your website URLs to the allowlist (required for the integration to work).
  6. Click Save Changes.

You can switch back to the standard widget at any time by unchecking the custom UI checkbox.

Integrating with your application​

The custom deployment mode uses two API endpoints:

1. Initialize a session

Send a POST request to the embed client endpoint with your embed key to create a new chat session:

const response = await fetch('https://your-instance.devs.ai/api/v1/embed-client', {
  method: 'POST',
  credentials: 'include',
  body: JSON.stringify({ embedKey: 'ek-abc123def456', chatId: null })
});

const data = await response.json();
const chatId = data.chat.id;
const authorizationContext = data.authorizationContext;

2. Send messages with streaming

Use the chat ID and authorization context to send messages and receive streaming responses via Server-Sent Events (SSE):

import { SSE } from 'sse.js';

const eventSource = new SSE(`https://your-instance.devs.ai/api/v1/chats/${chatId}`, {
  start: false,
  method: 'POST',
  withCredentials: false,
  payload: JSON.stringify({
    prompt: 'Hello, how can you help me?',
    date: new Date().toISOString()
  }),
  headers: {
    'Content-Type': 'application/json; charset=utf-8',
    'X-Embedded-Context': authorizationContext
  }
});

eventSource.addEventListener('message', (event) => {
  console.log('Received:', event.data);
});

eventSource.stream();

3. React integration

The editor also provides a complete useAIChat React hook that handles session initialization, message state, real-time streaming, and abort/cancel support. You can copy it directly from the code samples in the editor and drop it into any React application. It requires the sse.js npm package.

Good to know​

  • The authorization context token expires after 24 hours. Your integration should handle re-initialization when the context expires.
  • The streaming examples use the sse.js library because the standard browser EventSource API does not support POST requests.
  • Existing embed configurations are not affected — the default mode remains the standard widget. Your current setup continues to work as before.
⌘J