Trigger a phone call

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.

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 and Connect telephony.

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.

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.

Start here

Build and operate

Developers

Trigger a phone call

Choose an endpoint

Request fields

Example: published workflow

Interpret the response

​Choose an endpoint

​Request fields

​Example: published workflow

​Interpret the response

Choose an endpoint

Request fields

Example: published workflow

Interpret the response