Inbound calls

For the complete documentation index, see llms.txt.

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:

1
VoxEngine.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:

• Calls and Sessions concepts
• Processing calls in scenarios guide
• Launching a routing rule
• VoxEngine Call class