Inbound & Outbound

VoxBridge supports two call directions. Configure separate agents, voices, and prompts for proactive outbound campaigns and reactive inbound support lines.

Call directions

Direction	Who initiates	Typical use	API entry
`outbound`	Your application	Welcome calls, reminders, collections	`POST /v1/calls/outbound`
`inbound`	Caller dials your number	Support desk, IVR replacement	SIP routing (Phase 2)

Each Agent record has a direction field. Outbound API requests resolve an outbound agent; inbound SIP legs resolve an inbound agent based on trunk rules and DID mapping.

Outbound call flow

Your backend POSTs to /v1/calls/outbound with to, optional agent_id, and context.
VoxBridge validates minutes quota, normalizes the phone to E.164, and creates a Call in queued status.
Webhook call.queued is delivered to your org or per-call webhook_url.
When telephony is configured, the dispatcher creates a media session and SIP participant; status moves to calling, then completed or failed.
Transcripts and structured answers trigger call.ended and call.analyzed webhooks.

POST /v1/calls/outbound → queued (201) → [telephony] calling → completed + webhooks

Outbound queue

Calls are persisted immediately — the API does not block on dial completion. This design lets you:

Queue thousands of calls from batch jobs without holding HTTP connections open
Schedule future dials with schedule_at (ISO 8601 UTC)
Retry failed attempts up to max_attempts (default 3)

Until telephony and media workers are configured, calls remain in queued after creation. Configure environment variables described in SIP & telephony to enable live dialing.

Inbound SIP (Phase 2)

Inbound calls arrive via SIP trunks terminated into the platform media layer. VoxBridge maps your DID to an organization and selects the inbound agent (e.g. Inbound Support Agent with calm_support voice).

Setup checklist:

Provision a SIP connection and phone number with your carrier
Configure inbound SIP trunk and dispatch rules on the media server
Associate the number with your organization in platform admin / env config
Ensure an active direction: inbound agent exists for the tenant

Choosing agents per call

Pass agent_id on outbound requests to override the default. Use slug-friendly names in your CRM mapping (e.g. welcome vs collections) by storing agent UUIDs after listing GET /v1/agents.

Minutes and limits

Each organization has minutes_included and minutes_used. Outbound queue returns 402 Payment Required when the monthly allowance is exhausted. Inbound minutes count toward the same pool once billing meters are active.

Calls API → · SIP & telephony → · Agent configuration →