> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychert.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound

> Start a FaceTime Audio call from your backend using your own LiveKit agent.

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](/facetime/quickstart#connectivity). 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](/facetime/bring-your-own-room#token). 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.

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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.