Multilingual outbound calls

Use a multilingual campaign when your application already knows, or an operator has chosen, the recipient's preferred language. OpenPhonex starts every outbound call with one saved hosted agent and one resolved language profile. With Choose before the call, the admitted profile's STT, model, TTS, and language remain fixed for that call. Follow the caller is an explicit opt-in for controlled switching among that call's admitted language profiles.

Neither mode accepts arbitrary stack changes from call_context, extraction results, or a model instruction. A language request cannot add a new voice, provider, or language to an active call.

Configure languages on one agent

Auto multilingual

In the AI agent editor, choose Auto multilingual to let the conversation follow the caller's language. Within Auto, choose All supported languages or restrict the conversation to Selected languages only. Keep a fixed language when you already know which language the caller needs.

The accepted list belongs to the selected listening and voice configuration. It is not the union of every language advertised by every provider. A language must be usable by the complete call configuration, and automatic switching also needs language information from the recognizer. The editor shows the accepted languages and any provider constraints. It does not replace your transcriber or voice to make a larger set work.

Some transcribers require a candidate list. If all compatible languages exceed that provider's simultaneous limit, choose a subset or another compatible transcriber. OpenPhonex does not silently select a smaller list for you.

The opening language determines how the AI agent starts before the caller speaks. Publish the configuration to freeze its accepted languages for future calls. An inventory update or later draft edit does not expand a published or active call. Review new coverage when publishing again.

Language detection may delay the first response or a language switch. Recognition accuracy and voice quality vary by language. Provider-reported support is not a quality guarantee; use the browser test to hear your actual conversation. A fixed latency penalty would be misleading because the model, region, endpointing and connection state all affect the result.

When the caller uses another language

An allowed language can become the active response language after a clear request or supported stable recognition evidence. A request cannot add an unpublished language or change the selected provider or voice.

If a request for an excluded language is understood, the AI agent should explain the available languages in its current language. Speech that the recognizer cannot understand may instead produce an incomplete or incorrect transcript. There is no guarantee that an unsupported language will be identified as unsupported: a candidate-based recognizer can label it as one of the configured languages. A clarification does not establish that the original language was correctly detected.

Shared settings and optional overrides

You do not need to copy the same agent for each language. Choose the languages the agent will offer, its opening language, and one shared voice stack. Identity, instructions, model, tools, knowledge, and business policy stay on the same agent. Use the runnable catalog to choose components that can execute the selected languages:

The catalog is the source of truth for the currently runnable provider, model, voice, language, cost, and credential contracts. Do not hard-code a voice ID from a guide or use a provider credential to infer that a component is runnable.

For a least-privilege REST integration, grant agents:read to read this catalog and agents:write to save the selected agent; neither account nor wallet scope is needed. Each TTS entry's voices list contains the scoped, provider-reported IDs available for that provider/model. The catalog reads a last-good provider cache and never calls a provider while you read it. Use voice_count and voices_truncated before assuming that one provider/model inventory is complete. A partial inventory does not prove an unobserved voice was removed, and a provider-advertised language becomes callable only when the OpenPhonex worker registry declares the complete runnable stack. How OpenPhonex handles provider languages and voices explains the difference between browsing provider-reported voices and admitting a runnable call stack. A cached sample or a manual language approval is not required to configure a language.

Create an agent with POST /v1/agents, select its stack with PATCH /v1/agents/{agent_id}/voice-stack, and read it back with GET /v1/agents/{agent_id}/voice-stack. A voice-stack save publishes the effective language profiles; it is not a workflow publication. Its additional language fields are:

{
  "languages": ["en", "et", "de"],
  "language_profiles": [
    {"locale": "et", "greeting": "Tere! Kuidas saan teid aidata?"}
  ]
}

These are fields of the existing voice-stack request, not a complete stack configuration. The selected shared components must be runnable in every selected language, or you must explicitly choose a compatible per-language override. This example does not imply that every multilingual voice can run every listed language in OpenPhonex.

Optional per-language overrides can supply an exact greeting, voice, or transcriber. Unspecified settings inherit the shared configuration; an override does not copy the whole agent. Changing a shared setting leaves explicit overrides intact. Clearing an override returns it to inheritance.

Omit language_profiles to preserve the saved overrides. When you supply the array, send the complete desired set of sparse overrides; [] clears them. Saving shared voice-stack settings republishes their effective inherited values for future calls, even when the sparse override array is omitted. It does not rewrite the explicit overrides or calls already admitted. Read language_profiles.revision from the voice-stack response and send it as language_profile_revision when saving languages or language_profiles to detect a stale editor instead of overwriting a newer edit. Omitting the revision skips this check for compatibility; it does not protect a stale client from overwriting newer settings. The selected language set must contain 1–32 entries. To remove a language, supply the remaining selected languages and omit any override for the removed language from the replacement profiles array. Keep at least one language, including the opening language; an empty set is invalid.

An exact greeting is optional. Additional languages without a greeting use a model-generated opening in the selected language through the call's normal metered model and voice path. The existing opening-language literal is preserved. Keep required disclosure and consent wording in the appropriate policy; generated wording is not a way to bypass those rules. There is no automatic recommended voice and no fallback to a different voice when a selected provider voice fails.

Test each profile before it joins a live outbound cohort: open the agent's test panel, choose a language from the Published configuration, and start the metered browser test. Profile-based tests use the published version; publish edits before testing them. Unsaved shared draft settings do not overwrite a selected language's greeting or voice. This starts a browser conversation, not an outbound phone call. Use a separate, normally funded phone call to prove the carrier route. Previewing a language in the Voice Library does not add it to the agent's callable profiles. The generated API reference has the exact request and response schemas.

Resolve the language before each call

The API creates one call at a time; it does not provide a batch-language endpoint. Keep the campaign and row-selection logic in your application:

1. An operator chooses a batch default from the published set: for example, en, et, or de for the configuration above.
2. For each eligible row, use its valid language override when present; otherwise use the batch default.
3. Select the saved agent_id and request that published language, then create one governed, idempotent POST /v1/calls request.

Use agent_id as the canonical saved-agent selection. agent_endpoint_id is a backwards-compatible alias for the agent identity, not the language profile. Use the call request's runtime_config.language field to select its language (see the generated API reference for the call schema). A small, non-secret call_context can carry an application-visible label, but metadata there does not select or override a profile.

{
  "agent_id": "agent_multilingual",
  "runtime_config": {"language": "et"},
  "external_reference": "case_456",
  "external_group_reference": "campaign_2026_08",
  "call_context": {
    "preferred_language": "et"
  }
}

Add the normal recipient, source number, policy purpose, and authorization fields from Customer applications, and use a unique Idempotency-Key for each attempt. Do not put current balances, credentials, mutable case history, or a requested voice-stack override in call_context.

The selected language must belong to that agent's published configuration. The voice-stack response's language_profiles.published_version and language_profiles.published_at identify its latest publication. OpenPhonex resolves and validates it before reserving funds or dispatching the call. The estimate and admitted runtime use the same effective components; later edits cannot change an already-admitted call's voice stack. Credential revocation and policy checks still apply. An existing single-language agent does not become multilingual just because an application sends a new locale.

Respect 429 and Retry-After, keep the application queue bounded, and let your application own suppression, correct-person checks, duplicate prevention, cadence, and retry budget. A create response only confirms the governed call request; use signed lifecycle and evidence events to reconcile its outcome.

Optional: follow the caller

Keep Single language per call when each call should stay in its selected language. Existing agents keep that behavior unless you explicitly enable and publish Follow the caller. The opening language determines how the agent starts; it does not force the caller to stay in that language.

Follow mode requires at least two selected languages, one shared transcriber, and listening support for the selected languages together. A transcriber that supports English and German in separate monolingual calls does not necessarily support recognizing both in one conversation. OpenPhonex checks the configured listening mode and complete published profiles before admission. If the combination is unsupported, change the configuration yourself or keep fixed-language mode; OpenPhonex does not select a replacement voice or transcriber for you.

Use the existing voice-stack PATCH to publish the behavior with the language set. The additional behavior field is:

{
  "follow_caller": {"enabled": true, "scope": "selected"}
}

This is a partial request example, not a complete voice configuration. Read the voice-stack response to confirm the saved setting. Set enabled to false to publish fixed-language behavior for future calls. The call request's runtime_config.language still chooses the starting published language; it does not enable follow mode or supply a new profile set.

Use scope: "all" to resolve all compatible languages when publishing:

{
  "follow_caller": {"enabled": true, "scope": "all"}
}

The backend derives the concrete language set from your selected components and effective voices. Read the response's published language list to see the result. If a provider's simultaneous candidate limit prevents that set from working, publication fails with a configuration error; select a smaller set explicitly. An omitted scope retains the older selected-set behavior. Disabling Follow does not erase an existing set of fixed per-call profiles.

Each applicable STT catalog entry exposes language_detection with behavior (automatic or request_only), languages, and max_candidates. These describe the listening model, not the final voice coverage of an AI agent. A null candidate limit does not promise support for every human language. Check the full selected configuration and the published language set. Provider constructor options are not part of this customer API.

A caller can request a configured language directly—for example, “Please speak German” while speaking English. The agent can request a switch only to an admitted language. Automatic switching additionally requires provider language metadata supported by the adapter, and which transcriber you choose decides whether you get it. See Automatic switching availability by language for the current per-transcriber table.

Where automatic switching is available, it takes two consecutive final results that agree on the same language within the selected set. Conflicting or unrecognized signals reset that sequence. OpenPhonex does not guess the language from individual transcript words. Provider detection can still be wrong, so test your actual conversation.

This release supports Follow mode for authenticated browser tests and inbound and outbound phone calls that are not bound to a workflow. An authenticated browser test starts in its selected published language and can follow only within that test's frozen published language set. This guide is not live provider or PSTN media proof; test your actual conversation before relying on it. Workflow Talk, workflow phone pins, and workflow-bound browser sessions reject Follow-enabled configurations before creating a workflow run or dispatching the call; workflow-controlled switching is not supported in this phase.

Switches happen at a controlled turn boundary. The conversation's shared instructions, tools, knowledge, and disclosure requirements remain in force. Publishing or removing a profile later does not change an already-admitted call. A failed switch is not reported as successful and does not trigger an unrequested fallback voice or provider.

After the call's telemetry is imported, Calls shows a bounded language history above the transcript. Applied changes are separate from rejected or failed attempts. The history identifies the active response profile, not the language of every caller utterance; old calls or incomplete evidence are labeled rather than reconstructed. See Post-call results for timing and completeness limits.

The call reserves against its admitted configuration before media starts. Switching does not create a second call or a second independent reservation; native component usage remains metered. Phone calls require purchased funds; browser-only welcome credit cannot fund them. Test the conversation and inspect call evidence before launching a cohort; a successful voice audition alone is not proof that multilingual recognition or a carrier route works.

Self-hosted gateways with issued TTS credentials

If your self-hosted gateway uses platform-issued TTS credentials, select the same TTS provider for every published language. A call with multiple admitted TTS providers is refused before media when the call's project has an issued TTS credential for any of those providers. Active, revoked, expired, and pending credentials all count: revoking or reissuing a key does not remove this multi-provider restriction. Keep one TTS provider across the language profiles.

This restriction does not apply to fully managed cloud calls, or to self-hosted gateways using their own provider keys with no platform-issued TTS credential for an admitted provider. The usual language, provider, and credential qualification checks still apply. See Deployment modes for the difference between the two hosting paths.

Public homepage demos

The anonymous homepage demo can use Follow only for a published, frozen set of platform-managed profiles. It starts in the selected published language and can move only within that same frozen set. BYOK-bound profiles are not eligible, and the demo never selects a replacement provider or voice.

The visitor token contains an opaque session, the starting stack, and (where needed) a public capability revision. It does not contain the agent prompt, other language profiles, credential bindings, or component rates. The demo keeps its anonymous tool restriction: it can end the session and use the controlled language switch, but cannot call customer endpoints or place an outbound call.

Homepage-demo limits and platform-funded reservation remain separate from a workspace wallet. Native usage is segmented server-side against the frozen profile basis; where a provider does not supply a supported native metric, the demo is recorded as unpriced rather than estimated as measured usage.

Route a language retry after the call

Post-call extraction can label a later follow-up without changing an active conversation. Configure a small advisory schema such as:

{
  "enabled": true,
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "language_follow_up": {
        "type": "string",
        "enum": [
          "NONE",
          "LANGUAGE_RETRY_EN",
          "LANGUAGE_RETRY_SI",
          "LANGUAGE_RETRY_TA"
        ]
      }
    }
  }
}

When you receive a signed call.extraction.ready event, fetch the extraction and verify the source evidence and your own policy. If your application allows a retry, submit a later, new POST /v1/calls request with the target published language profile, a fresh idempotency key, and its own authorization. An extraction is advisory: it must not automatically place a call, change a customer record, or switch an in-progress voice stack.

For a fixed-language call, record a language-change request according to your policy and use the same later-call path. Follow mode can switch only among its already-admitted profiles. In either mode, do not edit a shared agent to redirect an active conversation; new publications apply only to future calls.

Evidence and duration

Treat call.completed or call.failed and the ready recording, transcript, and extraction events as the evidence path. Verify every signed delivery, deduplicate by event ID, and retain only what your policy permits. See Post-call results for verification and retrieval.

OpenPhonex does not impose a 90-second hard cap for this flow. The outbound worker defaults to a 1,800-second maximum and a deployment can set a value from 30 through 14,400 seconds. A language retry is still a separate future call, never an automatic in-call mutation.