Voice

Dispatch one ad-hoc AI-agent call to a raw number

Dispatch a single AI-agent call to an arbitrary number right now.

No dialer session or contact list required - this wraps voice's POST /api/call/start (voice/graph8_livekit/routers/call.py:19), the one-off "call this number" primitive that previously had no public surface at all. Places a REAL call and is billable upstream (voice checks the org's subscription and concurrent-call cap before dispatching). Send an Idempotency-Key header to make a retry safe - every POST on this API already honors it via the app-wide IdempotencyMiddleware, so no extra field is needed here.

Org is pinned server-side; phone numbers are normalized to E.164 by voice itself (a malformed number 400s with an actionable message).

post/voice/calls

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/voice/calls
  • Auth: HTTP bearer

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

to_phonestring required

Number to call. Normalized server-side.

from_phonestring required

Caller ID. Must be one of the org's numbers.

agent_idstring nullable

Voice agent UUID. Use GET /voice/agents to look up.

entity_type'agent' | 'twin' nullable

"agent" or "twin". Optional.

agent_namestring nullable

Legacy V1 agent-name fallback.

first_namestring nullable

Contact first name, for the agent's context.

last_namestring nullable

Contact last name, for the agent's context.

emailstring nullable

Contact email, for the agent's context.

contact_idstring nullable

CDP contact id, if this call is tied to a known contact.

timezonestring

IANA timezone for the callee.

campaign_idstring nullable

Optional campaign id for attribution.

studio_campaign_idstring nullable

Optional Campaign Builder (Studio) campaign UUID.

dry_runboolean

If true, the call is validated but not actually dispatched.

event_idinteger nullable

Appointments event-type id the agent can offer to book. Omit if this call has no booking flow.

callback_urlstring nullable

Webhook notified with the call result on completion. Optional.

Response

Successful Response

Changes

No recorded changes to this operation across all 2 revisions of this API.