Chat Widget

Drop a fully-featured chat interface into any page with one line. Handles OTP sign-in, streaming responses, quota display, and theming — all built in.

Building a custom UI? See the SDK Reference instead — useGatewayChat gives you full control over rendering.

Script tag (any website)

Add to any HTML page — no build step, no npm, no React required.

<script src="https://hub.aerostack.io/chat.js"
  data-project="your-project"
  data-api="your-api-slug"
  data-mode="bubble">
</script>

This creates a floating chat bubble (bottom-right). Click it to open.

React component

npm install @aerostack/chat-widget

import { AerostackChat } from '@aerostack/chat-widget'
 
export default function MyPage() {
  return (
    <AerostackChat
      project="your-project"
      api="your-api-slug"
      mode="bubble"
      primaryColor="#6366f1"
      welcomeMessage="Hi! How can I help you today?"
    />
  )
}

Embedded mode

Display the chat inline (not as a floating bubble) — useful for chat-first pages.

<AerostackChat
  project="your-project"
  api="your-api-slug"
  mode="embedded"   // renders inline, fills its container
  primaryColor="#10b981"
/>

All props / data attributes

React prop	`data-` attribute	Type	Default	Description
`project`	`data-project`	string	required	Your project slug
`api`	`data-api`	string	required	Your gateway API slug
`mode`	`data-mode`	`"bubble"` \| `"embedded"`	`"bubble"`	Display mode
`primaryColor`	`data-primary-color`	string	`"#FCAB4A"`	Accent color for header, buttons, user bubbles
`welcomeMessage`	`data-welcome-message`	string	—	First message shown from assistant
`placeholder`	`data-placeholder`	string	`"Type a message..."`	Input placeholder
`baseUrl`	`data-base-url`	string	`"https://api.aerocall.ai"`	Override API base URL
`consumerKey`	`data-consumer-key`	string	—	`ask_live_` key (consumer-key-only mode)

Auth behaviour

The widget automatically handles authentication based on your gateway API’s auth_mode:

Aerostack Auth (default): Shows an OTP sign-in modal if no JWT found in localStorage. User enters email → receives 6-digit code → authenticated. JWT stored and reused across page refreshes.

Consumer Key Only: Pass consumerKey prop / data-consumer-key attribute. No sign-in shown.

BYO JWT: Pass consumerKey prop with your own JWT value. Widget sends it as-is on all requests.

Theming

The widget uses a CSS custom property for the primary color — set it via the primaryColor prop:

// Match your brand color
<AerostackChat primaryColor="#6366f1" ... />  // indigo
<AerostackChat primaryColor="#10b981" ... />  // emerald
<AerostackChat primaryColor="#f59e0b" ... />  // amber

The widget renders inside a Shadow DOM, so it’s isolated from your page’s CSS.

Web component

The script tag registers <aerostack-chat> as a custom element. You can use it directly in any HTML or framework:

<!-- Directly in HTML -->
<aerostack-chat
  project="your-project"
  api="your-api-slug"
  mode="bubble"
  primary-color="#6366f1">
</aerostack-chat>

// In React (TypeScript)
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'aerostack-chat': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
        project?: string
        api?: string
        mode?: string
        'primary-color'?: string
        'welcome-message'?: string
        placeholder?: string
      }
    }
  }
}

Quota display

The widget shows a token balance bar at the bottom of the chat panel when the user has a wallet. It auto-refreshes after each message. No config required — it appears when data is available.

Subscription Plans SDK Reference