Events

For live caller turns, use the outbound Agent Relay. It reconnects, retains events until ACK, and works without a public inbound URL. Use the mailbox for non-live fallback awareness when neither relay nor webhook is available. See Agent Relay for the two-command runtime setup.

Poll (fallback, consume once)

poll returns pending events and deletes them — treat it as a one-time read.

result = client.events.poll(event_type="call.completed", limit=50)
for e in result["events"]:
    print(e["event_type"], e["payload"])

const result = await client.events.poll({ eventType: "call.completed", limit: 50 });
for (const e of result.events) console.log(e.event_type, e.payload);

Each event has { event_id, agent_id, event_type, payload, created_at }. Common event_types include call.utterance, call.completed, call.failed, call.owner_task, and sms.received.

Peek (non-destructive)

peek previews what’s queued without consuming it — handy to check before committing to retrieve.

client.events.peek(agent_id=agent.id)

await client.events.peek({ agentId: agent.id });

Prefer Agent Relay for live calls, then webhooks for a public inbound integration. Use the mailbox for fallback polling only.

⌘I

Get Started

Guides

SDKs

Events

Events

Poll (fallback, consume once)

Peek (non-destructive)

​Events

​Poll (fallback, consume once)

​Peek (non-destructive)

Events

Poll (fallback, consume once)

Peek (non-destructive)