Create an agent profile
Create an OPTIONAL agent profile (persona, greeting message, voice, language, recording disclosure, conversation knobs) so you can reference it by id instead of sending a full configure frame each call. Drive it with wss://api.pyai.com/v1/omni?session_label=agent_… (the profile id doubles as the opaque session label; agent_id is the deprecated alias); per-call headers (X-PyAI-Voice, X-PyAI-Persona) and the configure frame override profile config. The engine speaks greeting at turn 0 and consent_line before recording when enabled. Requires the omni:session scope.
Authorizations
Use Authorization: Bearer pyai_live_... (or pyai_test_...).
Body
Writable agent fields. On update, present fields are set, null clears, absent fields are untouched.
Display name. Required on create.
200The agent's entire character, role, policies, and business context.
32000Greeting message, opening line spoken at turn 0 when a call connects (before the caller speaks). Stored on the agent profile; played automatically when connecting with session_label={agent_id}. May also be sent inline in the Omni configure frame.
1000Approved opening-line variants. PyAI selects one for each newly resolved call profile; null or empty falls back to greeting. Recording consent is fixed and never rotated.
151000A stock voice id from GET /v1/voices or a cloned voice id.
Per-agent model selection. Omit for the platform default.
How eagerly the agent yields when talked over: low, normal, high, or an exact dBFS value.
Conversational-acknowledgment mode. Default auto.
How patient the agent is before checking in on a silent caller ("Sorry, are you still there?"). auto (default) checks in after a few seconds of silence; patient waits far longer, for callers who routinely think, read, or look something up mid-call; off disables the check-in entirely, so the agent stays silent until the caller speaks. Independent of ack_mode. May also be sent inline in the Omni configure frame, which wins for that session.
auto, patient, off, null Which side of the call the persona is on. agent (default) means the persona is the business being called, so PyAI adds its conversation layer for handling a caller (capability honesty, handoffs, turn discipline). caller means the persona is the individual on the call instead, as in QA and simulation callers, mystery shopping, or training partners; PyAI drops that operator-voice layer so it cannot contradict an inverted persona. May also be sent inline in the Omni configure frame, which wins for that session.
agent, caller, null Enable stereo call recordings. Default false.
Recording disclosure spoken before recording starts when recordings_enabled is true. Required for compliance when recordings are on. Playback order: consent_line, then greeting, then conversation.
500The language this agent's Omni sessions run in, end to end (recognition, reasoning, and voice). null or absent means the default, en, identical to pre-multilingual behavior. Hindi is served on the standard voice tier by default; the natural (telephony premium) tier bills an add-on per minute, see Pricing. Availability per language is staged, see the Language support reference.
en, fr, es, de, hi, null Up to 16 key/value annotations (keys ≤64 chars, values ≤512 chars).
Vocabulary-boost terms for speech recognition (stored now; engine biasing rolls out per the keyterms roadmap).
100Goal checklist for post-call outcome scoring (stored now; scoring ships with summaries).
20JSON Schema of fields to capture from each completed call's transcript. When set with extraction_webhook_url, PyAI runs a post-call extraction pass and POSTs the structured JSON to your webhook (signed with X-PyAI-Signature). Null disables extraction.
HTTPS URL that receives the signed post-call extraction result (event omni.call.extracted). Requires extraction_schema. The call's agent is resolved from the connect-URL session_label when it equals this agent's id.
Tool bindings for this agent profile (references tools from GET /v1/tools). Inline Omni configure.tools[] definitions are separate, see the Omni protocol docs.
Response
Created agent
"agent"
"agent_7f3a0b12"
15"default"
"normal"
"auto"
Idle check-in patience. Renders the effective default (auto) when unset.
auto, patient, off Which side of the call the persona is on. Renders the effective default (agent) when unset.
agent, caller Read-only runtime mode derived from the agent's role (default, sales, or collections). Set indirectly by choosing a role in the console; not writable through this API.
"default"
Read-only archetype the agent was created from, or null. Set in the console; not writable through this API.
Session language for this agent's calls. Renders the effective default (en) when unset.
en, fr, es, de, hi Post-call extraction JSON Schema, or null.
Signed delivery target for post-call extraction, or null.
Unix seconds.