AppilotsChat

<AppilotsChat/> is the chat UI itself — the floating button, the message thread, the input, and the confirmation cards the agent uses when it needs your approval. Drop it anywhere inside AppilotsProvider.

import { AppilotsProvider, AppilotsChat } from '@appilots/sdk';

function App() {
  return (
    <AppilotsProvider>
      {/* your app */}
      <AppilotsChat />
    </AppilotsProvider>
  );
}

Props

Every branding/theming prop below resolves with the precedence explicit prop → dashboard personalization → SDK default. The dashboard's Personalização values are fetched once on AppilotsProvider mount and act as fallbacks for theme, themeMode, headerTitle/assistantName (via chatTitle/assistantName), assistantAvatar (URL only), emptyStateIcon, welcomeMessage, poweredByVisible, triggerButtonColor, triggerButtonImage (URL only), and locale — a prop you set in code always wins. See Customization → Overview for details and the fetchPersonalization: false opt-out.

Prop	Type	Default	Description
visible	boolean	—	Controlled visibility. When set, the floating action button (FAB) is hidden and you own showing/hiding the chat yourself.
onClose	() => void	—	Called when the user dismisses the chat. Required alongside visible for controlled usage.
placeholder	string	i18n bundle	Input placeholder text.
headerTitle	string	assistantName prop, then dashboard chatTitle/assistantName, then i18n bundle	Chat header title.
showActionPreviews	boolean	—	Deprecated. No longer has any effect — action traces are debug-only and confirmation prompts always remain visible.
autoExecute	boolean	true	Auto-execute non-confirm actions without asking for approval. Actions marked confirm always require explicit user approval regardless of this setting.
theme	PartialThemeTokens | LegacyThemeShape	—	Theme token overrides, merged onto the resolved light/dark theme. See Theming. The legacy shape (primaryColor, backgroundColor, textColor, inputBackgroundColor, borderRadius, fontFamily) is still accepted and auto-translated.
themeMode	'auto' | 'light' | 'dark'	'auto'	'auto' follows the device color scheme.
assistantName	string	—	Display name shown in the header.
assistantAvatar	string | number | React.ReactNode	—	A URL, a require()'d local image, or a React node rendered next to the header title.
emptyStateIcon	string | number	Default ChatIcon glyph	An emoji/string rendered in a tinted badge, or an image (a URL starting with http(s)://, or a require()'d asset) rendered without the tint. Detected automatically — no separate type prop needed.
welcomeMessage	string	Default subtitle	Subtitle text shown under the empty-state title.
poweredByVisible	boolean	true	Show or hide the "Powered by Appilots" footer line.
mode	'bubble' | 'fullscreen' | 'sidebar' | 'inline'	'bubble'	Layout mode — see Layout modes.
position	'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'	'bottom-right'	FAB position. Only used when mode='bubble'.
triggerButton	React.ReactNode | 'default' | 'none'	'default'	Fully replace the FAB with your own node, or pass 'none' to hide it entirely (useful when you drive visible from your own trigger, e.g. a header icon).
triggerIcon	React.ReactNode	—	Replace only the icon inside the default FAB, keeping its shape and background. Takes priority over triggerButtonImage. Ignored once triggerButton is set to a node.
triggerButtonColor	string	theme.colors.primary	Background color of the default FAB.
triggerButtonImage	string | number	—	An image (URL or require()'d asset) rendered inside the default FAB instead of the built-in chat icon — e.g. a company logo. Ignored when triggerIcon is set.
locale	AppilotsLocale ('pt-BR' | 'en' | 'es')	Dashboard default locale, then device detection	Force a locale. See Customization: i18n.

Layout modes

Mode	Behavior
bubble (default)	FAB + bottom-sheet modal.
fullscreen	No FAB — a full-screen modal. Drive it with your own trigger via visible/onClose.
sidebar	Half-width modal pinned to the right on tablet/wide screens. Falls back to a full-width sheet on narrow phones.
inline	Renders in place — no modal, no FAB. Always visible.

Presentation during actions

Use experience={{ presence: 'pill' }} to let users watch the assistant operate the app. An open chat stays visible while the model thinks or streams a text response. It collapses when an app action starts executing, stays collapsed between steps, and returns with the result after the host app's modal closes. Confirmation questions remain visible.

With presence: 'hidden', execution also collapses the chat, but the result waits in the pill until the user opens it. A text-only response keeps an already open conversation visible in both modes. presence: 'sheet' preserves the expanded presentation.

Automatic progress labels use simple copy in the conversation language, such as “Tapping a button…” or “Filling in the form…”. They do not include control IDs, route names or field payloads. Technical action records remain available through getAppilotsDebugTraces(); customer progress copy does not depend on a debug setting.

Controlled vs. uncontrolled

By default, AppilotsChat manages its own open/closed state internally — the FAB opens it, the user closes it. Pass visible and onClose to control it externally instead. This works in every mode except inline, which is always visible and ignores visible/onClose.

Human escalation

The chat has a built-in "talk to a human" affordance — a headset icon button in the header, plus a chip that's automatically offered when the agent gives up on a request. See Escalation for the full picture.

Driving the chat from an e2e suite

Every control the chat renders carries a stable testID — assistant-launcher, assistant-input, assistant-send, assistant-close, and the rest. Match on those, never on the button copy: labels come from the i18n bundle and change with the locale. See Test IDs for the full list and the stability policy.

Examples

Minimal

import { AppilotsProvider, AppilotsChat } from '@appilots/sdk';

function App() {
  return (
    <AppilotsProvider>
      {/* your app */}
      <AppilotsChat />
    </AppilotsProvider>
  );
}

Customized bubble

import { AppilotsProvider, AppilotsChat } from '@appilots/sdk';

function App() {
  return (
    <AppilotsProvider>
      {/* your app */}
      <AppilotsChat
        assistantName="Ava"
        assistantAvatar={require('./assets/ava-avatar.png')}
        welcomeMessage="Ask me to find something or fill out a form for you."
        position="bottom-left"
        triggerButtonColor="#5B4CF0"
        theme={{
          colors: {
            primary: '#5B4CF0',
          },
        }}
      />
    </AppilotsProvider>
  );
}

Controlled fullscreen chat

import { useState } from 'react';
import { Button, View } from 'react-native';
import { AppilotsProvider, AppilotsChat } from '@appilots/sdk';

function App() {
  const [chatVisible, setChatVisible] = useState(false);

  return (
    <AppilotsProvider>
      <View>
        {/* your app */}
        <Button title="Ask Ava" onPress={() => setChatVisible(true)} />
      </View>
      <AppilotsChat
        mode="fullscreen"
        triggerButton="none"
        visible={chatVisible}
        onClose={() => setChatVisible(false)}
      />
    </AppilotsProvider>
  );
}

Next steps

• Theming — the full token tree behind the theme prop.
• Customization overview — branding, persona, layout, and i18n in one place.
• Escalation — how human handoff works end to end.
• Test IDs — the handles your Detox/Maestro suite drives the chat with.