@ips-ag/datatalk-chat

A self-contained chat web component built with React and packaged as a native Custom Element (<chat-widget>). It communicates with a DataTalk API over REST and SignalR.

Installation

npm install @ips-ag/datatalk-chat

Usage

Plain HTML / vanilla JS

Register the element by importing the package, then use it as an HTML tag.

<script type="module">
  import '@ips-ag/datatalk-chat';
</script>

<chat-widget
  apihost="https://your-api.example.com"
  selectedtopic="my-topic"
  streamingapi="chathub"
  chatapi="api/v1/chat"
  conversationapi="api/v1/conversations"
  downloadreferenceapi="https://your-api.example.com/api/v1/topics/my-topic/documents"
></chat-widget>

<script type="module">
  const widget = document.querySelector('chat-widget');

  // Required if your API needs an auth token
  widget.onGetAccessToken = () => 'Bearer <token>';
</script>

React

import '@ips-ag/datatalk-chat';

// Extend JSX intrinsic elements if using TypeScript
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'chat-widget': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
        apihost?: string;
        streamingapi?: string;
        chatapi?: string;
        conversationapi?: string;
        downloadreferenceapi?: string;
        selectedtopic?: string;
        conversationid?: string;
      };
    }
  }
}

export const MyPage = () => (
  <chat-widget
    apihost="https://your-api.example.com"
    selectedtopic="my-topic"
    streamingapi="chathub"
    chatapi="api/v1/chat"
    conversationapi="api/v1/conversations"
    downloadreferenceapi="https://your-api.example.com/api/v1/topics/my-topic/documents"  
  />
);

Attributes

| Attribute | Type | Required | Description | |------------------------|----------|----------|--------------------------------------------------------------------| | apihost | string | Yes | Base URL of the DataTalk API | | selectedtopic | string | Yes | Pre-selects a topic in the chat overview | | streamingapi | string | No | SignalR hub path for streaming responses (defaults to 'chathub') | | chatapi | string | No | REST endpoint for sending chat messages (defaults to 'api/v1/chat') | | conversationapi | string | No | REST endpoint for conversation management (defaults to 'api/v1/conversations') | | downloadreferenceapi | string | No | REST endpoint for downloading referenced documents (auto-computed as {apihost}/api/v1/topics/{selectedtopic}/documents if not provided) | | conversationid | string | No | Resumes an existing conversation by ID (defaults to a new UUID) |

Properties

| Property | Type | Description | |--------------------|------------------------|---------------------------------------------------------------------| | onGetAccessToken | () => string | Called before each API request to retrieve a bearer token | | messageHistory | ChatMessage[] | Pre-populates the chat with a set of existing messages |

Styles

The component uses Shadow DOM, so host-page CSS does not bleed in. A bundled stylesheet is also exported separately if you need to include it manually:

import '@ips-ag/datatalk-chat/styles';

Theming

The widget exposes a set of CSS custom properties that cascade into the Shadow DOM. Set them on the <chat-widget> element itself, or on any ancestor element.

Custom properties

| Property | Default | Description | |---|---|---| | --external-primary | #2563eb | Brand colour — send button, input focus ring, user bubble, avatar background | | --external-primary-foreground | #ffffff | Text colour on primary-coloured surfaces | | --external-secondary | #2563eb | Accent colour — links, suggestion chips, like button, overview card hover | | --external-danger | #ef4444 | Danger colour — dislike/thumbs-down feedback button | | --external-border-color | #e2e8f0 | Input and chip border colour | | --external-background-text-input | #ffffff | Chat input field background | | --external-background-user-message | #2563eb | User message bubble background | | --external-foreground-user-message | #ffffff | User message bubble text colour | | --external-background-assistant-message | #f1f5f9 | Assistant message bubble background | | --external-foreground-assistant-message | #1e293b | Assistant message bubble text colour |

Plain HTML

<chat-widget
  style="
    --external-primary: #7c3aed;
    --external-primary-foreground: #ffffff;
    --external-secondary: #0891b2;
    --external-danger: #ef4444;
    --external-border-color: #e2e8f0;
    --external-background-text-input: #ffffff;
    --external-background-user-message: #7c3aed;
    --external-foreground-user-message: #ffffff;
    --external-background-assistant-message: #f5f3ff;
    --external-foreground-assistant-message: #1e1b4b;
  "
  apihost="..."
></chat-widget>

CSS

chat-widget {
  --external-primary: #7c3aed;
  --external-primary-foreground: #ffffff;
  --external-secondary: #0891b2;
  --external-danger: #ef4444;
  --external-border-color: #e2e8f0;
  --external-background-text-input: #ffffff;
  --external-background-user-message: #7c3aed;
  --external-foreground-user-message: #ffffff;
  --external-background-assistant-message: #f5f3ff;
  --external-foreground-assistant-message: #1e1b4b;
}

React

<chat-widget
  style={{
    '--external-primary': '#7c3aed',
    '--external-primary-foreground': '#ffffff',
    '--external-secondary': '#0891b2',
    '--external-danger': '#ef4444',
    '--external-background-user-message': '#7c3aed',
    '--external-background-assistant-message': '#f5f3ff',
    '--external-foreground-assistant-message': '#1e1b4b',
  } as React.CSSProperties}
  apihost="..."
/>