FaceTime calls

This guide covers using the FaceTime API to initiate calls and obtain shareable FaceTime links.

Overview

The FaceTime API lets you programmatically call a contact and receive a shareable facetime.apple.com link. When you initiate a call:

1. A FaceTime link is generated
2. The target contact is rung via FaceTime Audio
3. The first person who joins via the link is auto-admitted
4. The call ends after the participant connects

The result is a shareable link that can be embedded in a web page, sent in a notification, or used in any workflow.

Initiating a call

Call a contact by phone number or email address:

curl -X POST 'https://backend.blooio.com/v2/api/facetime/calls' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"handle": "+15551234567"}'

const res = await fetch('https://backend.blooio.com/v2/api/facetime/calls', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.BLOOIO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ handle: '+15551234567' })
})
const { link } = await res.json()
console.log(link)
// "https://facetime.apple.com/join#v=1&p=..."

import os, requests

res = requests.post('https://backend.blooio.com/v2/api/facetime/calls',
  headers={
    'Authorization': f"Bearer {os.environ['BLOOIO_API_KEY']}",
    'Content-Type': 'application/json'
  },
  json={'handle': '+15551234567'}
)
link = res.json()['link']

You can also call by email:

curl -X POST 'https://backend.blooio.com/v2/api/facetime/calls' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"handle": "john@example.com"}'

Response fields

How the call flow works

When you call the endpoint, the call flow performs three steps:

1. Generate link — Creates a shareable FaceTime link
2. Ring contact — Initiates a FaceTime Audio call to the target handle (async, doesn't block the response)
3. Auto-admit — Monitors the call's waiting room and automatically admits the first person who joins via the link, then the call ends

The link is returned immediately after step 1. Steps 2 and 3 happen in the background.

Error handling

Common patterns

Embedding a FaceTime link in a notification

const { link } = await initiateFaceTimeCall(handle)

await sendPushNotification(userId, {
  title: 'Join the call',
  body: 'Tap to join the FaceTime call',
  url: link
})

Webhook-triggered calls

Combine with webhooks to auto-call when a specific event occurs:

app.post('/webhook', async (req, res) => {
  const event = req.body

  if (event.type === 'message.received' && event.data.text === 'CALL ME') {
    const sender = event.data.from
    const callRes = await fetch('https://backend.blooio.com/v2/api/facetime/calls', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.BLOOIO_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ handle: sender })
    })
    const { link } = await callRes.json()
    console.log(`Call initiated: ${link}`)
  }

  res.sendStatus(200)
})