Hooks

@appilots/sdk exposes a set of hooks for reading and controlling agent state — chat messages, pending actions, navigation, and suggested prompts. Use them when <AppilotsChat/>'s default UI doesn't fit and you want to build your own chat surface, trigger button, or status indicator on top of the same state.

This page covers the "read/control" hooks. For the registration hooks that expose a component to the agent (useAppilotsField, useAppilotsTarget, useAppilotsToggle, useAppilotsSlider), see Registering elements.

Which hook do I need?

Goal	Hook
Simple custom UI that wants "everything" without composing hooks manually	useAppilots
Fully custom chat surface (messages, sending, escalation)	useAppilotsChat
Fully custom action approval UI (breadcrumbs, confirm/reject)	useAppilotsActions
Reading tracked screen state, or manual navigation tracking	useAppilotsNavigation
Custom suggestion chips in an empty state	useSuggestedPrompts
Registering a field, button, toggle, or slider so the agent can operate it	Registering elements

useAppilots()

A convenience hook that combines chat, navigation, and actions into a single return value. Good for simple custom UIs that want "everything" without wiring the individual hooks together.

import { useAppilots } from '@appilots/sdk';

const { messages, sendMessage, currentScreen, pendingActions } = useAppilots();

Field	Type	Description
config	AppilotsConfig	The resolved provider config.
client	AppilotsClient	The underlying HTTP client — see API Reference.
messages	ChatMessage[]	The conversation transcript.
isLoading	boolean	true while a turn is in flight.
error	string | null	The last error message, if any.
sendMessage	(content: string) => Promise<void>	Sends a user message and drives the agent turn.
clearMessages	() => void	Clears the transcript.
clearError	() => void	Clears error.
currentScreen	string | null	The screen name the agent believes is active.
navigationHistory	string[]	Screen names visited, in order.
setCurrentScreen	(name: string) => void	Manually update the tracked screen.
navigationRef	React.MutableRefObject<any>	Attach to your NavigationContainer for agent-driven navigation.
pendingActions	AgentAction[]	Actions awaiting approval or auto-execution.
executingActions	AgentAction[]	Actions currently running.
completedActions	AgentAction[]	Actions that finished (succeeded or failed).
approveAction	(actionId: string) => Promise<boolean>	Approve and execute a pending action.
rejectAction	(actionId: string) => Promise<void>	Reject a pending action.

useAppilotsChat(options?)

The hook <AppilotsChat/> uses internally. Reach for this when you're building a fully custom chat surface but still want the SDK to drive message sending, streaming, and escalation state.

import { useAppilotsChat } from '@appilots/sdk';

const { messages, isLoading, sendMessage, escalation, requestHuman } = useAppilotsChat({
  streaming: true,
});

Options

Option	Type	Default	Description
errorPrefix	string	undefined	Prefix shown before the error text in a failed-turn system message.
streaming	boolean	true	Stream the agent's reply token-by-token. Falls back to a non-streaming request transparently if the streaming transport is unavailable.
escalationStrings	EscalationStrings	undefined	Localized copy for the system messages shown at each escalation transition (requested, connected, resolved, offer). See Escalation.

Returns

Field	Type	Description
messages	ChatMessage[]	The conversation transcript.
isLoading	boolean	true while a turn is in flight.
loadingStatusKey	'thinking' | 'statusAnalyzing' | 'statusWaitingApp' | 'statusAdjusting'	A coarse status you can map to localized copy for a loading indicator.
error	string | null	The last error message, if any.
pendingActions	AgentAction[]	Actions awaiting approval.
escalation	EscalationState | null	The open escalation, if any — see Escalation.
requestHuman	(reason?: 'user_requested' | 'agent_gave_up') => Promise<void>	Hand the conversation to a human operator.
sendMessage	(content: string) => Promise<void>	Sends a user message and drives the agent turn.
cancelMessage	() => void	Cancels the in-flight turn.
clearMessages	() => void	Clears the transcript.
clearError	() => void	Clears error.

sendMessage drives the whole agent turn: it sends your message plus the current screen context, applies any actions the agent returns, and — when autoExecute is enabled on the underlying actions hook — keeps going automatically until the agent has nothing more to do or hands off to a human.

useAppilotsActions(options?)

The lower-level hook useAppilotsChat uses under the hood for monitoring and controlling actions directly. Reach for this if you want to build your own action-approval UI (custom breadcrumbs, confirm dialogs, etc.) independent of the chat transcript.

import { useAppilotsNavigation, useAppilotsActions } from '@appilots/sdk';

const { navigationRef } = useAppilotsNavigation();
const { pendingActions, approveAction, rejectAction } = useAppilotsActions({
  navigationRef,
  autoExecute: false,
});

Options

Option	Type	Default	Description
navigationRef	React.MutableRefObject<any>	undefined	Navigation ref from useAppilotsNavigation. Required for navigate actions to work.
autoExecute	boolean	false	Execute actions automatically without calling approveAction yourself. Note this differs from <AppilotsChat/>'s own default, which enables auto-execute.

Returns

Field	Type	Description
pendingActions	AgentAction[]	Actions awaiting approval or auto-execution.
executingActions	AgentAction[]	Actions currently running.
completedActions	AgentAction[]	Actions that finished (succeeded or failed).
approveAction	(actionId: string) => Promise<boolean>	Approve and execute a pending action. Resolves true on success.
rejectAction	(actionId: string) => Promise<void>	Reject a pending action.

confirm-type actions always wait for an explicit approveAction/rejectAction call, regardless of autoExecute — they never auto-run.

The hook also enforces confirmation locally as a safety net: if the current screen's registerScreen metadata marks an action requiresConfirmation, destructive, or a high riskLevel, the SDK inserts a local confirmation step for it even if the server didn't already gate it. You don't need to do anything to opt in — just keep your screen metadata accurate and the SDK covers the gap.

useAppilotsNavigation()

Tracks which screen the agent believes is active and exposes the ref that AppilotsNavigationContainer attaches to.

import { useAppilotsNavigation } from '@appilots/sdk';

const { currentScreen, navigationHistory, navigationRef } = useAppilotsNavigation();

Field	Type	Description
currentScreen	string | null	The screen name the agent believes is active.
navigationHistory	string[]	Screen names visited, in order.
setCurrentScreen	(name: string) => void	Manually update the tracked screen.
navigationRef	React.MutableRefObject<any>	Attach to your NavigationContainer (or AppilotsNavigationContainer's internal ref) for automatic tracking.

You normally don't call setCurrentScreen yourself — AppilotsNavigationContainer does it automatically by listening to React Navigation's state changes. Use this hook directly for reading the tracked state, or for manual tracking setups that don't go through AppilotsNavigationContainer.

useSuggestedPrompts(options)

Powers the empty-state suggestion chips in <AppilotsChat/>. Use it directly if you're building a custom chat surface and want the same chips.

import { useSuggestedPrompts } from '@appilots/sdk';

const { prompts, isLoading } = useSuggestedPrompts({ enabled: chatVisible });

return prompts.map((p) => (
  <Chip key={p.text} onPress={() => setInput(p.text)}>{p.text}</Chip>
));

Options

Option	Type	Default	Description
enabled	boolean	—	Only fetches while true, so suggestions don't cost a round trip when the chat is closed.
limit	number	4	Max chips to return.

Returns

Field	Type	Description
prompts	SuggestedPrompt[]	{ text: string, source: 'dev-defined' | 'screen-popular' | 'global-popular' }[].
isLoading	boolean	true while fetching.
refetch	() => void	Re-runs the fetch on demand.

Three sources are merged in priority order, highest first:

1. dev-defined — from registerScreen({ suggestedPrompts }) on the current screen (see Navigation). Always wins when present.
2. screen-popular — historical prompts sent from this screen, server-mined from real usage.
3. global-popular — project-wide fallback for screens with no history yet.

The hook re-fetches automatically when the active screen changes while enabled is true, so chips always match where the user currently is.

Next steps

• Registering elements — the hooks and HOCs that expose fields, targets, toggles, and sliders to the agent.
• Permissions — control what actions the agent is allowed to take.
• Escalation — hand off to a human operator mid-conversation.