andy-widget-react

The official React Widget for Andy. Its canonical source is Andesphere/andy-sdk.

Install

Pin an exact reviewed release:

bun add [email protected]

React and React DOM 18 or 19 are required peer dependencies.

Use

'use client'

import { AndyChat, setApiBaseUrl } from 'andy-widget-react'

setApiBaseUrl('https://app.andypartner.com/api')

export function SupportWidget() {
	return <AndyChat embedId='your-agent-id' />
}

embedId is the non-secret Andy Agent ID. The Widget fetches its effective configuration from GET /api/chatbot/:embedId and sends visitor messages to POST /api/messages. The browser sends the embedding page's Origin; Andy enforces the Agent's exact allowed-origin configuration.

The launcher starts closed. If the Agent ID is invalid or configuration cannot be loaded, the Widget renders no launcher and does not affect the host page. Message failures remain inside the Widget as a short, language-aware retry message.

Props

| Prop | Type | Purpose | | --- | --- | --- | | embedId | string | Required Agent ID outside preview mode | | tooltip | string | Optional launcher tooltip | | name | string | Override the configured Agent name | | headline | string | Override the configured headline | | description | string | Override the configured description | | welcomeMessage | string | Override the configured first message | | bubbleLabel | string | Override the configured pill label | | theme | 'light' \| 'dark' \| 'auto' | Override the configured theme | | orientation | 'left' \| 'right' | Override the configured position | | brandColor | string | Override the configured six-digit hex color | | bubbleStyle | 'icon' \| 'pill' | Override the configured launcher style | | useBrandColor | boolean | Override configured brand-color use | | logoUrl | string | Override the configured logo | | previewMode | boolean | Render local prop-based preview configuration | | initialOpen | boolean | Opt into an initially open Widget; defaults to false |

The server configuration controls Powered by Andy visibility. Consumers cannot suppress it with a prop. FAQ entries render only when the API supplies both a question and an answer; the current question-only response safely exposes no incomplete FAQ. Visitor-information and lead capture are disabled in this release because there is no durable public submission boundary.

This release intentionally has no Widget analytics or event callback API. Use Andy's existing conversation analytics rather than observing the Shadow DOM.

Advanced exports

The package also exports useAndyChat, individual presentation components, its public TypeScript types, design tokens, getApiBaseUrl, and setApiBaseUrl. Andy remains a compatibility alias for AndyChat; new integrations should use AndyChat.

Supported integration path

Use the React package directly. Do not use an iframe, a floating @latest dependency, or Andy's legacy hosted /widget.js redirect for new integrations.

License

MIT