Action Types Reference

Actions represent things users can do in your application. Each action has a type that determines how it behaves.

Action Types

Type	Description	Use Case
`navigate`	Navigate to a page in your app	Settings, dashboard, detail pages
`trigger_action`	Run custom logic	Open modals, start wizards, toggle features
`inline_ui`	Show interactive UI in chat	Forms, confirmations, previews
`external_link`	Open URL in new tab	Documentation, external resources
`copy_text`	Copy text to clipboard	API keys, code snippets

navigate

Navigate to a page in your application.

examples/reference/action-types/navigate.tsx

{
  open_settings: {
    description: 'Navigate to the settings page',
    type: 'navigate',
    path: '/settings',
    autoRun: true,      // Navigate without clicking
    autoComplete: true, // Mark done immediately
  },
}

Property	Type	Description
`path`	`string`	The path to navigate to
`autoRun`	`boolean`	Execute immediately when suggested
`autoComplete`	`boolean`	Mark step as complete immediately

Default handler: window.location.href = path

trigger_action

Run custom logic in your application.

examples/reference/action-types/trigger-action.tsx

{
  invite_member: {
    description: 'Open the invite team member modal',
    type: 'trigger_action',
    examples: ['invite someone', 'add a user'],
    dataSchema: {
      type: 'object',
      properties: {
        email: { type: 'string', description: 'Email to invite' },
        role: { type: 'string', enum: ['admin', 'member'] },
      },
    },
    handler: (data) => openInviteModal(data),
  },
}

Property	Type	Description
`dataSchema`	`JSONSchema`	Schema for data extraction from user message
`handler`	`(data) => TaskResult`	Function to execute

inline_ui

Show interactive UI directly in the chat.

examples/reference/action-types/inline-ui.tsx

{
  invite_members: {
    description: 'Invite team members with confirmation',
    type: 'inline_ui',
    card_type: 'invite_members', // Maps to registered card component
    dataSchema: {
      type: 'object',
      properties: {
        emails: { type: 'array', items: { type: 'string' } },
        role: { type: 'string' },
      },
    },
  },
}

Property	Type	Description
`card_type`	`string`	The registered card component to render
`dataSchema`	`JSONSchema`	Schema for data extraction

Requires a registered card component. See Custom Cards.

external_link

Open a URL in a new browser tab.

examples/reference/action-types/external-link.tsx

{
  view_docs: {
    description: 'Open the API documentation',
    type: 'external_link',
    externalUrl: 'https://docs.example.com/api',
    autoRun: true,
  },
}

Property	Type	Description
`externalUrl`	`string`	The URL to open

Default handler: window.open(url, '_blank')

copy_text

Copy text to the user's clipboard.

examples/reference/action-types/copy-text.tsx

{
  copy_api_key: {
    description: 'Copy the API key to clipboard',
    type: 'copy_text',
    dataSchema: {
      type: 'object',
      properties: {
        text: { type: 'string', description: 'Text to copy' },
      },
    },
  },
}

Default handler: navigator.clipboard.writeText(text)

Common Properties

These properties are available on all action types:

Property	Type	Default	Description
`description`	`string`	Required	AI uses this to match user intent
`type`	`ActionType`	Required	One of the types above
`examples`	`string[]`	`[]`	Example phrases that trigger this action
`autoRun`	`boolean`	`false`	Execute without user clicking
`autoComplete`	`boolean`	`false`	Mark done immediately
`requiredContext`	`object`	`undefined`	Context required for action to be available
`defaultData`	`object`	`undefined`	Default values passed to handler

Data Schema

Use JSON Schema to define what data the AI should extract from user messages:

examples/reference/action-types/data-schema.tsx

dataSchema: {
  type: 'object',
  properties: {
    url: {
      type: 'string',
      description: 'URL of the source to add',
    },
    name: {
      type: 'string',
      description: 'Display name for the source',
    },
  },
  required: ['url'],
}

When a user says "Add my docs site at docs.example.com", the AI extracts:

examples/reference/action-types/data-extraction.json

{ "url": "docs.example.com" }

Required Context

Filter actions based on user attributes:

examples/reference/action-types/required-context.tsx

{
  delete_user: {
    description: 'Delete a user from the organization',
    type: 'trigger_action',
    requiredContext: {
      userRole: 'admin',
    },
    handler: ({ userId }) => deleteUser(userId),
  },
}

This action only appears when pillar.setContext({ userRole: 'admin' }) is set.

Search documentation