> ## 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](/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](/guides/context.md) and [Connect telephony](/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.

## 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](/guides/runs.md).


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