Sendblue FaceTime Audio

Use Sendblue when the agent should call through FaceTime Audio from an iMessage-enabled business number. Sendblue starts the FaceTime call and returns short-lived Agora credentials; your server joins that Agora channel and bridges its live audio to Inkibra.

Prerequisites

A purchased, FaceTime-enabled Sendblue line
Sendblue API key ID and secret
A Linux media service using an Agora Server SDK with raw-audio subscription and custom PCM publication
INKIBRA_API_KEY stored on the media service

FaceTime calling is an account upgrade. Ask Sendblue to enable it before implementing the relay. This guide is for live voice, not iMessage automation; the iMessage-enabled number matters because it is the identity shown to the person receiving the FaceTime call.

1. Start the FaceTime call

Call Sendblue from your server with E.164 numbers:

1234567891011121314const response = await fetch("https://api.sendblue.com/facetime/start-call", {
  method: "POST",
  headers: {
    "sb-api-key-id": process.env.SENDBLUE_API_KEY_ID!,
    "sb-api-secret-key": process.env.SENDBLUE_API_SECRET!,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+14155550123",
    fromNumber: process.env.SENDBLUE_FACETIME_NUMBER,
  }),
});

const { agora } = await response.json();

The response contains appId, channelName, token, and uid. The token is time-limited; hand it directly to the media service and join immediately. Never log it or return it to an application browser.

2. Join Agora from the media service

Run the Agora client headlessly. Subscribe to remote audio before the recipient answers, register a raw-audio observer, create a custom PCM audio track, and publish that track into the same channel.

12345678const agoraCall = await AgoraFaceTimeBridge.join({
  appId: agora.appId,
  channel: agora.channelName,
  token: agora.token,
  uid: agora.uid,
  subscribeAudio: true,
  publishCustomPcm: true,
});

AgoraFaceTimeBridge is an application adapter around an Agora Linux Server SDK—not the browser example that captures a microphone and plays through speakers. The server SDK must expose remote raw PCM frames and accept custom PCM frames for publication.

3. Connect Inkibra

123456789import LiveVoice from "@inkibra/voice-sdk/server";

const live = await LiveVoice.connect({
  apiKey: process.env.INKIBRA_API_KEY!,
  audio: new AgoraAudioTransport(agoraCall),
  prompt: "Help the caller schedule an appointment.",
  conversation: { starts: "assistant" },
  tools: {},
});

The transport follows the server media contract:

Configure the Agora raw-audio observer for mono PCM and resample each remote frame to PCM16LE 24 kHz before handlers.input.
Maintain the resampler across callbacks; never block Agora's audio callback thread.
Hold Inkibra mode: buffer audio locally by generation.
On release, publish PCM to the custom Agora track at the selected gain.
On cancel, remove unsent PCM and interrupt already-submitted custom-track audio before reporting cancelled.
Derive started and completed receipts from actual publication/playout progress, not TTS download completion.

4. End the call cleanly

When the remote Agora participant leaves or the channel closes, call handlers.close. When Inkibra closes first, stop publication and leave the Agora channel. Release the raw-audio observer, custom track, Agora connection, and Inkibra session exactly once.

Sendblue's call_log webhook applies to outbound calls placed from its dashboard and is not the real-time media lifecycle. For an API-started FaceTime session, use the Agora participant/channel lifecycle as the immediate source of truth unless Sendblue enables an additional call-status callback for the account.

Smoke test

Call a real iPhone and confirm it receives FaceTime Audio from the purchased Sendblue number.
Confirm the media service—not a browser—joins using the returned Agora credentials.
Speak from the iPhone and verify raw remote PCM reaches Inkibra continuously.
Confirm Inkibra reactions and foreground speech are audible on the iPhone.
Interrupt the assistant and verify Agora publication is cleared before the adapter reports cancelled.
Decline and then answer separate calls; verify both paths release every Agora and Inkibra resource.
Attempt to reuse expired Agora credentials and verify the integration fails closed without creating an Inkibra session.

Sendblue FaceTime API · Agora raw audio processing · Agora Python Server SDK