FaceTime API

Calling

Initiate FaceTime calls programmatically via WebRTC

Initiate FaceTime calls programmatically and connect to the audio stream via WebRTC using Agora’s SDK.

Start a Call

POST https://api.sendblue.co/facetime/start-call

Request Body

Parameter	Type	Required	Description
`phoneNumber`	string	Yes	The phone number to call (E.164 format)
`fromNumber`	string	Yes	Your Sendblue FaceTime number (E.164 format)

Example Request

curl -X POST 'https://api.sendblue.co/facetime/start-call' \
  -H 'sb-api-key-id: YOUR_API_KEY' \
  -H 'sb-api-secret-key: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+14155550123",
    "fromNumber": "+18885550199"
  }'

Success Response (200)

{
  "status": "OK",
  "message": "Call started",
  "agora": {
    "appId": "a1b2c3d4e5f6789012345678abcdef90",
    "channelName": "ft_call_9f8e7d6c5b4a3210",
    "token": "007eJxTYDhw4MCBAwcOHDhw4MCB...",
    "uid": 0
  }
}

Response Fields

Field	Type	Description
`status`	string	Request status (`OK` on success)
`message`	string	Human-readable status message
`agora.appId`	string	Agora application ID for joining the channel
`agora.channelName`	string	Unique channel name for this call
`agora.token`	string	Authentication token for joining the channel
`agora.uid`	number	User ID to use when joining (use `0` for auto-assign)

Joining the Call

Once you receive the Agora credentials, use the Agora Voice SDK to join the channel and stream audio to/from the FaceTime call.

JavaScript Example

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

const client = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" });

// Join using credentials from the API response
await client.join(
  response.agora.appId,
  response.agora.channelName,
  response.agora.token,
  response.agora.uid
);

// Create and publish your microphone track
const microphoneTrack = await AgoraRTC.createMicrophoneAudioTrack();
await client.publish([microphoneTrack]);

// Listen for remote audio (the FaceTime call audio)
client.on("user-published", async (user, mediaType) => {
  await client.subscribe(user, mediaType);
  if (mediaType === "audio") {
    user.audioTrack.play();
  }
});

Notes

Phone numbers must be in E.164 format (e.g., +1 followed by the 10-digit number for US numbers)
The fromNumber must be a FaceTime-enabled Sendblue number on your account
Agora tokens are time-limited; initiate your call promptly after receiving credentials