Skip to main content
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.