Inbound vs. Outbound calling

Inbound calls

Flows where the caller initiates the session
View as MarkdownOpen in Claude

Inbound flows start when a caller reaches your destination (phone number, WhatsApp destination, SIP username, or app user alias) and a routing rule launches your scenario.

Use AppEvents.CallAlerting as the entry point

All inbound calls use the same entry point, allowing easy, common handling regardless of the channel. Use AppEvents.CallAlerting to answer the call and start your Voice AI logic.

For example:

Inbound Voice AI pattern
1VoxEngine.addEventListener(AppEvents.CallAlerting, async (event) => {
2  const call = event.call;  // call object for the inbound session
3  call.answer();            // stops ringing and connects media
4
5    // Termination functions - add cleanup and logging as needed
6    call.addEventListener(CallEvents.Disconnected, ()=>VoxEngine.terminate());
7    call.addEventListener(CallEvents.Failed, ()=>VoxEngine.terminate());
8
9  // Connect the Voice AI client
10  const voiceAIClient = OpenAI.createRealtimeAPIClient({apiKey: "your-key", model: "your-realtime-model"});
11
12  // Bridge media between the call and the Voice AI client so they can speak and hear each other
13  VoxEngine.sendMediaBetween(call, voiceAIClient);
14});

Inbound guidelines:

  • Answer quickly with call.answer()
  • Listen for key call events (Disconnected, Failed, etc.) and handle as needed
  • Create/configure the connector client
  • Bridge media between call and connector:
    • Use VoxEngine.sendMediaBetween(...) for simple two-party bridging
    • Alternatively use call.sendMediaTo(...) and connector.sendMediaTo(...) for more complex pipelines
  • Invoke methods and handle events from the connector to drive your Voice AI logic

More information: