Skip to main content
After an Omni call ends, PyAI can run an extraction pass over the transcript and deliver a structured JSON object, captured fields, intent, outcome, to your webhook. No client code and no engine integration required: you declare a JSON Schema on the agent and point it at an HTTPS endpoint.
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:
Or use the console: Agents → your agent → Information to collect. Both fields are required to enable extraction. Set either to 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’s session_label to that agent’s id:
PyAI resolves the agent only when the 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 with X-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, or 5xx); a 4xx is treated as a permanent client error and is not retried. Return 2xx quickly. 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.