FaceTime Audio

contiguity.facetime

Only customers who lease numbers that support FaceTime Audio can use this.

Phone numbers must be in E.164 format. to can also be a FaceTime email.

If you omit from on dial, Contiguity picks one of your leased FaceTime Audio numbers at random. caller_id is optional and is presented as Maybe: caller_id. If not provided, it is a formatted version of your leased number, e.g. Maybe: +1 (415) 555-1234.

Join as the number

webrtc.join opens the call as the Contiguity FaceTime Audio line — not a third participant.

FaceTime Web

Once Apple creates it, link is a FaceTime Web URL. Opening it joins the call in the browser as a web participant.

Dial

Place an outbound FaceTime Audio call. Creates a call in queued and fires facetime.call.initiated. When the remote side starts ringing, status becomes ringing and Contiguity fires facetime.call.ringing. At dial time link is null, participants is [], and duration is null.

const call = await contiguity.facetime.dial({
    to: "+15125550100",
    from: "+18005551234",
    caller_id: "Tesla Support",
});

facetime.dial(params)

string

required

Recipient E.164 number or FaceTime email.

string

Your leased FaceTime Audio number. If omitted, a random one of yours is used.

string

Presented as Maybe: caller_id.

Get

Fetch a call by ID. FaceTime webhooks send this same object in data.

const call = await contiguity.facetime.get("call_fta...");
const call = await contiguity.facetime.get(event);

facetime.get(ref)

string | object

required

Call ID string, a parsed webhook event, or event.data.

Answer

Answer an inbound ringing call. Moves the call to in_progress and fires facetime.call.answered.

await contiguity.facetime.answer(event);
await contiguity.facetime.answer(event, { caller_id: "Support" });
await contiguity.facetime.answer("call_fta...");

facetime.answer(ref, params?)

string | object

required

Call ID string, a parsed webhook event, or event.data.

string

Optional caller ID to present on the call.

Reject

Reject a ringing inbound call. Fires facetime.call.rejected.

await contiguity.facetime.reject(event);
await contiguity.facetime.reject("call_fta...");

facetime.reject(ref)

string | object

required

Call ID string, a parsed webhook event, or event.data.

Hang up

Ends the call from your side. cause becomes dialer_hungup and Contiguity fires facetime.call.ended. If the remote party hangs up first, you still get facetime.call.ended with cause recipient_hungup. You do not need to hang up in that case.

await contiguity.facetime.hangup(event);
await contiguity.facetime.hangup("call_fta...");

facetime.hangup(ref)

string | object

required

Call ID string, a parsed webhook event, or event.data.

Availability

Check if a phone number or email supports FaceTime.

const { available } = await contiguity.facetime.availability("+15125550100");
const { available } = await contiguity.facetime.availability("user@example.com");

facetime.availability(to)

string

required

E.164 phone number or FaceTime email.

Response

boolean

Whether the address supports FaceTime.

object

Request metadata: id, timestamp, api_version, object.

Webhook comfort

get, answer, reject, and hangup take a call ID string, a parsed webhook event, or event.data — the same pattern as text.reply(event).

const event = contiguity.webhook.parse(raw_body);

if (event.type === "facetime.call.ringing") {
    await contiguity.facetime.answer(event, { caller_id: "Support" });
}

Throws FaceTime webhook data must have call_id if neither the event nor the object has a call_id. See Webhooks for verify / parse, or the v2 event payloads.

Call object

Returned by dial, get, answer, reject, hangup, and every facetime.call.* webhook in data.

string

FaceTime call ID.

string

The FaceTime Audio number this call is on.

string

Destination address.

string

Originating address.

string | null

Caller ID presented on this call.

string

inbound or outbound.

string

queued, ringing, in_progress, completed, or failed.

string | null

null while live. dialer_hungup if you hang up; recipient_hungup if they left; otherwise another end reason.

string | null

FaceTime Web join URL once Apple creates it. null during queued and ringing.

object | null

Present while the call is active, null after it ends.

Show WebRTC properties

string | null

URL to join as the Contiguity FaceTime Audio line.

string

WebRTC server URL.

string

WebRTC room name.

string

WebRTC join token.

string[]

Live roster while the call is up; remaining handles after it ends.

string

When the call was created.

string | null

When the call was answered, else null.

string | null

When the call ended, else null.

number | null

Connected time in seconds. null until the call ends.

object

Request metadata: id, timestamp, api_version, object.

`status`	meaning
`queued`	Outbound dial created the call
`ringing`	Outbound is ringing, or an inbound call arrived
`in_progress`	The call was answered
`completed`	The call ended (you hung up, they hung up, or FaceTime disconnected)
`failed`	Contiguity could not place the call

Stage	`participants`
initiated / ringing	`[]`
answered	The remote party, e.g. `["+15559876543"]`
ended	Remaining handles after hangup. Often just your FaceTime Audio line

FaceTime webhooks

Posted to your facetime webhook URL, else catchall. Envelope is the v2 webhook format. data is the same call object as facetime.get().

`event.type`	when	`data.status`
`facetime.call.initiated`	Outbound dial created the call	`queued`
`facetime.call.ringing`	Outbound is ringing, or an inbound call arrived	`ringing`
`facetime.call.answered`	The call is connected. `link` is now the FaceTime join URL	`in_progress`
`facetime.call.rejected`	You rejected an inbound ringing call via `facetime.reject()`	—
`facetime.call.failed`	Contiguity could not place the call	`failed`
`facetime.call.ended`	You hung up, they hung up, or FaceTime disconnected. `webrtc` is `null`, `duration` is set	`completed`

import { Contiguity } from "contiguity";

const contiguity = new Contiguity("contiguity_sk_...");

export async function POST(req) {
    const raw_body = await req.text();
    if (!contiguity.webhook.verify(raw_body, req.headers.get("contiguity-signature"), process.env.CONTIGUITY_WEBHOOK_SECRET)) {
        return new Response("invalid signature", { status: 401 });
    }

    const event = contiguity.webhook.parse(raw_body);
    const call = event.data;

    switch (event.type) {
        case "facetime.call.ringing":
            if (call.direction === "inbound") {
                await contiguity.facetime.answer(event, { caller_id: "Support" });
            }
            break;
        case "facetime.call.answered":
            call.link;
            call.webrtc.join;
            break;
        case "facetime.call.ended":
            call.duration;
            call.cause;
            break;
    }

    return new Response("ok");
}

Types

import type {
    FacetimeCall,
    FacetimeCallData,
    FacetimeCallRef,
    FacetimeDialParams,
    FacetimeAnswerParams,
    FacetimeAvailableResponse,
    FacetimeWebRTC,
    FacetimeCallStatus,
    FacetimeCallDirection,
} from "contiguity";

FacetimeCallData is an alias of FacetimeCall — the webhook data payload.

Getting Started

SDK Documentation by Product

SDK Documentation by Language

Join as the number

FaceTime Web

Dial

facetime.dial(params)

Get

facetime.get(ref)

Answer

facetime.answer(ref, params?)

Reject

facetime.reject(ref)

Hang up

facetime.hangup(ref)

Availability

facetime.availability(to)

Response

Webhook comfort

Call object

FaceTime webhooks

Types

Join as the number

FaceTime Web

​Dial

​facetime.dial(params)

​Get

​facetime.get(ref)

​Answer

​facetime.answer(ref, params?)

​Reject

​facetime.reject(ref)

​Hang up

​facetime.hangup(ref)

​Availability

​facetime.availability(to)

​Response

​Webhook comfort

​Call object

​FaceTime webhooks

​Types

Dial

facetime.dial(params)

Get

facetime.get(ref)

Answer

facetime.answer(ref, params?)

Reject

facetime.reject(ref)

Hang up

facetime.hangup(ref)

Availability

facetime.availability(to)

Response

Webhook comfort

Call object

FaceTime webhooks

Types