Quickstart

What to have ready

A Chert project and provisioned FaceTime line, including its handle and line ID.
Your LiveKit project, WebSocket URL, and server-side API key and secret.
A backend that prepares a room and mints separate tokens for your agent and Chert’s bridge.
An agent that publishes audio and consumes the caller’s audio. For inbound video, also publish and subscribe to video.
A person ready to place or answer the test call. Each line handles one active call at a time.

Chert operates the FaceTime endpoint; you do not need to install the open-source connector. Inbound calls need an acceptance webhook. Outbound calls use an authenticated API request and require an outbound-enabled line.

1. Get your project key

Open Developer → Project API keys. Create a key with facetime:write for create/end and facetime:read for status/events. Store it on your backend and copy the Project ID.

export CHERT_API_KEY="<your-project-api-key>"
export PROJECT_ID="<your-project-uuid>"
export BASE=https://facetime.trychert.com/api

2. Choose your line

curl "$BASE/v1/lines" \
  -H "Authorization: Bearer $CHERT_API_KEY" \
  -H "X-Chert-Project-Id: $PROJECT_ID"

Confirm the line’s worker is accepting calls with fresh readiness in Workers & Lines. For outbound, confirm that this line is enabled for outbound audio, then use its exact ID as line_id. Chert does not fall back to another line when it is unavailable.

3. Prepare your LiveKit agent

Run your agent in your room with exactly one eligible, unmuted audio publication. Mint a separate, room-scoped bridge token with join, publish, and subscribe grants and an identity distinct from your agent. See the token requirements. For outbound, keep the agent silent until bridge_ready. The bridge token needs more than 90 seconds remaining at allocation and an issued lifetime of at most two hours.

4. Choose a calling direction

Inbound
Outbound

Set the line to customer_decides with no default Assistant. Configure its HTTPS Integration URL. If you enable webhook signing, store the signing secret on your backend and verify incoming signatures.On call.incoming, return an accept response within the decision deadline (five seconds by default):

{
  "action": "accept",
  "livekit_url": "wss://your-project.livekit.cloud",
  "participant_token": "<room-scoped bridge JWT>",
  "remote_participant_identity": "your-agent"
}

Call your provisioned handle using FaceTime Audio, or FaceTime Video on a video-enabled line. The BYOR guide covers the incoming event and decline response.

Your backend sends the request; no incoming-decision webhook is needed. Use audio only and save this body as a protected local file named outbound-call.json, replacing the placeholders:

{
  "direction": "outbound",
  "mode": "customer_managed",
  "line_id": "<your-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"
}

Send it with a unique create key (8–200 characters):

curl --fail-with-body "$BASE/v1/calls" \
  -H "Authorization: Bearer $CHERT_API_KEY" \
  -H "X-Chert-Project-Id: $PROJECT_ID" \
  -H "Idempotency-Key: $CREATE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @outbound-call.json

Set CREATE_KEY before running the command. HTTP 201 means allocated, not answered. Save data.id as CALL_ID. Retry an uncertain request with the same body and key; do not create a new attempt automatically.Poll GET /api/v1/calls/<call ID>/events with the same project headers. Start the greeting once on bridge_ready, or the corresponding outbound call.started webhook. Room join or an active status alone is insufficient. Ignore activation after termination.See Outbound for phone destinations, line selection, and the full flow.

5. Verify the call and cleanup

Confirm clear two-way audio. For inbound video, also confirm that each side sees the other’s current video. Subscribe to the bridge’s facetime-remote-audio track and, when enabled, facetime-remote-video. Hang up from either end, or end through the API using the call ID and a unique end key (8–200 characters):

curl --fail-with-body -X POST "$BASE/v1/calls/$CALL_ID/end" \
  -H "Authorization: Bearer $CHERT_API_KEY" \
  -H "X-Chert-Project-Id: $PROJECT_ID" \
  -H "Idempotency-Key: $END_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{}'

Set END_KEY before running the command. HTTP 202 acknowledges the request. Check that FaceTime ends, the call becomes terminal, and the line becomes available again. Your backend must also release its agent and room resources. See Calls API.

Get started

Build with BYOR

Reference

Other models

What to have ready

1. Get your project key

2. Choose your line

3. Prepare your LiveKit agent

4. Choose a calling direction

5. Verify the call and cleanup

​What to have ready

​1. Get your project key

​2. Choose your line

​3. Prepare your LiveKit agent

​4. Choose a calling direction

​5. Verify the call and cleanup

What to have ready

1. Get your project key

2. Choose your line

3. Prepare your LiveKit agent

4. Choose a calling direction

5. Verify the call and cleanup