AI agent

A settings form for an account's Managed VoiceAI agent, the AI receptionist DialStack runs on its calls. The user edits how the agent introduces itself, the business name it greets callers with, its instructions and its FAQ, then saves.

The component edits an agent that already exists. It doesn't create one: create the agent from your backend with the AI Agents API (see AI Scheduling), then pass its ID to the component.

When Managed VoiceAI is hidden

A platform can hide Managed VoiceAI from its accounts, for example because it offers its own voice AI. An account where it is hidden can't create an agent, so this component has nothing to show there. To run your own voice AI on DialStack calls, use a voice app instead.

Usage

React
Web Component

TypeScript
import { AIAgent } from '@dialstack/sdk-react/ai-agent';

function ReceptionistSettings({ agentId }: { agentId: string }) {
  return <AIAgent agentId={agentId} />;
}

HTML
<dialstack-ai-agent agent-id="YOUR_AGENT_ID"></dialstack-ai-agent>

<script>
  // `dialstack` is your initialized instance (see Setup)
  document.querySelector('dialstack-ai-agent').setInstance(dialstack);
</script>

Session permissions

Enable the ai_agent component when you mint the account session. It lets the session read and update an AI agent by its ID, and nothing else: it can't list, create or delete agents. Look up the agent's ID on your backend with your secret key (list the account's agents with GET /v1/ai-agents) and pass it to the page. See Sessions.

The form shows a loading message until it has both an instance and an agent ID.

Fields

Field	Hide with	Limits	What it does
Name	`name`	Required, up to 255 characters	Label shown in lists and call logs. Callers never hear it
Persona name	`persona_name`	Up to 255 characters	How the agent introduces itself on calls
Greeting name	`greeting_name`	Up to 255 characters	The business name in the greeting ("Thanks for calling …")
Instructions	`instructions`	Up to 10,000 characters	Plain-language guidance: tone, what to do, what to escalate
FAQ	`faq`	Up to 50 entries, 2,000 characters per field	Question and answer pairs the agent uses for recurring questions

Each FAQ entry needs both a question and an answer. Empty entries are dropped when the form saves. Save stays disabled while a field breaks a limit, with the reason shown beside the button. Changes apply from the agent's next call.

Options

React prop	Web Component method	Type	Default	Description
`agentId`	`setAgentId(id)` or `agent-id` attribute	`string`	—	The agent to edit
`hideFields`	`setHideFields(fields)` or `hide-fields` attribute	`AIAgentField[]`	`[]`	Fields not to show (see below)
`locale`	`setLocale(locale)`	`Locale`	—	UI strings. See Internationalization
`onSaved`	`dialstack:ai-agent:saved` event	`(agent: { id: string }) => void`	—	Called after a successful save
`onError`	`dialstack:ai-agent:error` event	`(error: Error) => void`	—	Called when loading or saving the agent fails
`beforeActions`	`before-actions` slot	`React.ReactNode`	—	Your own content inside the form, just above Save
`className`	—	`string`	—	Class on the React wrapper's container element
`style`	—	`React.CSSProperties`	—	Inline style on the React wrapper's container

Unlike the list components, the AI agent form doesn't take the other common options.

Hiding fields

A hidden field is left out of the form, and saving leaves its stored value as it was. Use it when your product sets a value itself. For example, hide name when each account only ever has one agent and the label means nothing to your users.

The values for the fields this form shows are 'name', 'persona_name', 'greeting_name', 'instructions' and 'faq'. The attribute takes the same values, separated by commas.

React
Web Component

TypeScript
<AIAgent agentId={agentId} hideFields={['name']} />

HTML
<dialstack-ai-agent agent-id="YOUR_AGENT_ID" hide-fields="name"></dialstack-ai-agent>

Events

The React callbacks wrap DOM events that the element dispatches. They bubble, so you can listen on the element or on an ancestor.

Event	`detail`	When
`dialstack:ai-agent:saved`	`{ agentId }`	The agent was saved
`dialstack:ai-agent:error`	`{ error }`	Loading or saving failed. `error` is an `Error`

Validation problems are shown in the form and don't fire an error.

React
Web Component

TypeScript
<AIAgent
  agentId={agentId}
  onSaved={(agent) => toast.success('Receptionist updated')}
  onError={(error) => console.error('AI agent error:', error.message)}
/>

JavaScript
const agent = document.querySelector('dialstack-ai-agent');

agent.addEventListener('dialstack:ai-agent:saved', (event) => {
  showToast('Receptionist updated');
});
agent.addEventListener('dialstack:ai-agent:error', (event) => {
  console.error('AI agent error:', event.detail.error.message);
});

Content above the Save button

The form owns its Save button. To put something the user should read before saving inside the form, such as a note about what changes take effect, pass it as beforeActions in React, or as a child with slot="before-actions" on the element. It keeps your page's styles.

React
Web Component

TypeScript
<AIAgent
  agentId={agentId}
  beforeActions={<p className="text-sm">Changes apply from the next call.</p>}
/>

HTML
<dialstack-ai-agent agent-id="YOUR_AGENT_ID">
  <p slot="before-actions" class="text-sm">Changes apply from the next call.</p>
</dialstack-ai-agent>

Styling

The AI agent form has no classes option. It follows the colors, fonts and spacing you set on the instance. See Theming.

Next steps

AI Scheduling — create the agent and connect it to your booking system
Voice apps — run your own voice AI on DialStack calls
Theming — customize appearance

Usage​

Fields​

Options​

Hiding fields​

Events​

Content above the Save button​

Styling​

Next steps​