Widget integration pattern

AomiWidget adds Aomi chat, threads, wallet connection, and transaction approval to your React application. Your application chooses the App and the user-facing wallet provider. Aomi resolves the App’s tools and execution settings from the Application ID. The widget runs on your application’s origin. It does not reuse cookies from chat.aomi.dev. Instead, it creates a widget session for the signed-in user and binds that session to the exact origin that created it. There is no origin registration or allowlist: any HTTPS origin can mint a session, and the session is only valid when presented from that same origin.

Understand the boundary

Your host application and Aomi have distinct responsibilities:

Owner	What it controls
Your application	The Application ID, browser wallet or embedded-wallet provider, public provider identifier, initial thread, and widget presentation
`AomiWidget`	Sign-in, wallet connection, threads, chat, transaction review, and signing requests
Aomi	Origin binding of the widget session, the user’s Aomi account, and the App configuration selected by the Application ID
User wallet	Wallet ownership proof and any signature required by the active signing policy

Provider choice belongs to your application. Switching from browser wallets to Para or Privy changes how users sign in and access wallets. It does not change which Aomi App handles the conversation.

Before you start

You need:

An activated Aomi App and its numeric Application ID.
React 18 or 19 running in the browser.
A browser-wallet, Para, or Privy integration choice.

Hosted integrations must use HTTPS. HTTP is accepted only on loopback hosts (localhost, 127.0.0.1, [::1]) for local development. If you use Para or Privy, also allow your host origin in that provider’s project settings when the provider requires it.

npm install @aomi-labs/widget-lib

Import the default stylesheet once in your client application:

import "@aomi-labs/widget-lib/styles.css";

2. Add public configuration

Keep the Application ID and provider’s public browser identifier in your host application. Add only the provider you use.

Next.js
Vite

NEXT_PUBLIC_AOMI_API_URL=https://chat.aomi.dev
NEXT_PUBLIC_AOMI_APPLICATION_ID=123

# Add one only when you use that provider
NEXT_PUBLIC_PARA_API_KEY=your_public_para_api_key
NEXT_PUBLIC_PRIVY_APP_ID=your_public_privy_app_id

VITE_AOMI_API_URL=https://chat.aomi.dev
VITE_AOMI_APPLICATION_ID=123

# Add one only when you use that provider
VITE_PARA_API_KEY=your_public_para_api_key
VITE_PRIVY_APP_ID=your_public_privy_app_id

These values are safe to expose to the browser. Do not add an App key, provider secret, paymaster credential, gas-policy credential, treasury configuration, or private key to frontend code.

3. Mount AomiWidget

Choose one authentication mode. Import the matching provider entry point for Para or Privy so the widget can register that provider.

Browser wallet
Para
Privy

Use this mode when users connect an existing wallet.

"use client";

import { AomiWidget } from "@aomi-labs/widget-lib";
import "@aomi-labs/widget-lib/styles.css";

export default function AssistantPage() {
  return (
    <AomiWidget
      applicationId={process.env.NEXT_PUBLIC_AOMI_APPLICATION_ID!}
      apiUrl={process.env.NEXT_PUBLIC_AOMI_API_URL!}
      auth={{ kind: "browser_wallet" }}
      height="calc(100dvh - 32px)"
    />
  );
}

Use this mode when Para owns the sign-in and embedded-wallet experience.

"use client";

import { AomiWidget } from "@aomi-labs/widget-lib";
import "@aomi-labs/widget-lib/providers/para";
import "@aomi-labs/widget-lib/styles.css";

export default function AssistantPage() {
  return (
    <AomiWidget
      applicationId={process.env.NEXT_PUBLIC_AOMI_APPLICATION_ID!}
      apiUrl={process.env.NEXT_PUBLIC_AOMI_API_URL!}
      auth={{
        kind: "embedded_wallet",
        provider: "para",
        environment: "PROD",
        apiKey: process.env.NEXT_PUBLIC_PARA_API_KEY!,
      }}
      height="calc(100dvh - 32px)"
    />
  );
}

Use this mode when Privy owns the sign-in and embedded-wallet experience.

"use client";

import { AomiWidget } from "@aomi-labs/widget-lib";
import "@aomi-labs/widget-lib/providers/privy";
import "@aomi-labs/widget-lib/styles.css";

export default function AssistantPage() {
  return (
    <AomiWidget
      applicationId={process.env.NEXT_PUBLIC_AOMI_APPLICATION_ID!}
      apiUrl={process.env.NEXT_PUBLIC_AOMI_API_URL!}
      auth={{
        kind: "embedded_wallet",
        provider: "privy",
        appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID!,
      }}
      height="calc(100dvh - 32px)"
    />
  );
}

For Vite, replace each process.env.NEXT_PUBLIC_* read with the matching import.meta.env.VITE_* value.

4. Pass optional host state

You can keep thread selection and wallet presentation in your application:

<AomiWidget
  applicationId={applicationId}
  apiUrl={apiUrl}
  auth={auth}
  initialThreadId={threadId}
  clientOptions={clientOptions}
  wallets={{
    evm: { preset: "popular" },
    solana: false,
  }}
  persistThread
/>

Prop	Use it for
`applicationId`	Select the activated Aomi App. Aomi resolves its tools and execution settings.
`apiUrl`	Select the Aomi service used for widget sessions, chat, and account requests.
`auth`	Select browser-wallet, Para, or Privy authentication.
`initialThreadId`	Open a thread chosen by your host application.
`clientOptions`	Pass supported client behavior overrides without replacing Aomi authentication.
`wallets`	Limit the wallet families, networks, or wallet choices shown to users.

The Application ID selects the App. It is not a user credential and does not grant wallet signing. The active user and wallet must still complete the configured authentication and approval flow.

5. Verify the integration

Open the widget from the origin your application is served from.
Sign in or connect a browser wallet. Browser-wallet sign-in uses a SIWE or SIWS signature from an externally owned account; smart-contract wallets (Safe, Coinbase Smart Wallet, Base Account) cannot sign in through the widget.
Confirm the thread list and composer load without an App-key prompt.
Send a message and confirm your selected App responds.
If the App creates transactions, confirm the widget shows the request before the wallet asks for a signature.
Repeat the check from the production HTTPS origin before launch.

If the origin is rejected, check that it is HTTPS (or a loopback host over HTTP) and that the session is presented from the same scheme, host, and port that created it. If an embedded provider does not open, check its public identifier, environment, provider import, and allowed origins.

Installation details

Review framework setup and environment configuration.

Customize the widget

Configure layout, themes, wallet controls, or a headless interface.

Troubleshooting

Resolve origin, provider, wallet, and transaction issues.

Build with SDK

Widget integration pattern

Understand the boundary

Before you start

1. Install the widget

2. Add public configuration

3. Mount AomiWidget

4. Pass optional host state

5. Verify the integration

Installation details

Customize the widget

Troubleshooting

​Understand the boundary

​Before you start

​1. Install the widget

​2. Add public configuration

​3. Mount AomiWidget

​4. Pass optional host state

​5. Verify the integration

Installation details

Customize the widget

Troubleshooting

Understand the boundary

Before you start

1. Install the widget

2. Add public configuration

3. Mount AomiWidget

4. Pass optional host state

5. Verify the integration