Skip to main content

BotChatProps interface

For teams that want MimicBot's chat UI inside an existing React app without the launcher's Shadow DOM wrapper, mount <BotChat /> from @mimicbot/chat-ui directly. This page documents the component's props exactly as declared in source.

Most installs don't need this. If you are starting from zero, use the script tag install — the launcher handles Shadow DOM isolation, visitor id persistence, config fetching, and action execution automatically. Reach for the React component only when your host app needs direct control over the conversation or when Shadow DOM isolation is incompatible with your design system.

Installation​

npm install @mimicbot/chat-ui

Usage​

import { BotChat } from '@mimicbot/chat-ui';
import { useEffect, useState } from 'react';
import type { PublicBotConfig } from '@mimicbot/chat-ui';

function App() {
  const [config, setConfig] = useState<PublicBotConfig | null>(null);
  const [conversationId, setConversationId] = useState<string | null>(null);

  useEffect(() => {
    fetch('https://api.mimicbot.app/v1/public/bots/bot_a1b2c3d4e5/config')
      .then((r) => r.json())
      .then(setConfig);
  }, []);

  if (!config) return null;

  return (
    <BotChat
      apiBase="https://api.mimicbot.app"
      botPublicId="bot_a1b2c3d4e5"
      visitorId={getOrCreateVisitorId()}
      conversationId={conversationId}
      config={config}
      onConversationIdChange={setConversationId}
      onProposal={async (proposal) => {
        // Execute the proposed action however your app wants to.
        // Return the terminal result so the bot can acknowledge it.
        return { result: 'success' };
      }}
    />
  );
}

Props​

PropTypeRequiredDescription
apiBasestringyesThe API origin. For MimicBot Cloud this is https://api.mimicbot.app. Self-hosted installs point at their own API origin.
botPublicIdstringyesThe target bot's publicId, shape bot_<10 chars>.
visitorIdstringyesStable anonymous per-browser identifier. Generate once and persist in localStorage — see below.
conversationIdstring | nullyesnull to start a new conversation, or a prior conversation's id to continue. Pass the value returned by onConversationIdChange on subsequent renders.
configPublicBotConfigyesThe config object returned by GET /v1/public/bots/{publicId}/config. Drives assistantName, primaryColor, welcomeMessage, suggestedQuestions, and privacyPolicyUrl.
onConversationIdChange(id: string) => voidyesCalled when the server assigns a new conversationId (on data-done). Persist it and pass it back on the next render so follow-up turns continue the same conversation.
onProposal(p: ActionProposalPayload) => Promise<{ result: 'success' | 'failure' | 'cancelled'; error?: string }>yesCalled when the bot proposes an action. Your app is responsible for running it (form fill, network request, whatever) and returning the terminal outcome. The resolved value is what the action card displays and what you would post to /v1/public/actions/{executionId}/result if you want server-side execution history.

All seven props are required. There is no default for onProposal — if you don't handle proposals, the chat UI will surface an action card the user can click but nothing will happen when they do.

visitorId management​

The launcher persists a stable visitorId in localStorage automatically. When you embed <BotChat /> directly, you own this — generate one on first load and reuse it across sessions so the backend's rate limiter can track the visitor correctly.

function getOrCreateVisitorId(): string {
  const key = 'mimicbot.visitorId';
  let id = localStorage.getItem(key);
  if (!id) {
    id = `visitor_${crypto.randomUUID()}`;
    localStorage.setItem(key, id);
  }
  return id;
}

onProposal contract​

When the agent emits a data-action-proposal chunk, the chat UI renders an action card and passes the ActionProposalPayload to onProposal. Your implementation decides what to do:

  • Form / newsletter actions — POST the form, observe the response, return { result: 'success' } or { result: 'failure', error: 'reason' }.
  • Deep-link actions (mailto, calendar, phone, whatsapp) — window.open the target and return { result: 'success' } optimistically.
  • Cancel — return { result: 'cancelled' } so the card displays the cancellation state and the bot can move on.

If your app also wants to contribute to the server-side action_executions history, POST the same outcome to /v1/public/actions/{executionId}/result before resolving. The launcher's built-in action executor does this automatically; if you are rolling your own, it is opt-in.