Skip to content

README.md

Latest commit

 

History

History
288 lines (229 loc) · 7.75 KB

README.md

File metadata and controls

288 lines (229 loc) · 7.75 KB

@uipath/ap-chat

A flexible chat interface component provided as a framework-agnostic web component, making it usable in any framework or vanilla JavaScript.

Overview

The ap-chat web component provides AI assistant functionality with a powerful service-based API. The component includes:

  • A resizable and collapsible UI that can operate in side-by-side, full-screen, or embedded mode
  • Support for text messages with markdown formatting and citations
  • File attachments with drag-and-drop support
  • Customizable first-run experience with suggested prompts
  • Extensible architecture with custom message renderers
  • Event system for intercepting and handling chat interactions
  • Support for real-time streaming responses and simulated streaming
  • Interactive message actions system
  • Comprehensive conversation history management
  • Settings panel with customizable content
  • Real-time voice input and output streaming
  • Model and agent mode selection
  • Custom header actions with nested menus
  • Loading and waiting state management
  • Pagination support for large conversations

Bundle & Performance

This package is a self-contained web component with all dependencies bundled (React, Material-UI, etc.):

  • Format: ESM only (no CommonJS) - requires modern bundlers and Node.js 14+
  • Code splitting: Vendor chunks and locales are lazy-loaded on demand
  • Tree-shaking: Not applicable (self-contained bundle)

Why ESM-only?

Web components are designed for modern browsers and bundlers. If you need CommonJS support, use the React components from @uipath/apollo-react directly instead.

Installation

npm install @uipath/ap-chat
# or
pnpm add @uipath/ap-chat
# or
yarn add @uipath/ap-chat

Note: This package is published to both npm and GitHub Package Registry. External users will automatically pull from npm. Internal UiPath users with .npmrc configured will automatically pull from GitHub Package Registry.

Usage

Vanilla JavaScript / HTML

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>AP Chat Example</title>
</head>
<body>
  <ap-chat id="chat"></ap-chat>

  <script type="module">
    import { AutopilotChatService } from '@uipath/ap-chat/service';
    import '@uipath/ap-chat';

    // Create and initialize the service
    const service = AutopilotChatService.Instantiate({
      instanceName: 'my-chat',
      config: {
        mode: 'side-by-side',
        firstRunExperience: {
          title: "Welcome to Autopilot Chat!",
          description: "Ask me anything about your data or how to use this application.",
          suggestions: [
            { label: "Get started", prompt: "How do I get started?" },
            { label: "Show features", prompt: "What features are available?" }
          ]
        }
      }
    });

    // Set the service instance and properties on the web component
    const chatElement = document.getElementById('chat');
    chatElement.chatServiceInstance = service;
    chatElement.locale = 'en';
    chatElement.theme = 'light';

    // Listen for user requests
    service.on('Request', (data) => {
      console.log('User sent:', data.content);

      // Send a response
      setTimeout(() => {
        service.sendResponse({
          content: `Echo: ${data.content}`,
          role: 'assistant'
        });
      }, 1000);
    });

    // Open the chat
    service.open();
  </script>
</body>
</html>

React

For React applications, use the @uipath/apollo-react package directly instead of the web component:

import { ApChat, AutopilotChatService, AutopilotChatMode } from '@uipath/apollo-react/ap-chat';

function App() {
  const service = AutopilotChatService.Instantiate({
    instanceName: 'my-chat',
    config: {
      mode: AutopilotChatMode.SideBySide
    }
  });
  // ... use ApChat React component directly
}

See the @uipath/apollo-react documentation for details.

Web Component Properties

The <ap-chat> element exposes the following JavaScript properties:

// Chat service instance (required)
chatElement.chatServiceInstance = service;

// Locale (optional, default: 'en')
// Supported: 'en', 'de', 'es', 'es-MX', 'fr', 'ja', 'ko', 'pt', 'pt-BR', 'ru', 'tr', 'zh-CN', 'zh-TW'
chatElement.locale = 'en';

// Theme (optional, default: 'light')
// Supported: 'light', 'dark', 'light-hc', 'dark-hc'
chatElement.theme = 'light';

Chat Service API

The complete chat service API documentation is available in the @uipath/apollo-react package documentation.

Quick Reference

Configuration & Initialization

  • initialize(config) - Initialize the chat service
  • open() - Open the chat interface
  • close() - Close the chat interface
  • setChatMode(mode) - Set chat window mode ('side-by-side', 'full-screen', 'embedded')
  • setLocale(locale) - Change locale dynamically
  • setTheme(theme) - Change theme dynamically

Message Handling

  • sendRequest(message) - Send a user request
  • sendResponse(message) - Send an AI response
  • setConversation(messages) - Set entire conversation
  • getConversation() - Get current conversation
  • setPrompt(prompt) - Set input field value
  • setSuggestions(suggestions) - Show suggestion chips

Event Handling

  • on(event, handler) - Subscribe to events
  • intercept(event, interceptor) - Intercept events

Common Events

  • Request - User sends a message
  • Response - AI response received
  • ModeChange - Chat mode changed
  • Open - Chat opened
  • Close - Chat closed

Example: Streaming Response

import { AutopilotChatService } from '@uipath/ap-chat/service';

const service = AutopilotChatService.Instantiate({
  instanceName: 'streaming-chat',
  config: {
    mode: 'side-by-side'
  }
});

// Stream a response word by word
const messageId = 'stream-' + Date.now();
const words = ['Hello', 'World', 'This', 'is', 'streaming'];

words.forEach((word, index) => {
  setTimeout(() => {
    service.sendResponse({
      id: messageId,
      content: word,
      stream: true,
      done: index === words.length - 1
    });
  }, index * 200);
});

Example: Citations

service.sendResponse({
  role: 'assistant',
  contentParts: [
    {
      text: 'The NBA Finals are the annual championship series.',
      citations: [
        {
          id: 1,
          title: 'NBA Official Finals Overview',
          url: 'https://www.nba.com/history/finals'
        }
      ]
    }
  ]
});

Example: Custom Actions

service.sendResponse({
  content: 'Here is your data analysis',
  actions: [
    {
      name: 'export',
      label: 'Export Data',
      icon: 'download',
      eventName: 'export-data'
    }
  ]
});

service.on('export-data', ({ message, action }) => {
  console.log('Export triggered for message:', message.id);
});

Complete Documentation

For comprehensive documentation including:

  • All service methods and parameters
  • Event system details
  • Message renderers
  • History management
  • Settings panel
  • Model and agent mode selection
  • Streaming and citations
  • And much more...

See the complete documentation.

TypeScript Support

The package includes full TypeScript definitions. Import types from the service:

import {
  AutopilotChatService,
  AutopilotChatMessage,
  AutopilotChatConfiguration,
  AutopilotChatEvent
} from '@uipath/ap-chat/service';

Browser Support

The web component uses modern browser features:

  • Custom Elements v1
  • Shadow DOM v1
  • ES Modules

Supported browsers:

  • Chrome/Edge 88+
  • Firefox 90+
  • Safari 14+

License

MIT