Calls

A call is one phone conversation OpenPhn runs on your behalf. Calls are created via POST /v1/calls (outbound) or triggered by an inbound dial to a number you own.

Outbound lifecycle

create → queued → dialing → in_progress → completed
                                        └→ failed

Create a call with an objective and outcome_schema; we dial the number, run the conversation, and populate outcome when finished. If the call hits voicemail, fails to connect, or is rejected, status moves to failed with a failure_reason.

Batch up to 200 calls with POST /v1/calls/batch. Each item in the batch is independently validated (DNC, call-hour rules) and gets its own call_id.

Inbound lifecycle

An inbound dial to a number you own is picked up by Twilio's media stream endpoint. The number's configured greeting plays, then one of these paths runs:

• Flow — a published flow graph drives the conversation.
• Transfer — the transfer_to_human tool hands off to one of up to five destination phones (see Transfers).
• Freeform — the model answers questions per the number's configured persona.

Idempotency

POST /v1/calls and POST /v1/calls/batch accept an Idempotency-Key header. A repeated request with the same key within 24h returns the original response instead of creating a duplicate. Use this on retries.

DNC enforcement

Every create is checked against:

1. Global suppression list — federal DNC imports, your admin's platform-wide blocks.
2. Your tenant's DNC — everything you've uploaded or added manually.

See DNC.