@convokit/widget

The ConvoKit chat widget for React sites. It answers visitors with AI from your own content, and hands the chat to a person on your team when it needs to.

npm i @convokit/widget

import { ChatWidget } from '@convokit/widget';

<ChatWidget apiKey="pk_live_…" />

In Next.js, render it from a client component ('use client'). The widget mounts into its own shadow root, so your site's CSS can't break it and its CSS can't leak into your site.

PopupWidget is still exported, so installs that use 0.1.x keep working.

Make it yours

<ChatWidget
  apiKey="pk_live_…"
  title="Acme Support"
  subtitle="Usually replies in a few seconds"
  logoUrl="/logo.png"
  primaryColor="#7C3AED"
  theme="auto"
  position="bottom-left"
  launcherLabel="Chat with us"
  teaser="Questions about pricing? Ask here."
  welcomeTitle="Hi there"
  welcomeMessage="How can we help today?"
  suggestions={['How much does it cost?', 'Talk to a person']}
/>

| Prop | Default | What it does | |---|---|---| | apiKey | | Public key from the dashboard (pk_live_…). Never use a secret key here. | | demo | false | Sample replies, no key needed. Good for previews. | | title, subtitle | 'Support', 'Usually replies in a few seconds' | Header text. | | logoUrl, logoFit | , 'cover' | Your logo in the header, the welcome screen and next to replies. | | teamAvatars | | Up to 3 team photos, shown as overlapping faces in the header. | | avatarUrl, botName | logo, 'Assistant' | Avatar and name used for AI replies. | | primaryColor, primaryTextColor | '#2563EB', automatic | Brand colour. Text on it picks black or white for contrast unless you set it. | | gradient | 'wash' | 'wash' (soft brand tint down the chat), 'mesh' (soft brand glows behind the chat) or 'solid' (flat colours). | | theme | 'light' | 'light', 'dark' or 'auto' (follows the visitor's system). | | radius, fontFamily, fontSize | 18, system UI, '14px' | Shape and type. | | position, offset | 'bottom-right', { x: 20, y: 20 } | Where the launcher sits. | | launcherIconUrl, launcherLabel, bubbleSize | , , 52 | Launcher image, optional text label, size. | | teaser, teaserDelay | , 4000 | A short message that pops out of the launcher. Dismissed for the rest of the session once closed. | | welcomeTitle, welcomeMessage, suggestions | 'Hi there', 'How can we help today?', [] | The first screen. Up to 4 suggestions. | | inputStyle | 'outline' | Message box look: 'outline', 'filled', 'pill' or 'underline'. | | sendIcon, sendShape, sendLabel | 'arrow-up', 'rounded', | Send button: icon ('arrow-up', 'arrow-right', 'plane', 'none'), shape ('rounded' or 'circle'), and optional text such as 'Send'. | | placeholder, showTimestamps | 'Write a message…', true | Composer text and message times. | | panelWidth, panelHeight | 360, 580 | Panel size on desktop. On phones it goes full screen. | | persist | 'session' | Keep the chat across reloads in this tab ('session'), this browser ('local'), or not at all ('none'). | | openByDefault, open, onOpenChange, hideLauncher | | Open it yourself, e.g. from a "Contact us" button. | | onMessage, onAgentJoined, onError | | Events for analytics or your own UI. | | apiUrl, widgetId, instanceId, zIndex | | Advanced. |

Every widget shows a small "Powered by ConvoKit" link under the message box.

Live chat

When the assistant decides a person should take over, the visitor sees that the team has been told and can keep writing. When someone takes the chat in the ConvoKit dashboard, the header switches to their name, their replies show with their name, and the visitor sees them typing. The visitor's typing shows in your inbox too.

Try every option

npm run dev

This opens the widget studio: change the logo, colours, text and layout, watch the widget update, and copy the code.