View as Markdown Open in ChatGPT Open in Claude

Avatar actions

Let the avatar do things in your app — book a demo, look up an order — with every change read back and confirmed by the user first.

An action is something your app can do that the avatar may offer during a call. You declare it with a name, a description and the details it needs; the avatar collects those details in conversation, reads them back, and your handler runs only once the user says yes. Only the name, description and params leave the device — the handler stays in your app.

The API, the rules and the limits are the same as on the web. This page covers the React Native specifics; the React actions page is the full reference.

Before you start

Requirement	Where it is set
Call mode	mode: "call" in your config. Registering in any other mode reports a non-fatal INVALID_MODE error.
The Site actions grant	Site actions in the avatar's Tool calling panel on the Platform. Off by default. While it is off the SDK declares nothing and logs one warning per session.

triggerAction and availableActions on useAvatar() are rig gestures, not these actions.

Registering an action

useAvatarAction registers on mount and unregisters on unmount, so an action exists only while the screen that can perform it is mounted.

tsx

import { useAvatarAction } from "@avatarfactory/react-native";

function DemoBookingAction() {
  useAvatarAction({
    name: "book_demo",
    description: "Book a 30-minute demo call. Ask for the time first, then the email.",
    params: {
      slot: { type: "datetime", description: "Demo start time" },
      email: { type: "email", description: "Where to send the invite" },
    },
    handler: async ({ slot, email }, { signal }) => {
      const response = await fetch("https://example.com/api/demo", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ slot, email }),
        signal,
      });
      return response.ok
        ? { ok: true, result: `Booked. The invite is on its way to ${email}.` }
        : { ok: false, error: "that slot was just taken" };
    },
  });
  return null;
}

useAvatarAction takes the full definition, including kind, ui and check. To register outside a component's lifetime, use registerAction from useAvatar(); it returns the function that unregisters it.

tsx

const { registerAction } = useAvatar();

useEffect(() => {
  if (!registerAction) return;
  return registerAction({
    name: "track_order",
    description: "Look up where an order is.",
    kind: "lookup",
    params: { orderNumber: { type: "string" } },
    handler: async ({ orderNumber }) => {
      const status = await fetchOrderStatus(String(orderNumber));
      return { ok: true, result: `Order ${orderNumber} is ${status}.` };
    },
  });
}, [registerAction]);

The definition fields, param types and handler results are documented in full under ActionDefinition.

How an action runs

Stage	What happens
`collecting`	The avatar asks for each detail it still needs. The user can also type a value into your UI.
`review`	The avatar reads back the exact details and waits for a yes.
`running`	The user agreed — by voice on a later turn, or by tapping Confirm. Your handler runs with those exact details.
`done`	The handler returned. The avatar tells the user how it went.
`cancelled`	The user backed out before the run.
`expired`	No yes within 3 user turns or 2 minutes, or a different action replaced this one.

There is no option to skip the read-back. A kind: "lookup" runs at once without one, so a lookup must change nothing.

Your own UI

useAvatarActionFlow reports each stage so you can show an input, a confirm card, or the outcome. Voice alone completes every action, so this is optional.

tsx

import { View, Text, Pressable } from "react-native";
import { useAvatarActionFlow } from "@avatarfactory/react-native";

function DemoBookingCard() {
  const { flow, confirm, cancel } = useAvatarActionFlow("book_demo");
  if (!flow) return null;

  if (flow.stage === "review") {
    return (
      <View>
        <Text>{new Date(String(flow.args.slot)).toLocaleString()}</Text>
        <Text>{String(flow.args.email)}</Text>
        <Pressable onPress={confirm}><Text>Confirm</Text></Pressable>
        <Pressable onPress={cancel}><Text>Cancel</Text></Pressable>
      </View>
    );
  }

  if (flow.stage === "done" && flow.outcome) {
    return <Text>{flow.outcome.message}</Text>;
  }

  return null;
}

Prop	Type	Default	Description
`flow`Optional	`ActionFlow \| null`	No default	The current flow as the server last reported it, or null. Read flow.stage and flow.awaiting to pick a card.
`input`Optional	`(args: Record<string, unknown>) => boolean`	No default	Send what the user typed or picked. Starts the action if none is in progress.
`confirm`Optional	`() => boolean`	No default	The user tapped Confirm during the read-back.
`cancel`Optional	`() => boolean`	No default	The user backed out, at any stage before the run.

See Your own UI for every ActionFlow field and awaiting kind.

Limits

Limit	Value
Actions registered at once	`8`
Params per action	`8`
Action name	`^[a-z][a-z0-9_]{0,63}$`
description	`300 characters`
result / error	`1000 characters`
Handler time	`12 s, then the signal aborts`
check time	`2.5 s, then the value passes unverified`

Action names cannot contain dots. Problems are reported through the error event as non-fatal INVALID_MODE, INVALID_INPUT or NOT_CONNECTED errors; none of them ends the session.

App Events

Events