Calling

Voice calls use the same service key, connection grants, contact IDs, conversation IDs, and ownership checks as messaging. Ruut delegates telephony to the configured Ruut Voice or Twilio connection. Provider credentials stay on the server.

Before you start

Create or connect a voice inbox in Ruut, grant it to your key, and enable calls:read and calls:write. Grant the conversation's inbox too if you are starting a call from a messaging conversation. The contact needs an E.164 phone identity. GET /api/v2/connections reports voice in the connection's supported transports.

Start a call

Read the conversation's current owner_version, then start the call:

1234POST /api/v2/conversations/{conversation_id}/calls
Authorization: Bearer YOUR_KEY
Idempotency-Key: call-start-0001
Content-Type: application/json

12345{
  "connection_id": "conn_your_voice_connection",
  "expected_owner_version": 0,
  "twiml": "<Response><Say>Hello from Ruut.</Say></Response>"
}

Use the actual owner version returned by your conversation. The response is 202 Accepted with a cal_ ID. accepted means the request is durably queued; it does not mean the recipient has answered.

Omit twiml to use the voice connection's existing conference flow, allowing support staff to join through the app. Inline TwiML uses Ruut Voice's programmable calling engine. XML entities are rejected. Media and callback URLs must use HTTPS or WSS on origins configured by the installation operator.

Read call state

Use GET /api/v2/calls/{call_id} for the current state or list calls with GET /api/v2/conversations/{conversation_id}/calls. The resource includes direction, provider, duration, transcript when available, and the latest control operation. Subscribe to call.created and call.updated for changes.

Queued calls recheck key permissions and conversation ownership before dialing. A network failure with an uncertain outcome becomes unknown and is not automatically dialed again. Provider callbacks correlate to the same call resource, including when an acceptance response was lost.

Control an active call

Send a PATCH with a new idempotency key and the current conversation ownership version:

1234{
  "action": "complete",
  "expected_owner_version": 0
}

Supported actions are complete, cancel, and redirect. A redirect includes replacement twiml; use the engine's TwiML verbs for announcements, transfer, or call routing. Control operations are queued and observable through last_operation. Wait for an existing operation to finish before submitting another.

Recordings and transcripts

Read the transcript from the call resource when the voice connection supplies one. With calls:read and media:read, use GET /api/v2/calls/{call_id}/recording to obtain an authorized recording download URL. Provider authentication is never included in that URL. Download expiry is returned when known; request a fresh link when it expires.

Browser calling and voice engine SDK

Ruut Voice provides a TypeScript SDK, a browser WebRTC softphone, SIP calling, TwiML, recording, and transcription APIs. See the Ruut Voice quickstart and browser SDK for media transport and device setup. The conversation API handles conversation identity, access, ownership, and call resources; the voice engine handles signaling and audio.