Inbound vs. Outbound calling

Outbound calls

Flows where your scenario initiates the call
View as MarkdownOpen in Claude

Outbound flows start when you trigger a routing rule manually (Control Panel) or through the Management API (startScenarios). VoxEngine then starts AppEvents.Started.

Outbound Voice AI pattern

Outbound calls have different methods depending on the destination channel (PSTN, SIP, WhatsApp, app user), but the overall pattern is similar: trigger the call, listen for CallEvents.Connected, then set up the Voice AI client and media bridging. The call methods require a callerId. For phone numbers this must be a verified caller ID or a purchased Voximplant number. For WhatsApp, this must be a verified WhatsApp Business number.

Outbound Voice AI pattern
1VoxEngine.addEventListener(AppEvents.Started, () => {
2  // Retrieve information passed when the scenario was triggered
3  const { destination, callerId } = JSON.parse(VoxEngine.customData());
4
5  // Choose your call method based on the destination & desired network
6  const call = VoxEngine.callPSTN(destination, callerId);
7  // const call = VoxEngine.callUser({ username: destination, callerid: callerId });
8  // const call = VoxEngine.callSIP(`sip:${destination}@your-sip-domain`, callerId);
9  // const call = VoxEngine.callWhatsappUser({ number: destination, callerid: callerId });
10
11  // Handle call events
12  call.addEventListener(CallEvents.Disconnected, ()=>VoxEngine.terminate());
13  call.addEventListener(CallEvents.Failed, ()=>VoxEngine.terminate());
14
15  // Set up the Voice AI client and media bridging only after the call is connected
16  call.addEventListener(CallEvents.Connected, async () => {
17    const voiceAIClient = OpenAI.createRealtimeAPIClient({apiKey: "your-key", model: "your-realtime-model"});
18    // Bridge media between the call and the Voice AI client so they can speak and hear each other
19    VoxEngine.sendMediaBetween(call, voiceAIClient);
20  });
21});

Start the outbound flow

Choose one of these options:

Start from the GUI (Control Panel)

In manage.voximplant.com, open your application, go to Routing, choose the rule that points to your outbound scenario, then start it with script_custom_data that includes destination and caller ID.

Start from CLI (Management API)

Use curl to call StartScenarios and pass the same script_custom_data JSON payload from your terminal.

CLI example via StartScenarios
$curl -X POST "https://api.voximplant.com/platform_api/StartScenarios/" \
>  --data-urlencode "account_id=$VOX_ACCOUNT_ID" \
>  --data-urlencode "api_key=$VOX_API_KEY" \
>  --data-urlencode "rule_id=$VOX_RULE_ID" \
>  --data-urlencode "script_custom_data={\"destination\":\"+15551234567\",\"callerId\":\"+15557654321\"}"

If using the management API via curl or one of the management API Clients, you will need to configure an API key and create an authorization token.

Outbound checklist

  • Listen for the AppEvents.Started entry point
  • Use VoxEngine.customData() to retrieve any information needed for the scenario, such as destination and caller ID to use
  • Place the channel-specific call using one of the call methods (callPSTN, callUser, callSIP, callWhatsappUser)
  • Listen for key call events (Disconnected, Failed, etc.) and handle as needed
  • Create the Voice AI connector after CallEvents.Connected
  • 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: