AppilotsProvider

AppilotsProvider is the root context provider for the SDK. It must wrap everything in your app that uses Appilots hooks or components — AppilotsChat, AppilotsNavigationContainer, useAppilotsField, and so on all read from this context.

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

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

Two ways to configure it

1. Zero-config (recommended)

With the Metro plugin configured and a .appilotsrc file in your project root, AppilotsProvider needs no config prop at all — it auto-loads the project ID, API key, and any other settings at bundle time.

<AppilotsProvider>
  <App />
  <AppilotsChat />
</AppilotsProvider>

See CLI configuration for the .appilotsrc file format.

2. Explicit config prop

Pass a config object directly. Useful if you don't want the Metro plugin, or if you need to select the config at runtime (per build flavor, per environment, etc).

<AppilotsProvider
  config={{
    projectId: 'proj_xxxxxxxx',
    apiKey: 'ak_xxxxxxxxxxxx...',
  }}
>
  <App />
  <AppilotsChat />
</AppilotsProvider>

If neither a config prop nor an auto-loaded .appilotsrc resolves a projectId, AppilotsProvider throws a clear error on mount — it won't fail silently.

Props

Prop	Type	Required	Description
config	AppilotsConfig	No	SDK configuration. Omit to auto-load from .appilotsrc via the Metro plugin.
children	React.ReactNode	Yes	Your app tree.
client	AppilotsClient	No	Advanced — supply your own pre-configured AppilotsClient instance instead of letting the provider build one from config.

AppilotsConfig

Field	Type	Description
projectId	string	Required. Your project ID from the Appilots dashboard.
apiBaseUrl	string	API base URL. Defaults to the Appilots cloud API, https://api.appilots.com.
apiKey	string	Your SDK API key (ak_...), sent as a bearer token on every request. The type marks it optional, but real network calls fail without it.
permissions	AgentPermissions	Local permission overrides for this app instance. See Permissions.
debug	boolean	Enables verbose local diagnostic logging for troubleshooting. Off by default.
appVersion	string	Your host app's version (e.g. read from package.json). Forwarded to the API so it can serve the MCP document that matches this build — useful when your fleet has multiple app versions live at once (OTA updates, staged rollouts).
mcpVersion	string	The version of the MCP document bundled with this build. Used for stale-document detection.
user	AppilotsUser	Identifies the current app user ({ id, name?, identifiers? }). See Sessions & users — identifiers are never sent to the model.
fetchPersonalization	boolean	Defaults to true: on mount, the provider fetches the project's dashboard personalization (theme, branding, FAB color, locale…) once, and <AppilotsChat/> uses it as a fallback for props you didn't set. Set false to opt out — this is the SDK's only automatic network call before the user interacts; without it (or on fetch failure) the chat just uses props and bundled defaults. See Customization → Overview.

useAppilotsContext()

const { config, client, subscribe, emit, remotePersonalization } = useAppilotsContext();

This is the low-level hook that every other Appilots hook builds on — it exposes the resolved config, the AppilotsClient instance, the internal event bus (subscribe/emit), and remotePersonalization (the dashboard-configured personalization fetched on mount — null until the fetch resolves, and forever if it fails or fetchPersonalization: false opted out). Most apps never call it directly: useAppilots() and useAppilotsChat() already wrap it with a friendlier API. Reach for useAppilotsContext() only if you're building custom chat UI on top of the SDK — e.g. reading remotePersonalization to apply the project's branding to your own surfaces.

Wiring up navigation

If your app uses React Navigation, wrap your NavigationContainer with AppilotsNavigationContainer inside AppilotsProvider so the agent knows what screen the user is on:

<AppilotsProvider>
  <AppilotsNavigationContainer>
    <NavigationContainer>{/* ... */}</NavigationContainer>
  </AppilotsNavigationContainer>
  <AppilotsChat />
</AppilotsProvider>

See Navigation for the full setup.

Next steps

• AppilotsChat — the chat UI itself.
• Navigation — describe your screens to the agent.
• Permissions — control what the agent is allowed to do.