## FaceTime Audio

> **FaceTime-enabled accounts only**
>
> These endpoints are available only on API accounts with FaceTime Audio enabled. Calls from accounts without the feature return 403 with error code `FACETIME_NOT_ENABLED` — that means the feature isn't active on your account, not that the API is down. Interested in FaceTime Audio? Contact [sales@tryprojectblue.com](mailto:sales@tryprojectblue.com) or reach out to support to upgrade.

Initiate real FaceTime Audio calls programmatically and connect to the live call audio via WebRTC using Agora's SDK. The `pb_line_id` must be a FaceTime-enabled line on your account.

`POST /start-facetime-call-api`

### Request body

- `pb_line_id` (string (UUID), required) — FaceTime-enabled line to call from. UUID returned from GET /get-lines.

- `phone_number` (string (E.164), required) — Destination phone number. Flexible formats accepted; normalized to E.164.

### Response

- `status` ("OK", required) — Present on every successful call.

- `call_uuid` (string, required) — Identifies the call. Pass it to the status and end endpoints.

- `agora` (object | null, required) — WebRTC credentials for joining the call audio, or null when the device placed the call but returned no credentials. The call is still ringing in that case — you simply cannot join its audio, so check for null before calling the Agora SDK.

  - `appId` (string, required) — Agora application id.

  - `channelName` (string, required) — Channel to join for this call.

  - `token` (string, required) — Time-limited RTC token. Join promptly after starting the call.

  - `uid` (number, required) — The uid to join as.

### Joining the call

The returned `agora` credentials are used with the Agora Voice SDK to stream audio to and from the FaceTime call. Tokens are time-limited, so join the channel promptly after starting the call.

> **agora can be null on a 200**
>
> A `200` means the call was placed, not that you can hear it. When the device returns no credentials, `agora` is `null` and the call still rings — check for it before touching the SDK, and fall back to polling [`/get-facetime-call-status-api`](https://api.tryprojectblue.com/#facetime-status) for the outcome.

**Request — cURL**

```bash
curl -X POST https://api.tryprojectblue.com/start-facetime-call-api \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pb_line_id": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5",
    "phone_number": "+15551234567"
  }'
```

**Response — 200 OK**

```json
{
  "status": "OK",
  "call_uuid": "ftc_8a2b1c3d4e5f6g7h",
  "agora": {
    "appId": "your-agora-app-id",
    "channelName": "facetime-channel-abc123",
    "token": "agora-rtc-token...",
    "uid": 123456
  }
}
```

**Join the call — JavaScript**

Tokens are time-limited — join promptly. Check res.agora is non-null first.

```javascript
import AgoraRTC from "agora-rtc-sdk-ng";

const client = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" });
await client.join(
  res.agora.appId,
  res.agora.channelName,
  res.agora.token,
  res.agora.uid,
);
const mic = await AgoraRTC.createMicrophoneAudioTrack();
await client.publish([mic]);
client.on("user-published", async (user, mediaType) => {
  await client.subscribe(user, mediaType);
  if (mediaType === "audio") user.audioTrack.play();
});
```