Inbound vs. Outbound calling

Outbound calls

Flows where your scenario initiates the call
View as Markdown

For the complete documentation index, see llms.txt.

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

Alternatively you can start the outbound flow against a call list for automated dialing see call lists for automated outbound calling.

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.

Control Panel demo video: manage-run-rule.mp4

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:

Call lists for automated outbound calling

When you need to dial many contacts, you can run your outbound scenario against an uploaded CSV number table and have each scenario execution pull the next destination.

Call list task pattern with CallList module
1require(Modules.CallList); // Enable CallList methods
2
3VoxEngine.addEventListener(AppEvents.Started, () => {
4  const task = JSON.parse(VoxEngine.customData() || "{}");
5  const destination = task.destination;
6  const callerId = task.callerId;
7
8  if (!destination || !callerId) {
9    CallList.reportError({
10      status: "invalid_task_data",
11      destination: destination || null
12    });
13    VoxEngine.terminate();
14    return;
15  }
16
17  const call = VoxEngine.callPSTN(destination, callerId);
18
19  call.addEventListener(CallEvents.Connected, () => {
20    CallList.reportProgress({
21      status: "connected",
22      destination: destination
23    });
24    // Create/attach your Voice AI connector here.
25  });
26
27  call.addEventListener(CallEvents.Disconnected, () => {
28    CallList.reportResult({
29      status: "completed",
30      destination: destination
31    });
32    VoxEngine.terminate();
33  });
34
35  call.addEventListener(CallEvents.Failed, () => {
36    CallList.reportError({
37      status: "failed",
38      destination: destination
39    });
40    VoxEngine.terminate();
41  });
42});

More information: