omni:session from the intended project. An instant
sandbox key belongs to its own isolated project and does not place agents in
an existing console project.
Which API to use
Create the profile
201 Created with agent_id (agent_...). Save that ID.
Recording is off by default. The profile appears in the console under the
project associated with the key. GET /v1/agents lists active profiles across
the key’s organization; the console filters to the selected project.
Read or update settings
POST, not PATCH. Omitted fields stay unchanged;
null clears fields that permit it. Read the response to confirm the stored
values. New sessions load the update; an active call keeps its configuration.
Add custom vocabulary
Use Agent-ownedvocabulary for distinctive names and phrases. See
Conversation behavior and vocabulary
for limits, lifetime, and controls that are stored but inactive.
Bind a hosted knowledge base
Follow Knowledge bases to create content, wait for indexing, and bind it to this agent. Knowledge writes requirekb:manage;
agent binding requires omni:session. Ordinary sandbox keys omit kb:manage.
The guide also explains organization defaults and how to disable inheritance.
Bind tools
Follow Tools and actions to select a hosted tool or register a signed server webhook, then bind it to the agent. Do not putendpoint or
webhook_url in inline Omni configure.tools; that transport is rejected.
Open a session
Pass the saved ID assession_label:
configured acknowledgement. Browser clients need an ephemeral token
from your server or the hosted widget; never put a secret key in browser code.
Supported inline configure fields override the saved profile for that session.
REST uses persona_system_prompt; realtime uses persona.
Website or phone
Publish the website widget, build a custom browser client, or connect Twilio / FreeSWITCH. Phone actions require a transport that handles the relevant control frames.Next
- Settings and customization: prompts, voices, language, recordings, and overrides.
- Greetings: opening variants and recording disclosure.
- Post-call data capture: fields and completion delivery.
- API reference: exact request and response schemas.