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

# Trigger a phone call

> Start a published or draft call and follow the result.

Starting a call can dial a real destination and can create model, telephony, and tool usage. During setup, call a number you control and use synthetic context. Do not use `/test/` as a dry-run flag; those routes can place real calls.

## Choose an endpoint

| Method | Path | Definition selected |
| - | - | - |
| POST | `/api/v1/public/agent/workflow/{workflow_uuid}` | Published workflow |
| POST | `/api/v1/public/agent/test/workflow/{workflow_uuid}` | Latest draft, or published if no draft exists |
| POST | `/api/v1/public/agent/{uuid}` | Published API-trigger entry point |
| POST | `/api/v1/public/agent/test/{uuid}` | Draft API-trigger entry point |

Use the workflow route when your integration starts a call from the workflow UUID. Use a trigger route when your workflow defines a specific API-trigger entry point. A dashboard's numeric workflow ID and a run ID are not substitutes for the UUID in a call URL. See [Agents, drafts, and publishing](https://docs.tryopencomputer.com/guides/agents.md).

## Request fields

`phone_number` is required. Optional fields include:

| Field | When to use it |
| - | - |
| `initial_context` | Supply values that the workflow expects, such as a synthetic customer name or case reference. |
| `telephony_configuration_id` | Select a specific ready outbound route for predictable provider selection. |
| `from_phone_number_id` | Select a specific active caller ID when the route supports it. |
| `model_overrides` | Override supported model settings for this request. |

Keep `initial_context` free of credentials and only send data the workflow needs. A selected telephony configuration is checked as given; Athena does not silently switch to a different provider if that configuration is blocked. If you omit it, the server resolves an available outbound configuration. See [Context and variables](https://docs.tryopencomputer.com/guides/context.md) and [Connect telephony](https://docs.tryopencomputer.com/guides/telephony.md).

## Example: published workflow

Use a published agent and an outbound-capable telephony configuration. Test with a number you control, then review the completed run and any configured post-call webhook before using the integration with callers.

```bash theme={null}
curl --fail-with-body \
  "$ATHENA_BASE_URL/api/v1/public/agent/workflow/$ATHENA_WORKFLOW_UUID" \
  -H "X-API-Key: $ATHENA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "phone_number": "<YOUR_CONTROLLED_TEST_NUMBER>",
    "telephony_configuration_id": 123,
    "initial_context": {
      "customer_name": "Sam Example",
      "case_reference": "CASE-EXAMPLE-001"
    }
  }'
```

Set `ATHENA_BASE_URL` to the hosted API origin and provide the key only in a backend or shell secret store. Replace the workflow UUID, test destination, and example configuration ID with values from your own organization. Use the number format required by your carrier.

## Choose a model configuration for one call

To select another compatible named configuration for one request, include a top-level `model_overrides` object:

```json theme={null}
{
  "model_overrides": {
    "model_configuration_uuid": "YOUR_MODEL_CONFIGURATION_UUID"
  }
}
```

This fragment belongs alongside `phone_number` in the call request. Replace the placeholder with a real configuration UUID from your organization. The override is not a value inside `initial_context` and does not change the saved agent. Service-specific overrides must follow `ModelConfigurationOverride` in the API reference. Omit unchanged fields; do not use `null` as a general reset. Verify the run's configuration snapshot after testing. See [Models](https://docs.tryopencomputer.com/guides/models.md).

## Override the opening greeting

On the supported cascade path, a valid `initial_context.greeting_override` can replace the saved Start Call greeting for that call:

```json theme={null}
{
  "initial_context": {
    "customer_name": "Sam Example",
    "greeting_override": {
      "type": "text",
      "text": "Hello {{customer_name}}, I am calling about your appointment."
    }
  }
}
```

For supported library-audio playback, the alternative is `{"type":"audio","recording_id":"YOUR_RECORDING_ID"}`. Use the descriptive recording ID, not an unrelated run ID. An invalid greeting override can fall back to the saved greeting. This mechanism does not establish equivalent override or clip support in the native realtime path; verify your selected runtime. See [Recordings](https://docs.tryopencomputer.com/guides/recordings.md).

## Interpret the response

The response includes a status and run identifiers such as `workflow_run_id` and `workflow_run_name`. A successful initiation response means Athena accepted the start request; it does not establish that the provider connected, the handset rang, or the conversation completed successfully.

Open the run or query its detail using the returned run ID. If the HTTP request times out or its response is lost, inspect for a run before retrying the POST. The call may have already started. For result stages and media, see [Calls, runs, and results](https://docs.tryopencomputer.com/guides/runs.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.