Outbound

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 currently supports audio only on enabled, ready lines. Use media: { audio: true, video: false }. Inbound readiness alone does not mean a line can place outbound calls.

Choose the project and line

Request value	What it does
Project API key	Authorizes your backend. Use `facetime:write` for create/end and `facetime:read` for status/events.
`X-Chert-Project-Id`	Selects the project that owns the line.
`line_id`	Selects the provisioned FaceTime line and its associated worker (Mac). Chert does not fall back to another line if it is unavailable.
`destination` and `destination_type`	Identify the recipient’s email address or phone number.
LiveKit URL, bridge token, and agent identity	Tell Chert which room to join and provide call-scoped access.

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.
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.

POST https://facetime.trychert.com/api/v1/calls
Authorization: Bearer <project API key>
X-Chert-Project-Id: <project UUID>
Idempotency-Key: <unique create key, 8-200 characters>
Content-Type: application/json

{
  "direction": "outbound",
  "mode": "customer_managed",
  "line_id": "<line UUID>",
  "destination": "recipient@example.com",
  "destination_type": "email",
  "media": { "audio": true, "video": false },
  "livekit_url": "wss://your-project.livekit.cloud",
  "participant_token": "<room-scoped bridge JWT>",
  "remote_participant_identity": "your-agent"
}

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:

GET /api/v1/calls/<call ID>
GET /api/v1/calls/<call ID>/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:

POST https://facetime.trychert.com/api/v1/calls/<call ID>/end
Authorization: Bearer <project API key>
X-Chert-Project-Id: <project UUID>
Idempotency-Key: <unique end key, 8-200 characters>
Content-Type: application/json

{}

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.

Get started

Build with BYOR

Reference

Other models

Choose the project and line

1. Prepare the room and agent

2. Create the call

3. Wait for answer, then greet

4. End and clean up

​Choose the project and line

​1. Prepare the room and agent

​2. Create the call

​3. Wait for answer, then greet

​4. End and clean up

Choose the project and line

1. Prepare the room and agent

2. Create the call

3. Wait for answer, then greet

4. End and clean up