This is post-call capture (after the call, fully PyAI-run). For in-call
function calling where your code executes mid-conversation, see
Function calling. Use Recap for standard summaries and action items.
Configure
Set two fields on the agent, a JSON Schema of the fields to capture and a signed delivery URL:null to turn it
off. extraction_webhook_url must be https.
How a call is matched to your agent
Omni is zero-state, a call is authorized by your key’s org, not a stored agent. To attribute a call to a specific agent’s extraction config, set the connect URL’ssession_label to that agent’s id:
session_label equals an agent id in the
same org, so another tenant’s id can never trigger your extraction.
The delivery (engine → your webhook)
When the call completes, PyAI POSTs the extracted object, signed withX-PyAI-Signature (same scheme as transcription webhooks):
Correlating to your own record.
call_id is PyAI-generated and round-trips
through every call sub-resource. To map it to your own system, set a meta
object on the session (for example, a meta.external_id you control). PyAI
echoes customer metadata and lifts a string meta.external_id to the top-level
external_id; reserved internal fields are never included. session_label is
also echoed, but it doubles as the agent_… resolution id, so prefer
meta.external_id for a per-call key. Both external_id and meta are null
when nothing was set.Verify the signature
Use the shared webhook verification guide and complete receiver. Verify the signature over the original body bytes, enforce timestamp tolerance, and handle duplicate deliveries before applying side effects. The organization signing secret is separate from the API key; the guide covers safe provisioning and rotation.Behavior & limits
- Best-effort / fail-open. Extraction never blocks or fails a call. If the transcript is empty, the model can’t produce valid JSON, or your webhook is down, the call is unaffected and nothing is delivered.
- Missing fields can be
null. Treat extracted values as model output and validate them before using them for business actions. - The transcript is truncated for very long calls before the extraction pass.
- Delivery retries up to 3 times with a short backoff on a transient failure
(network error,
429, or5xx); a4xxis treated as a permanent client error and is not retried. Return2xxquickly. Delivery is at-most-once per attempt and not strongly durable, treat a missed event as best-effort.
See also
Knowledge bases
Ground answers in your own content.
Function calling
In-call tools your client executes.
Omni protocol
Connect URL,
session_label, frames.Conversation intelligence
Transcripts, summaries, recordings.