release: 4.142.0 (#302)

* feat: TELAPPS-5698 document conversation relay API shape

* release: 4.142.0

---------

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.141.0"
+  ".": "4.142.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 1045
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/telnyx/telnyx-2f1a1854d307f38a63ec89d1bf32b02c4de3996e08796c7eda08b98a59f6879a.yml
-openapi_spec_hash: c82ed2a0dc80695f271c3e56d466c4da
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/telnyx/telnyx-65c4b7caac34918e94079d6e5073f448a34a4e39d82d6a2d2c6e280012819f28.yml
+openapi_spec_hash: 504d65873a9ed56a7147361bb5606411
 config_hash: 292f68f00de272998cbaf069c10e2a93

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.142.0 (2026-05-27)
+
+Full Changelog: [v4.141.0...v4.142.0](https://github.com/team-telnyx/telnyx-python/compare/v4.141.0...v4.142.0)
+
+### Features
+
+* TELAPPS-5698 document conversation relay API shape ([4573d36](https://github.com/team-telnyx/telnyx-python/commit/4573d364aee2f30da464b2273d128390fa3a8123))
+
 ## 4.141.0 (2026-05-27)
 
 Full Changelog: [v4.140.0...v4.141.0](https://github.com/team-telnyx/telnyx-python/compare/v4.140.0...v4.141.0)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "telnyx"
-version = "4.141.0"
+version = "4.142.0"
 description = "The official Python library for the telnyx API"
 dynamic = ["readme"]
 license = "MIT"

src/telnyx/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "telnyx"
-__version__ = "4.141.0"  # x-release-please-version
+__version__ = "4.142.0"  # x-release-please-version

src/telnyx/resources/calls/actions.py

@@ -95,6 +95,7 @@ def dial(
         client_state: str | Omit = omit,
         command_id: str | Omit = omit,
         conference_config: call_dial_params.ConferenceConfig | Omit = omit,
+        conversation_relay_config: call_dial_params.ConversationRelayConfig | Omit = omit,
         custom_headers: Iterable[CustomSipHeaderParam] | Omit = omit,
         deepfake_detection: call_dial_params.DeepfakeDetection | Omit = omit,
         dialogflow_config: DialogflowConfigParam | Omit = omit,
@@ -245,6 +246,13 @@ def dial(
 
           conference_config: Optional configuration parameters to dial new participant into a conference.
 
+          conversation_relay_config: Starts a Conversation Relay session automatically when the answered/dialed call
+              is answered. This embedded shape is supported on `answer` and `dial`. It uses
+              public field names (`url`, `dtmf_detection`, `greeting`, `voice`, `language`,
+              etc.) and maps them to the underlying Conversation Relay action. `client_state`,
+              `tts_language`, and `transcription_language` inside this object are ignored; use
+              the parent command's `client_state` and `command_id` fields instead.
+
           custom_headers: Custom headers to be added to the SIP INVITE.
 
           deepfake_detection: Enables deepfake detection on the call. When enabled, audio from the remote
@@ -423,6 +431,7 @@ def dial(
                     "client_state": client_state,
                     "command_id": command_id,
                     "conference_config": conference_config,
+                    "conversation_relay_config": conversation_relay_config,
                     "custom_headers": custom_headers,
                     "deepfake_detection": deepfake_detection,
                     "dialogflow_config": dialogflow_config,
@@ -558,6 +567,7 @@ async def dial(
         client_state: str | Omit = omit,
         command_id: str | Omit = omit,
         conference_config: call_dial_params.ConferenceConfig | Omit = omit,
+        conversation_relay_config: call_dial_params.ConversationRelayConfig | Omit = omit,
         custom_headers: Iterable[CustomSipHeaderParam] | Omit = omit,
         deepfake_detection: call_dial_params.DeepfakeDetection | Omit = omit,
         dialogflow_config: DialogflowConfigParam | Omit = omit,
@@ -708,6 +718,13 @@ async def dial(
 
           conference_config: Optional configuration parameters to dial new participant into a conference.
 
+          conversation_relay_config: Starts a Conversation Relay session automatically when the answered/dialed call
+              is answered. This embedded shape is supported on `answer` and `dial`. It uses
+              public field names (`url`, `dtmf_detection`, `greeting`, `voice`, `language`,
+              etc.) and maps them to the underlying Conversation Relay action. `client_state`,
+              `tts_language`, and `transcription_language` inside this object are ignored; use
+              the parent command's `client_state` and `command_id` fields instead.
+
           custom_headers: Custom headers to be added to the SIP INVITE.
 
           deepfake_detection: Enables deepfake detection on the call. When enabled, audio from the remote
@@ -886,6 +903,7 @@ async def dial(
                     "client_state": client_state,
                     "command_id": command_id,
                     "conference_config": conference_config,
+                    "conversation_relay_config": conversation_relay_config,
                     "custom_headers": custom_headers,
                     "deepfake_detection": deepfake_detection,
                     "dialogflow_config": dialogflow_config,

src/telnyx/resources/calls/calls.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Dict, Union, Iterable
-from typing_extensions import Literal, Required, Annotated, TypedDict
+from typing_extensions import Literal, Required, Annotated, TypeAlias, TypedDict
 
 from .._types import SequenceNotStr
 from .._utils import PropertyInfo
@@ -15,14 +15,29 @@
 from .stream_bidirectional_mode import StreamBidirectionalMode
 from .stream_bidirectional_codec import StreamBidirectionalCodec
 from .call_assistant_request_param import CallAssistantRequestParam
+from .calls.aws_voice_settings_param import AwsVoiceSettingsParam
+from .shared_params.xai_voice_settings import XaiVoiceSettings
 from .stream_bidirectional_target_legs import StreamBidirectionalTargetLegs
+from .calls.telnyx_voice_settings_param import TelnyxVoiceSettingsParam
+from .shared_params.rime_voice_settings import RimeVoiceSettings
+from .shared_params.azure_voice_settings import AzureVoiceSettings
 from .stream_bidirectional_sampling_rate import StreamBidirectionalSamplingRate
+from .shared_params.minimax_voice_settings import MinimaxVoiceSettings
+from .shared_params.resemble_voice_settings import ResembleVoiceSettings
+from .calls.eleven_labs_voice_settings_param import ElevenLabsVoiceSettingsParam
 from .calls.transcription_start_request_param import TranscriptionStartRequestParam
 
 __all__ = [
     "CallDialParams",
     "AnsweringMachineDetectionConfig",
     "ConferenceConfig",
+    "ConversationRelayConfig",
+    "ConversationRelayConfigInterruptionSettings",
+    "ConversationRelayConfigLanguage",
+    "ConversationRelayConfigLanguageVoiceSettings",
+    "ConversationRelayConfigLanguageVoiceSettingsInworldVoiceSettings",
+    "ConversationRelayConfigVoiceSettings",
+    "ConversationRelayConfigVoiceSettingsInworldVoiceSettings",
     "DeepfakeDetection",
     "WebhookRetriesPolicies",
 ]
@@ -134,6 +149,16 @@ class CallDialParams(TypedDict, total=False):
     conference_config: ConferenceConfig
     """Optional configuration parameters to dial new participant into a conference."""
 
+    conversation_relay_config: ConversationRelayConfig
+    """
+    Starts a Conversation Relay session automatically when the answered/dialed call
+    is answered. This embedded shape is supported on `answer` and `dial`. It uses
+    public field names (`url`, `dtmf_detection`, `greeting`, `voice`, `language`,
+    etc.) and maps them to the underlying Conversation Relay action. `client_state`,
+    `tts_language`, and `transcription_language` inside this object are ignored; use
+    the parent command's `client_state` and `command_id` fields instead.
+    """
+
     custom_headers: Iterable[CustomSipHeaderParam]
     """Custom headers to be added to the SIP INVITE."""
 
@@ -542,6 +567,242 @@ class ConferenceConfig(TypedDict, total=False):
     """
 
 
+class ConversationRelayConfigInterruptionSettings(TypedDict, total=False):
+    """Settings for handling caller interruptions during Conversation Relay speech."""
+
+    enable: bool
+    """Legacy boolean form.
+
+    `true` is equivalent to `interruptible=any`; `false` is equivalent to
+    `interruptible=none`.
+    """
+
+    interruptible: Literal["none", "any", "speech", "dtmf"]
+    """Controls when caller input can interrupt assistant speech.
+
+    `any` allows speech or DTMF interruptions; `none` disables interruptions;
+    `speech` allows speech only; `dtmf` allows DTMF only.
+    """
+
+    interruptible_greeting: Literal["none", "any", "speech", "dtmf"]
+    """Controls when caller input can interrupt assistant speech.
+
+    `any` allows speech or DTMF interruptions; `none` disables interruptions;
+    `speech` allows speech only; `dtmf` allows DTMF only.
+    """
+
+    welcome_greeting_interruptible: Literal["none", "any", "speech", "dtmf"]
+    """Controls when caller input can interrupt assistant speech.
+
+    `any` allows speech or DTMF interruptions; `none` disables interruptions;
+    `speech` allows speech only; `dtmf` allows DTMF only.
+    """
+
+
+class ConversationRelayConfigLanguageVoiceSettingsInworldVoiceSettings(TypedDict, total=False):
+    type: Required[Literal["inworld"]]
+    """Voice settings provider type"""
+
+
+ConversationRelayConfigLanguageVoiceSettings: TypeAlias = Union[
+    ElevenLabsVoiceSettingsParam,
+    TelnyxVoiceSettingsParam,
+    AwsVoiceSettingsParam,
+    MinimaxVoiceSettings,
+    AzureVoiceSettings,
+    RimeVoiceSettings,
+    ResembleVoiceSettings,
+    ConversationRelayConfigLanguageVoiceSettingsInworldVoiceSettings,
+    XaiVoiceSettings,
+]
+
+
+class ConversationRelayConfigLanguage(TypedDict, total=False):
+    """Language-specific TTS and transcription settings for Conversation Relay."""
+
+    language: Required[str]
+    """BCP 47 language tag for this language configuration."""
+
+    speech_model: str
+    """Conversation Relay speech model.
+
+    Prefer `transcription_engine_config.transcription_model` when configuring
+    speech-to-text.
+    """
+
+    transcription_engine: Literal[
+        "Google", "Telnyx", "Deepgram", "Azure", "xAI", "AssemblyAI", "Speechmatics", "Soniox", "A", "B"
+    ]
+    """Engine to use for speech recognition.
+
+    Legacy values `A` - `Google`, `B` - `Telnyx` are supported for backward
+    compatibility. When provided in a Conversation Relay language entry, Telnyx
+    derives `transcription_provider` and `speech_model` for that language.
+    """
+
+    transcription_engine_config: Dict[str, object]
+    """Engine-specific transcription settings for Conversation Relay.
+
+    This accepts the same provider-specific options used by the Call Transcription
+    Start command, such as `transcription_model`, without requiring the engine
+    discriminator to be repeated inside this object.
+    """
+
+    transcription_provider: str
+    """Conversation Relay transcription provider name.
+
+    Prefer `transcription_engine` when configuring speech-to-text.
+    """
+
+    tts_provider: str
+    """Text-to-speech provider for this language.
+
+    If omitted and `voice` is provided, Telnyx derives the provider from the voice
+    identifier.
+    """
+
+    voice: str
+    """Voice identifier for this language."""
+
+    voice_settings: ConversationRelayConfigLanguageVoiceSettings
+    """The settings associated with the voice selected"""
+
+
+class ConversationRelayConfigVoiceSettingsInworldVoiceSettings(TypedDict, total=False):
+    type: Required[Literal["inworld"]]
+    """Voice settings provider type"""
+
+
+ConversationRelayConfigVoiceSettings: TypeAlias = Union[
+    ElevenLabsVoiceSettingsParam,
+    TelnyxVoiceSettingsParam,
+    AwsVoiceSettingsParam,
+    MinimaxVoiceSettings,
+    AzureVoiceSettings,
+    RimeVoiceSettings,
+    ResembleVoiceSettings,
+    ConversationRelayConfigVoiceSettingsInworldVoiceSettings,
+    XaiVoiceSettings,
+]
+
+
+class ConversationRelayConfig(TypedDict, total=False):
+    """
+    Starts a Conversation Relay session automatically when the answered/dialed call is answered. This embedded shape is supported on `answer` and `dial`. It uses public field names (`url`, `dtmf_detection`, `greeting`, `voice`, `language`, etc.) and maps them to the underlying Conversation Relay action. `client_state`, `tts_language`, and `transcription_language` inside this object are ignored; use the parent command's `client_state` and `command_id` fields instead.
+    """
+
+    url: Required[str]
+    """WebSocket URL for your Conversation Relay server.
+
+    Must start with `ws://` or `wss://`.
+    """
+
+    custom_parameters: Dict[str, object]
+    """
+    Custom key-value parameters forwarded to the relay session as assistant dynamic
+    variables.
+    """
+
+    dtmf_detection: bool
+    """Enable DTMF detection for the relay session."""
+
+    greeting: str
+    """Text played when the relay session starts."""
+
+    interruptible: Literal["none", "any", "speech", "dtmf"]
+    """Controls when caller input can interrupt assistant speech.
+
+    `any` allows speech or DTMF interruptions; `none` disables interruptions;
+    `speech` allows speech only; `dtmf` allows DTMF only.
+    """
+
+    interruptible_greeting: Literal["none", "any", "speech", "dtmf"]
+    """Controls when caller input can interrupt assistant speech.
+
+    `any` allows speech or DTMF interruptions; `none` disables interruptions;
+    `speech` allows speech only; `dtmf` allows DTMF only.
+    """
+
+    interruption_settings: ConversationRelayConfigInterruptionSettings
+    """Settings for handling caller interruptions during Conversation Relay speech."""
+
+    language: str
+    """Default language for both text-to-speech and speech recognition."""
+
+    languages: Iterable[ConversationRelayConfigLanguage]
+    """Per-language TTS and transcription settings."""
+
+    provider: str
+    """Structured voice provider.
+
+    Must be supplied together with `structured_provider`.
+    """
+
+    structured_provider: Dict[str, object]
+    """Provider-specific structured voice settings.
+
+    Must be supplied together with `provider`; Telnyx sends the value as the nested
+    provider configuration for Conversation Relay.
+    """
+
+    transcription_engine: Literal[
+        "Google", "Telnyx", "Deepgram", "Azure", "xAI", "AssemblyAI", "Speechmatics", "Soniox", "A", "B"
+    ]
+    """Engine to use for speech recognition.
+
+    Legacy values `A` - `Google`, `B` - `Telnyx` are supported for backward
+    compatibility. For Conversation Relay, use this field with
+    `transcription_engine_config`; the `transcription` object is not supported.
+    """
+
+    transcription_engine_config: Dict[str, object]
+    """Engine-specific transcription settings for Conversation Relay.
+
+    This accepts the same provider-specific options used by the Call Transcription
+    Start command, such as `transcription_model`, without requiring the engine
+    discriminator to be repeated inside this object.
+    """
+
+    tts_provider: str
+    """Text-to-speech provider.
+
+    If omitted, Telnyx derives it from `voice` or `provider`.
+    """
+
+    voice: str
+    """The voice to be used by the voice assistant.
+
+    Currently we support ElevenLabs, Telnyx and AWS voices.
+
+    **Supported Providers:**
+
+    - **AWS:** Use `AWS.Polly.<VoiceId>` (e.g., `AWS.Polly.Joanna`). For neural
+      voices, which provide more realistic, human-like speech, append `-Neural` to
+      the `VoiceId` (e.g., `AWS.Polly.Joanna-Neural`). Check the
+      [available voices](https://docs.aws.amazon.com/polly/latest/dg/available-voices.html)
+      for compatibility.
+    - **Azure:** Use `Azure.<VoiceId>. (e.g. Azure.en-CA-ClaraNeural,
+      Azure.en-CA-LiamNeural, Azure.en-US-BrianMultilingualNeural,
+      Azure.en-US-Ava:DragonHDLatestNeural. For a complete list of voices, go to
+      [Azure Voice Gallery](https://speech.microsoft.com/portal/voicegallery).)
+    - **ElevenLabs:** Use `ElevenLabs.<ModelId>.<VoiceId>` (e.g.,
+      `ElevenLabs.BaseModel.John`). The `ModelId` part is optional. To use
+      ElevenLabs, you must provide your ElevenLabs API key as an integration secret
+      under `"voice_settings": {"api_key_ref": "<secret_id>"}`. See
+      [integration secrets documentation](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret)
+      for details. Check
+      [available voices](https://elevenlabs.io/docs/api-reference/get-voices).
+    - **Telnyx:** Use `Telnyx.<model_id>.<voice_id>`
+    - **Inworld:** Use `Inworld.<ModelId>.<VoiceId>` (e.g., `Inworld.Mini.Loretta`,
+      `Inworld.Max.Oliver`). Supported models: `Mini`, `Max`.
+    - **xAI:** Use `xAI.<VoiceId>` (e.g., `xAI.eve`). Available voices: `eve`,
+      `ara`, `rex`, `sal`, `leo`.
+    """
+
+    voice_settings: ConversationRelayConfigVoiceSettings
+    """The settings associated with the voice selected"""
+
+
 class DeepfakeDetection(TypedDict, total=False):
     """Enables deepfake detection on the call.