> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound vs Outbound

> Understanding simulation testing directions

## Overview

When running simulations in Roark, there are two fundamental testing directions based on who initiates the call. This affects how your tests execute, what you can test, and how you configure your simulations.

<Note>
  You don't choose a direction when building a run — it's derived from the
  agent endpoints you select. Each endpoint has a direction (Inbound, Outbound,
  or "In + out"), and a run is outbound only when every selected endpoint is
  outgoing-only. Otherwise the run executes inbound.
</Note>

***

## Inbound Testing

In inbound testing, **Roark calls your agent** to simulate incoming customer calls.

### How It Works

1. You select an agent endpoint that accepts incoming calls (direction Inbound or "In + out")
2. Roark initiates calls to your agent
3. The simulated customer (persona) interacts with your agent
4. Your agent responds as it would to a real incoming call

### Characteristics

* **Immediate execution** - Tests run as soon as triggered
* **Multiple iterations** - Can repeat the same test case up to 100 times
* **High control** - Roark controls timing and execution
* **Synchronous results** - Get results immediately after completion

### Use Cases

Perfect for testing:

* **Customer service lines** - Support hotlines, help desks
* **IVR systems** - Automated phone menus
* **Receptionist agents** - Virtual assistants answering calls
* **Emergency response** - Crisis hotlines, urgent support
* **Inbound sales** - Agents handling incoming inquiries

### Configuration

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
Endpoint direction: Inbound (or "In + out")
Agent Endpoint: +1-555-0100 or sip:agent@domain.com
Iterations: 1-100 (configurable)
Concurrency: Default 5 parallel calls, capped by your account quota
```

***

## Outbound Testing

In outbound testing, **your agent calls Roark** to simulate outbound campaigns. Roark runs a plan outbound when every selected agent endpoint is outgoing-only.

### How It Works

1. Roark provisions a phone number for each test case in your run
2. Your agent can start the call either by exposing an outbound call endpoint that Roark will trigger automatically, or by directly calling the provisioned number shown on the run detail page.
3. Roark answers as the simulated customer (persona)
4. Your agent conducts the outbound call against the customer flow you attached

#### Triggering an outbound call

In an outbound simulation, your agent is responsible for starting the simulated call. This can be done in two ways:

#### HTTP Endpoint (Suggested)

By setting up an outbound call HTTP request, Roark can automatically start your outbound tests for you - giving you the benefits of scheduling and concurrency control.

1. Set up an HTTP request on the agent endpoint that will be used in the simulation
2. Whenever a simulation is started for this agent endpoint, Roark will make the specified HTTP request passing in the provisioned phone number as `{{phoneNumberToDial}}`.
3. This HTTP request is expected to trigger your agent to start an outbound call by dialing `{{phoneNumberToDial}}`.

This automates the workflow of running outbound tests - Roark will handle generating the number and calling your endpoint, and your system simply initiates the call.

<Note>
  Template variables such as `{{ phoneNumberToDial }}` can be used in the `URL`,
  `body`, and `headers`.
</Note>

#### Provider Examples

Below are minimal example configurations for common voice AI providers. The `{{phoneNumberToDial}}` template variable will be replaced with the provisioned Roark number at runtime.

<Tabs>
  <Tab title="VAPI">
    **URL:**

    ```
    POST https://api.vapi.ai/call
    ```

    **Headers:**

    ```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    {
      "Authorization": "Bearer <YOUR_VAPI_API_KEY>",
      "Content-Type": "application/json"
    }
    ```

    **Body:**

    ```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    {
      "customer": {
        "number": "{{phoneNumberToDial}}"
      },
      "assistantId": "<YOUR_VAPI_ASSISTANT_ID>",
      "phoneNumberId": "<YOUR_VAPI_PHONE_NUMBER_ID>"
    }
    ```

    See the [VAPI API documentation](https://docs.vapi.ai/api-reference/calls/create-call) for additional options.
  </Tab>

  <Tab title="Retell">
    **URL:**

    ```
    POST https://api.retellai.com/v2/create-phone-call
    ```

    **Headers:**

    ```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    {
      "Authorization": "Bearer <YOUR_RETELL_API_KEY>",
      "Content-Type": "application/json"
    }
    ```

    **Body:**

    ```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    {
      "from_number": "<YOUR_RETELL_PHONE_NUMBER>",
      "to_number": "{{phoneNumberToDial}}",
      "override_agent_id": "<YOUR_RETELL_AGENT_ID>"
    }
    ```

    See the [Retell API documentation](https://docs.retellai.com/api-references/create-phone-call) for additional options like `metadata`, `retell_llm_dynamic_variables`, and agent overrides.
  </Tab>

  <Tab title="ElevenLabs">
    **URL:**

    ```
    POST https://api.elevenlabs.io/v1/convai/batch-calling/submit
    ```

    **Headers:**

    ```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    {
      "xi-api-key": "<YOUR_ELEVENLABS_API_KEY>",
      "Content-Type": "application/json"
    }
    ```

    **Body:**

    ```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    {
      "call_name": "<YOUR_BATCH_CALL_NAME>",
      "agent_id": "<YOUR_ELEVENLABS_AGENT_ID>",
      "recipients": [
        {
          "phone_number": "{{phoneNumberToDial}}"
        }
      ]
    }
    ```

    See the [ElevenLabs API documentation](https://elevenlabs.io/docs/api-reference/batch-calling/create) for additional options.
  </Tab>
</Tabs>

#### Manual Calls

If an HTTP request is not configured, Roark displays the provisioned phone number for each test case on the run detail page while the call shows as "Waiting for call". You can then manually trigger your agent to dial that number.

Alternatively, you can trigger calls programmatically using our APIs. This is useful when you need full control over when simulations run within your own orchestration logic.

<Steps>
  <Step title="Trigger the simulation run plan">
    Start a simulation by calling the [Run a Simulation Plan](/api-reference/simulation-run-plan-job/run-a-simulation-plan) endpoint with your run plan ID.

    ```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    POST /v1/simulation/plan/{planId}/job
    ```

    This returns a `simulationRunPlanJobId` for tracking the executed simulation run plan job.
  </Step>

  <Step title="Fetch the simulation run plan job">
    Retrieve the job details using the [Get Simulation Plan Job](/api-reference/simulation-run-plan-job/get-simulation-plan-job) endpoint.

    ```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    GET /v1/simulation/plan/job/{jobId}
    ```

    The response includes a list of individual simulation jobs.
  </Step>

  <Step title="Dial pending jobs">
    Look for jobs with `status: "WAITING_FOR_OUTBOUND_CALL"` (shown as "Waiting for call" in the dashboard). For each of these, have your agent dial the `roarkPhoneNumber` provided in the job object to start that simulation.
  </Step>

  <Step title="Repeat for queued jobs">
    Depending on your run settings, some jobs may be queued while others are in progress. Monitor when each call completes, then repeat steps 2–3 until the [Get Simulation Plan Job](/api-reference/simulation-run-plan-job/get-simulation-plan-job) endpoint returns `status: "COMPLETED"`.
  </Step>
</Steps>

<Tip>
  While the programmatic approach offers flexibility, we recommend using HTTP
  requests instead. Roark will automatically trigger calls at the right time,
  handling queued simulations and concurrency limits for you.
</Tip>

<Warning>
  For both HTTP requests and manual calls, Roark expects the outbound call to be
  made by the number set in your agent endpoint. Calls made to the provisioned
  number from numbers other than the one defined in your agent endpoint will be
  ignored.
</Warning>

### Characteristics

* **Asynchronous execution** - Tests wait for your agent to call
* **Single iteration** - Outbound runs are always one iteration per test case
* **Agent-controlled timing** - Your system decides when to call
* **Waiting state** - Test cases show "Waiting for call" until your agent dials

### Use Cases

Perfect for testing:

* **Sales campaigns** - Cold calling, lead follow-up
* **Appointment reminders** - Medical, service appointments
* **Survey calls** - Customer satisfaction, market research
* **Collections** - Payment reminders, account management
* **Notifications** - Alert calls, status updates

### Configuration

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
Endpoint direction: Outbound (all selected endpoints outgoing-only)
Phone Numbers: Provisioned by Roark
Iterations: 1 (fixed)
Timeout: Configurable (default 24 hours)
```

## Key Differences

| Aspect             | Inbound                         | Outbound           |
| :----------------- | :------------------------------ | :----------------- |
| **Who calls who**  | Roark → Your Agent              | Your Agent → Roark |
| **Execution**      | Immediate                       | When agent calls   |
| **Iterations**     | Multiple supported (up to 100)  | One per test case  |
| **Use case**       | Customer service                | Sales/outreach     |
| **Timing control** | Roark controls                  | You control        |
| **Phone numbers**  | Use your existing               | Roark provisions   |
| **Concurrency**    | Default 5, capped by your quota | Limited by numbers |
| **Results**        | Immediate                       | After agent calls  |

***

## Choosing the Right Direction

Since direction follows from your agent endpoints, "choosing" a direction means selecting the right endpoints for the behavior you want to test.

### Test Inbound When:

* Testing customer service flows
* You need immediate results
* Running high-volume tests
* Testing response to incoming requests
* Validating IVR flows

### Test Outbound When:

* Testing sales or marketing campaigns
* Your agent initiates contact
* Testing dialer integrations
* Validating outreach scripts
* Testing follow-up workflows

***

## Technical Considerations

### Inbound Testing

* Ensure your agent can handle concurrent calls
* Configure appropriate rate limits
* Test your agent's scaling capabilities
* Monitor response times under load

### Outbound Testing

* Plan for phone number provisioning time
* Set appropriate timeouts for pending tests
* Configure your dialer to call Roark numbers
* Handle failed call attempts gracefully

***

## Best Practices

<AccordionGroup>
  <Accordion title="Start with Inbound">
    Begin with inbound testing for immediate feedback before moving to outbound
  </Accordion>

  <Accordion title="Match Production Patterns">
    Choose endpoints that match how your agent operates in production
  </Accordion>

  <Accordion title="Test Both Directions">
    If your agent handles both, test both directions for complete coverage
  </Accordion>

  <Accordion title="Monitor Phone Number Usage">
    For outbound, track which numbers have been called to avoid duplicates
  </Accordion>

  <Accordion title="Set Realistic Timeouts">
    Configure appropriate timeouts for outbound tests based on your calling
    patterns
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Run Plans" icon="list-check" href="/documentation/simulation-testing/run-plans">
    Build test suites around your agent endpoints
  </Card>

  <Card title="Configure Personas" icon="users" href="/documentation/simulation-testing/personas">
    Set up customer profiles for testing
  </Card>

  <Card title="Running Simulations" icon="play" href="/documentation/simulation-testing/running-simulations">
    Execute your inbound or outbound tests
  </Card>

  <Card title="Customer Flows" icon="git-branch" href="/documentation/simulation-testing/customer-flows">
    Author the conversations your simulations follow
  </Card>
</CardGroup>