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

# API Trigger

> Trigger outbound calls from external systems like n8n, Zapier, or your own backend

The API Trigger node lets you initiate outbound calls to your voice agent programmatically. When you add an API Trigger node to your workflow, Voice AiLunaPro generates a unique endpoint URL that external systems can call to start a conversation.

This is useful when you want to trigger calls from your own backend, a CRM, or workflow tools like n8n and Zapier.

## Prerequisites

* A configured [telephony provider](/integrations/telephony/overview) — outbound calls will fail without one
* An [API key](/configurations/api-keys) for authentication

## Finding your trigger URL

When you add an API Trigger node to your workflow, AiLunaPro assigns it a unique UUID. The trigger node exposes two URLs that share this UUID:

* A **production URL** for the published workflow
* A **test URL** for the latest draft

You can copy either URL from the trigger node's settings dialog.

```text theme={null}
POST https://voice-api.ailunapro.com/api/v1/public/agent/{uuid}        # Production
POST https://voice-api.ailunapro.com/api/v1/public/agent/test/{uuid}   # Test
```

### Test vs production

| Mode | URL | Runs |
| - | - | - |
| Production | `/api/v1/public/agent/{uuid}` | The published version of the agent. |
| Test | `/api/v1/public/agent/test/{uuid}` | The latest draft. Falls back to the published version if no draft exists. |

Use the test URL while iterating on changes so production traffic continues to hit the published version.

The production URL only executes a **published** workflow. If you update the workflow but do not publish it, the production trigger will continue to run the older published version.

Once you publish your draft, both URLs run the same definition.

<Warning>
  A common pitfall is editing the workflow, saving the draft, and then calling the production trigger URL expecting the new behavior. That will not work until you publish the workflow. Use the test URL to verify draft changes before publishing.
</Warning>

The request body, headers, and response shape are identical for both URLs.

## Making a request

Authenticate by passing your API key in the `X-API-Key` header. The request body requires a `phone_number` and accepts optional `initial_context`, `telephony_configuration_id`, `from_phone_number_id`, and `model_overrides` fields.

<CodeGroup>
  ```bash Production URL theme={null}
  curl -X POST https://voice-api.ailunapro.com/api/v1/public/agent/{uuid} \
    -H "Content-Type: application/json" \
    -H "X-API-Key: dg_your_api_key" \
    -d '{
      "phone_number": "+14155550100",
      "initial_context": {
        "customer_name": "Jane",
        "appointment_date": "March 15"
      }
    }'
  ```

  ```bash Test URL theme={null}
  curl -X POST https://voice-api.ailunapro.com/api/v1/public/agent/test/{uuid} \
    -H "Content-Type: application/json" \
    -H "X-API-Key: dg_your_api_key" \
    -d '{
      "phone_number": "+14155550100",
      "initial_context": {
        "customer_name": "Jane",
        "appointment_date": "March 15"
      }
    }'
  ```
</CodeGroup>

Use the test URL when you want to verify draft changes before publishing.

### Response

A successful request returns a `workflow_run_id` that you can use to [retrieve run details](/api-reference/runs/get-run), recordings, and transcripts.

```json theme={null}
{
  "status": "initiated",
  "workflow_run_id": 12345,
  "workflow_run_name": "WR-API-7823"
}
```

### Error responses

| Status | Cause |
| - | - |
| `400` | Telephony provider not configured, or call failed to initiate |
| `401` | Missing or invalid API key |
| `403` | API key does not have access to this agent |
| `404` | Trigger not found, inactive, or a referenced model configuration or provider connection is unavailable in your organization |
| `422` | Invalid or incompatible model overrides |

## Initial context

`initial_context` is a JSON object containing any information you want your voice agent to access during the call. You can reference these values in your prompts using [template variables](/voice-agent/template-variables) — values enclosed in `{{` and `}}`.

For example, if your request includes:

```json theme={null}
{
    "phone_number": "+14155550100",
    "initial_context": {
        "user": {
            "name": "John"
        }
    }
}
```

You can reference the user's name in your agent prompt as `{{user.name}}` — in Agent prompts, `initial_context` fields are referenced directly by name (not prefixed with `initial_context.`). See [template variables](/voice-agent/template-variables) for the exact syntax in prompts versus webhook payloads.

See [Context & Variables](/core-concepts/context-and-variables) for more on how data flows through a call.

### Override the greeting for one call

Pass `greeting_override` inside `initial_context` to replace the Start Call node's saved greeting for one API-triggered call. A valid override takes precedence over the saved greeting. If you omit it, AiLunaPro uses the saved greeting; if neither exists, the Start node follows its normal no-greeting behavior.

For a text greeting:

```json theme={null}
{
  "phone_number": "+14155550100",
  "initial_context": {
    "greeting_override": {
      "type": "text",
      "text": "Hi, please confirm account {{account_id}}."
    }
  }
}
```

For a pre-recorded greeting, pass the recording's string ID from the Recordings page:

```json theme={null}
{
  "phone_number": "+14155550100",
  "initial_context": {
    "greeting_override": {
      "type": "audio",
      "recording_id": "callback-welcome"
    }
  }
}
```

AiLunaPro renders a text override after Pre-Call Data Fetch completes, so the override can reference variables returned by the fetch. The override follows the same playback restrictions as a saved greeting. In particular, static text greetings are not spoken by realtime speech-to-speech models; use an audio override for those configurations.

Pre-Call Data Fetch can also return `greeting_override`. Because fetched context is applied after trigger context, a valid fetched override replaces one supplied by the trigger.

## Choosing models for one call

Create provider connections and named model configurations on the **Model Configurations** page. Copy their UUIDs to select them in `model_overrides`. Referenced configurations and connections must be active and belong to the trigger's organization.

This request selects a saved setup and customizes its LLM temperature and TTS voice:

```json theme={null}
{
  "phone_number": "+14155550100",
  "model_overrides": {
    "model_configuration_uuid": "11111111-1111-4111-8111-111111111111",
    "llm": {
      "settings": {
        "temperature": 0.2
      }
    },
    "tts": {
      "settings": {
        "voice": "default"
      }
    }
  }
}
```

Replace the example UUID with your configuration UUID and choose a voice supported by its TTS provider. Omit `model_configuration_uuid` to customize the setup already selected by the workflow.

To select another connection for one service, provide that service's `provider_connection_uuid`:

```json theme={null}
{
  "phone_number": "+14155550100",
  "model_overrides": {
    "llm": {
      "provider_connection_uuid": "22222222-2222-4222-8222-222222222222",
      "settings": {
        "model": "gpt-4.1-mini",
        "temperature": 0.2
      }
    }
  }
}
```

This example assumes the selected LLM connection uses OpenAI. Keep credentials, endpoints, cloud project IDs, and regions in the provider connection; they cannot be supplied through `settings`.

The order of precedence is **organization default → workflow override → API override → pre-call data fetch override**:

* Selecting a named configuration starts from that entire saved setup, replacing earlier model choices and parameter changes. Explicit settings in the same override apply afterward.
* Selecting another connection for the same provider preserves that service's parameters. Selecting a different provider starts that service from the new provider's defaults and your explicit settings.
* Settings-only overrides change individual fields. Omitted fields inherit; `temperature: null` requests the provider default. `embeddings: null` disables embeddings only when the workflow does not require indexed-document retrieval.
* Overrides affect this run. They do not edit saved configurations or workflows.

For realtime mode, the setup must include a realtime connection and a separate text LLM. Pipeline mode requires LLM, STT, and TTS. Multiple AiLunaPro connections may be saved, but the active AiLunaPro services within one run must share a service key.

AiLunaPro resolves the organization, workflow, and API-trigger overrides, validates the setup locally, and checks billing and quota **before dialing**. Invalid settings or references stop the call; validation does not contact model providers to test credentials. The pre-call data fetch runs once the call connects and may still adjust the agent's LLM, LLM fallback, and TTS. Each run retains its selected model settings and connection references. Credentials are loaded from those connections when a runtime starts, so rotating credentials can affect a prepared call, a later text-chat turn, or post-call analysis.

Keep `model_overrides` outside `initial_context`. See [Pre-Call Data Fetch](/voice-agent/pre-call-data-fetch) for selecting models from your own endpoint.

## Choosing a telephony configuration and caller ID

By default, calls are placed through your organization's default outbound [telephony configuration](/integrations/telephony/overview). To route a specific call through a different configuration — for example, to dial out from a regional number — pass `telephony_configuration_id` in the request body.

```json theme={null}
{
  "phone_number": "+14155550100",
  "telephony_configuration_id": 42
}
```

The id is shown on each row in **Telephony configurations** (`https://voice.ailunapro.com/telephony-configurations`). The configuration must belong to the same organization as the API Trigger; otherwise the request returns `404`.

To use a specific caller ID from that configuration, also pass `from_phone_number_id`:

```json theme={null}
{
  "phone_number": "+14155550100",
  "telephony_configuration_id": 42,
  "from_phone_number_id": 84
}
```

`from_phone_number_id` is the ID of a phone number configured under the selected telephony configuration. The number must be active and belong to that configuration; otherwise the request returns `400`. You can retrieve configured numbers with [List phone numbers](/api-reference/telephony-configs/phone-numbers/list).

<Note>
  For full endpoint details including all parameters and response fields, see the [API reference](/api-reference/runs/trigger).
</Note>


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