> For a complete documentation index, fetch https://docs.voximplant.ai/llms.txt

# Outbound calls

> For the complete documentation index, see [llms.txt](/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](#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`**

```js title="Outbound Voice AI pattern"
VoxEngine.addEventListener(AppEvents.Started, () => {
  // Retrieve information passed when the scenario was triggered
  const { destination, callerId } = JSON.parse(VoxEngine.customData());

  // Choose your call method based on the destination & desired network
  const call = VoxEngine.callPSTN(destination, callerId);
  // const call = VoxEngine.callUser({ username: destination, callerid: callerId });
  // const call = VoxEngine.callSIP(`sip:${destination}@your-sip-domain`, callerId);
  // const call = VoxEngine.callWhatsappUser({ number: destination, callerid: callerId });

  // Handle call events
  call.addEventListener(CallEvents.Disconnected, ()=>VoxEngine.terminate());
  call.addEventListener(CallEvents.Failed, ()=>VoxEngine.terminate());

  // Set up the Voice AI client and media bridging only after the call is connected
  call.addEventListener(CallEvents.Connected, async () => {
    const voiceAIClient = OpenAI.createRealtimeAPIClient({apiKey: "your-key", model: "your-realtime-model"});
    // Bridge media between the call and the Voice AI client so they can speak and hear each other
    VoxEngine.sendMediaBetween(call, voiceAIClient);
  });
});
```

### 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.

Custom script from the control panel demo:

#### 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`**

```bash title="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](/platform/management-api/basics#api-clients),
you will need to [configure an API key](https://manage.voximplant.com/settings/service_accounts?_ga=2.264241679.1608268282.1771956490-551602791.1771956490)
and create an [authorization token](/platform/management-api/authorization).

### 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

### <icon icon="fa-duotone fa-solid fa-link" /> More information:

* [Calls and Sessions concepts](/platform/voxengine/calls-and-sessions)
* [Processing calls in scenarios guide](/getting-started/inbound-vs-outbound/inbound-calls)
* [VoxEngine Call class](/api-reference/voxengine/call)

## 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`**

```js title="Call list task pattern with CallList module"
require(Modules.CallList); // Enable CallList methods

VoxEngine.addEventListener(AppEvents.Started, () => {
  const task = JSON.parse(VoxEngine.customData() || "{}");
  const destination = task.destination;
  const callerId = task.callerId;

  if (!destination || !callerId) {
    CallList.reportError({
      status: "invalid_task_data",
      destination: destination || null
    });
    VoxEngine.terminate();
    return;
  }

  const call = VoxEngine.callPSTN(destination, callerId);

  call.addEventListener(CallEvents.Connected, () => {
    CallList.reportProgress({
      status: "connected",
      destination: destination
    });
    // Create/attach your Voice AI connector here.
  });

  call.addEventListener(CallEvents.Disconnected, () => {
    CallList.reportResult({
      status: "completed",
      destination: destination
    });
    VoxEngine.terminate();
  });

  call.addEventListener(CallEvents.Failed, () => {
    CallList.reportError({
      status: "failed",
      destination: destination
    });
    VoxEngine.terminate();
  });
});
```

### <icon icon="fa-duotone fa-solid fa-link" /> More information:

* [Call lists solution guide](/feature-guides/features/call-lists/automated-dial-lists).
* [Management API: call lists](/api-reference/management-api/reference/call-lists)