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

# Trigger Voice Call

> Places a single outbound voice call.

Places a single outbound voice call. Display name **"Trigger Voice Call"**. Off by default — the agent builder must add it explicitly.

Starts the call and returns immediately with a call id; it does not wait for the call to finish. Pair with `await_webhook` to resume once the call ends (match on `message.call.id` in the callback body).

## Authentication and enablement

Voice calling is a single Nanonets-wide platform capability, not a per-workspace integration — there is no customer-facing connection step. The agent builder can always see and add this tool. Whether a call actually runs depends on the platform's voice-call provider key being configured — without it, `trigger_voice_call` is not executable and calls fail at runtime.

The agent builder configures, per tool instance (hidden from the model):

* `squad_id` or `assistant_id` — which voice squad or assistant this agent calls through. Set exactly one; setting both or neither is a configuration error.
* `phone_number_id` — which number to dial from.
* `dial_override` — a safety switch. While set, **every** call redirects here regardless of `customer_number`, so a real party can never be dialled by accident during testing. Clear it only when payer/customer calls are deliberately cleared to run.

## Inputs

* `customer_number` (required): the number to call, in E.164 format.
* `variable_values` (optional object): template variables the voice assistant references during the call.
* `metadata` (optional object): free-form metadata attached to the call for tracing.
* `system_prompt_override` (optional string): replace the assistant's configured system prompt for this call only. Leave unset to use the assistant's own prompt. Requires `model_provider_override` and `model_name_override` to also be set — the call provider's override API needs an explicit provider/model whenever the prompt is overridden.
* `first_message_override` (optional string): replace the assistant's first spoken line for this call only.
* `model_provider_override` / `model_name_override` (optional strings, required together with `system_prompt_override`): the LLM provider/model to use for this call only (e.g. `"openai"` / `"gpt-4o"`).

## Output

`{ok, call_id, status, dialled, intended_number, test_mode, listen_url, control_url, variables_sent, blank_values, warnings}`.

`blank_values` lists `variable_values` keys sent with an empty/blank string — it cannot detect a variable the agent omitted entirely.

`dialled` is the number actually called (the override, if `dial_override` was set); `intended_number` is always the real `customer_number`, whether or not it was used.

## Limits and side effects

* Places exactly one call per invocation. Never call this a second time for the same outcome — a retry dials the number again.
* Carries patient PHI in call audio and `variable_values`; see `scripts/hipaa-providers.txt`.

## Expected errors

* Missing `squad_id`/`phone_number_id` (tool not configured), missing `customer_number`, or `system_prompt_override` set without both `model_provider_override` and `model_name_override` — safe to retry, no call was placed.
* Any failure once the call request has been sent (rejected request, timeout, malformed response) is reported as `ok: false` in the tool's own output, **never** as a platform tool error — a platform-level retry after an ambiguous outcome could dial the number twice. The agent must read `ok`/`failure_reason` in the response rather than relying on step failure to detect a problem.