Skip to main content
Your backend prepares a LiveKit room and agent, then sends an authenticated request to POST https://facetime.trychert.com/api/v1/calls. Chert uses the line you select to dial the recipient and connect the call to your room. Outbound BYOR supports audio and video through this same endpoint. Use media: { audio: true, video: true } for FaceTime Video, or media: { audio: true, video: false } for FaceTime Audio.

Line eligibility

Outbound video is enabled for eligible Free, Shared, and Dedicated lines. Your project must hold a current shared allocation or a dedicated assignment. The selected line must support outbound audio and video and have fresh audio and video readiness. Eligible lines do not need a separate project or line whitelist entry. Recipient verification, billing, trial expiry, usage limits, and line availability still apply. Free and Shared calls require verified recipients. Dedicated calls follow the line’s configured recipient policy. Inbound or audio readiness alone does not establish outbound video readiness. Caller-camera capture is a separate capability and is not enabled automatically by an outbound video request. See Audio and video.

Choose the project and line

Get your project and line IDs from the dashboard or list your lines. Keep the project key and LiveKit credentials on your backend. Inbound calls ask your webhook to accept or decline. Outbound calls start with your API request; no incoming-decision webhook is needed. You can observe events through the API or use an assigned integration for lifecycle notifications.

1. Prepare the room and agent

  • Join your agent to the room with exactly one eligible, unmuted audio publication, but keep it silent until the activation event below.
  • For video calls, also publish your agent’s video or avatar track into the room before dialing. See Audio and video.
  • Mint a separate bridge token with a distinct identity and permission to join, publish, and subscribe to this one room.
  • Follow the token requirements. The bridge token must have more than 90 seconds remaining when the call is allocated, with an issued lifetime of at most two hours. Allow enough time for ringing and conversation.
  • Disable any greeting triggered by room join. The bridge joins before the recipient answers.

2. Create the call

Use your own project and line IDs. The values below are placeholders.
For a phone recipient, use destination_type: "phone" and an international number such as +15551234567. HTTP 201 means allocated, not dialed or answered. Save the returned data.id as your call ID. Retry the same request with the same idempotency key to retrieve the original call. Materially different call or room fields with that key return 409. If a response is lost, do not switch to a new key and risk another call.

3. Wait for answer, then greet

With the same project authentication, observe the call and its events.
Start the greeting on bridge_ready, or the corresponding outbound call.started webhook when an integration is configured. Room join, HTTP 201, and an active status alone are not the signal to speak. Greet only once per call ID and ignore activation after the call ends or fails. Subscribe to the bridge’s caller audio and publish your agent’s replies into the room.

4. End and clean up

Either party can hang up. To end through the API, use a separate idempotency key.
HTTP 202 acknowledges the end request. Continue observing until the call is terminal and the line is available again. Chert cleans up its bridge and stored credentials; your backend must release its own agent, dispatch, and room resources, including after failures. Group calling is generally available on Free, Shared, and Dedicated lines through the same Calls API. Use recipients instead of destination and destination_type; no iMessage group chat is needed. Free and Shared require every recipient to be phone-verified for the project and line. Dedicated lines follow their configured recipient policy. Joining an existing FaceTime link is enabled separately. Use destination_type: "facetime_link" on a line with that capability. On shared lines, add when_busy: "queue" to opt into the busy-call queue. Its 202 waiting receipt is different from a 201 allocated call.