telnyx 7.24.0 → 7.26.0

package/src/resources/ai/assistants/assistants.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../../../core/resource';
 import * as AssistantsAPI from './assistants';
 import * as Shared from '../../shared';
+import * as AvatarsAPI from '../avatars';
 import * as ChatAPI from '../chat';
 import * as ToolsAPI from '../tools';
 import * as CanaryDeploysAPI from './canary-deploys';
@@ -18,6 +19,13 @@ import {
   RuleOutput,
   Serve,
 } from './canary-deploys';
+import * as DeletedAPI from './deleted';
+import {
+  Deleted,
+  DeletedAssistant,
+  DeletedAssistantsDefaultFlatPagination,
+  DeletedListParams,
+} from './deleted';
 import * as InstructionsAPI from './instructions';
 import { InstructionEnhanceParams, InstructionEnhanceResponse, Instructions } from './instructions';
 import * as ScheduledEventsAPI from './scheduled-events';
@@ -84,6 +92,7 @@ export class Assistants extends APIResource {
   versions: VersionsAPI.Versions = new VersionsAPI.Versions(this._client);
   tags: TagsAPI.Tags = new TagsAPI.Tags(this._client);
   instructions: InstructionsAPI.Instructions = new InstructionsAPI.Instructions(this._client);
+  deleted: DeletedAPI.Deleted = new DeletedAPI.Deleted(this._client);
 
   /**
    * Retrieve a list of all AI Assistants configured by the user.
@@ -151,6 +160,20 @@ export class Assistants extends APIResource {
   /**
    * Delete an AI Assistant by `assistant_id`.
    *
+   * By default this performs a soft delete: the assistant moves to the Recently
+   * Deleted list and stays restorable for 30 days, after which it is permanently
+   * deleted automatically. The assistant's versions and TeXML application are
+   * preserved during the retention window.
+   *
+   * Pass `hard_delete=true` to skip the retention window and permanently delete the
+   * assistant immediately. A hard delete erases the assistant and all of its
+   * versions, and deletes its TeXML application unless phone numbers are still
+   * assigned to it. It does not delete conversations, recordings, shared tools the
+   * assistant referenced, or knowledge-base embeddings.
+   *
+   * Deletion fails with `400` if other assistants reference this one through a
+   * handoff tool or a conversation-flow edge — remove those references first.
+   *
    * @example
    * ```ts
    * const assistant = await client.ai.assistants.delete(
@@ -158,8 +181,13 @@ export class Assistants extends APIResource {
    * );
    * ```
    */
-  delete(assistantID: string, options?: RequestOptions): APIPromise<AssistantDeleteResponse> {
-    return this._client.delete(path`/ai/assistants/${assistantID}`, options);
+  delete(
+    assistantID: string,
+    params: AssistantDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AssistantDeleteResponse> {
+    const { hard_delete } = params ?? {};
+    return this._client.delete(path`/ai/assistants/${assistantID}`, { query: { hard_delete }, ...options });
   }
 
   /**
@@ -306,6 +334,70 @@ export class Assistants extends APIResource {
       ]),
     });
   }
+
+  /**
+   * Start a WhatsApp conversation with a customer from the business side. This
+   * endpoint:
+   *
+   * 1. Validates that `from` is a WhatsApp number on your account whose messaging
+   *    profile has this assistant configured
+   * 2. Creates a new `whatsapp_chat` conversation with the provided metadata
+   * 3. Asks the assistant to pick one of its approved WhatsApp templates and fill
+   *    its variables from `content`
+   * 4. Sends the template from `from` to `to`
+   * 5. Returns the conversation ID and the message ID
+   *
+   * When the customer replies, the reply is routed to the same conversation and the
+   * assistant answers within the 24-hour customer service window. The assistant
+   * needs a `whatsapp_template` tool with at least one approved template, data
+   * retention enabled and PII redaction disabled.
+   *
+   * @example
+   * ```ts
+   * const response = await client.ai.assistants.whatsapp(
+   *   'assistant_id',
+   *   {
+   *     content:
+   *       'Send the login verification code 482913 to the customer.',
+   *     from: '+13125550001',
+   *     to: '+13125550002',
+   *     conversation_metadata: { order_id: 'A1' },
+   *   },
+   * );
+   * ```
+   */
+  whatsapp(
+    assistantID: string,
+    params: AssistantWhatsappParams,
+    options?: RequestOptions,
+  ): APIPromise<AssistantWhatsappResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post(path`/ai/assistants/${assistantID}/chat/whatsapp`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Restore a soft-deleted assistant from the Recently Deleted list.
+   *
+   * The assistant becomes fully active again with its versions and TeXML application
+   * as they were at deletion time. Restoring does not re-enable numbers or
+   * connections that were released separately after the deletion.
+   *
+   * @example
+   * ```ts
+   * const inferenceEmbedding =
+   *   await client.ai.assistants.restore('assistant_id');
+   * ```
+   */
+  restore(assistantID: string, options?: RequestOptions): APIPromise<InferenceEmbedding> {
+    return this._client.post(path`/ai/assistants/${assistantID}/restore`, options);
+  }
 }
 
 /**
@@ -1004,6 +1096,20 @@ export namespace AssistantTool {
          * `shared` the exchange stays in the conversation like any other messages.
          */
         end_user_target_context_mode?: 'private' | 'shared';
+
+        /**
+         * Fail closed when the acceptance consult cannot run. Off by default: if the
+         * consult cannot be set up for any reason — including where acceptance is
+         * unavailable at all (`gather_using_ai`, Conversation Relay or web calls, a
+         * conference, or additional invited participants) — the transfer degrades to a
+         * plain warm transfer (the warm transfer message is played to the destination as
+         * audio and the calls are bridged anyway). Set to true to treat those paths as a
+         * decline instead: the destination is disconnected without being asked, the
+         * assistant returns to the caller, and no bridge happens without an acceptance.
+         * Only consult-setup failures are affected; the destination must still explicitly
+         * accept on every consult that does run.
+         */
+        require_acceptance?: boolean;
       }
     }
   }
@@ -1349,6 +1455,34 @@ export interface AudioVisualizerConfig {
  */
 export type AuthenticationMethod = 'token' | 'certificate';
 
+/**
+ * **Beta:** Configuration for the Telnyx open-source avatar provider. Use one of
+ * the six stock avatars or an organization-owned custom avatar returned by the
+ * Avatars API. Supported backgrounds are office, studio, and reception.
+ */
+export interface AvatarSettingsRequest {
+  /**
+   * The Telnyx stock avatar or organization-owned custom avatar to render.
+   */
+  avatar_id: AvatarsAPI.AvatarID;
+
+  /**
+   * The background to render.
+   */
+  background_id: 'office' | 'studio' | 'reception';
+
+  /**
+   * Required avatar model identifier, separate from `avatar_id`. The supported value
+   * is `foxtrot-1`. Omission, null, and unsupported model identifiers are rejected.
+   */
+  model: 'foxtrot-1';
+
+  /**
+   * Selects the Telnyx open-source avatar provider.
+   */
+  provider: 'telnyx';
+}
+
 /**
  * Combine sub-expressions with a logical operator (`and` / `or` / `not`).
  *
@@ -1429,7 +1563,7 @@ export interface ConversationFlow {
 export interface ConversationFlowReq {
   /**
    * All nodes in the flow. Must contain `start_node_id`. Each node is a prompt node
-   * (`type: prompt`) or a tool node (`type: tool`).
+   * (`type: prompt`), a tool node (`type: tool`), or a speak node (`type: speak`).
    */
   nodes: Array<FlowNodeReq | ToolNodeReq | SpeakNodeReq>;
 
@@ -1444,6 +1578,73 @@ export interface ConversationFlowReq {
   edges?: Array<FlowEdge>;
 }
 
+/**
+ * Splits the conversation between a frontend model that talks to the caller and a
+ * backend model that does the work. On the GPT-Live route the frontend model
+ * cannot call tools at all — when it needs something done it raises a delegation
+ * and waits. On the chat completion route the frontend keeps a single `delegate`
+ * tool that returns immediately, so the conversation carries on while the backend
+ * works. Either way the backend's answer is spoken as commentary or kept as silent
+ * context, depending on `speak_results`. Beta feature.
+ */
+export interface DelegationSettings {
+  /**
+   * Whether the assistant delegates work to a backend model. Defaults to `true`: a
+   * GPT-Live assistant with delegation disabled can hold a conversation but can
+   * never look anything up or run a tool.
+   */
+  enabled?: boolean;
+
+  /**
+   * Run the backend on your own OpenAI-compatible endpoint instead of a
+   * Telnyx-hosted model. As above, a raw `api_key` here is rejected — reference an
+   * integration secret with `external_llm.llm_api_key_ref` instead.
+   */
+  external_llm?: ExternalLlm;
+
+  /**
+   * Extra instructions for the backend model, in addition to the assistant's own.
+   * Use this for the business rules the backend needs and the talking model does
+   * not.
+   */
+  instructions?: string;
+
+  /**
+   * Integration secret identifier for the backend model's API key. Required for
+   * models from providers other than Telnyx, OpenAI and Anthropic. A raw `api_key`
+   * is rejected rather than ignored, so that no plaintext credential is stored on
+   * the assistant.
+   */
+  llm_api_key_ref?: string;
+
+  /**
+   * Who answers a delegation. `telnyx` runs the backend model on Telnyx with the
+   * assistant's own tools, MCP servers and observability. `client` relays the
+   * delegation to a server you host over the WebSocket configured in
+   * `websocket_settings`: Telnyx sends a `session.delegation.created` frame and
+   * waits for your `session.delegation.completed` answer. That answer is text only,
+   * since the socket offers no tool vocabulary. If no socket is connected the
+   * delegation is refused and the assistant tells the caller it cannot look things
+   * up right now. Defaults to `telnyx`.
+   */
+  mode?: 'telnyx' | 'client';
+
+  /**
+   * The backend model that answers delegations. Must be a model available for AI
+   * Assistants. When enabling `telnyx` delegation, explicitly set this field or
+   * `external_llm.model`; a configuration without either backend model is rejected.
+   * Only applies when `mode` is `telnyx`.
+   */
+  model?: string;
+
+  /**
+   * Whether the backend's answer is spoken to the caller. When `true` the result is
+   * appended as commentary and paraphrased aloud; when `false` it is kept as silent
+   * context that informs later answers without being read out. Defaults to `true`.
+   */
+  speak_results?: boolean;
+}
+
 /**
  * If `telephony` is enabled, the assistant will be able to make and receive calls.
  * If `messaging` is enabled, the assistant will be able to send and receive
@@ -1644,9 +1845,14 @@ export interface FallbackConfigReq {
  * Directed transition from one node to a target, gated by a condition.
  *
  * The target is either another node in the same flow (`NodeTarget`) or a different
- * assistant (`AssistantTarget`). Multiple edges may share a `start_node_id`; the
- * runtime evaluates them in the order they're declared and takes the first whose
- * condition is true.
+ * assistant (`AssistantTarget`). Multiple edges may share a `start_node_id`. On
+ * calls, `expression` conditions are evaluated before the model turn and take
+ * precedence over `llm` conditions regardless of declaration order, while `llm`
+ * conditions are offered to the assistant's model as transition tools and fire
+ * when the model selects one. On chat channels, an `expression` condition that is
+ * true when the turn begins routes before the reply is generated; all conditioned
+ * edges that remain are considered together in declaration order after the reply,
+ * and the first true one wins.
  */
 export interface FlowEdge {
   /**
@@ -1674,15 +1880,22 @@ export interface FlowEdge {
 
 export namespace FlowEdge {
   /**
-   * Edge condition evaluated by the LLM from a natural-language prompt.
+   * Edge condition routed by the assistant's LLM from a natural-language prompt.
    *
-   * The model is asked to judge the prompt against conversation context and returns
-   * true/false. Use this for fuzzy intents that aren't expressible as a
-   * deterministic expression (e.g. 'user wants to escalate to a human').
+   * How the edge is decided depends on the channel. On calls, each outgoing `llm`
+   * condition is offered to the assistant's model as a transition tool alongside the
+   * assistant's tools, and the edge fires when the model selects it; the platform
+   * does not evaluate the prompt itself, and instructions that forbid or discourage
+   * tool calls can stop these edges from firing. On chat channels, the edge prompts
+   * are evaluated in a separate model call after the reply, which does not use the
+   * assistant's instructions. Use this for fuzzy intents that aren't expressible as
+   * a deterministic expression (e.g. 'user wants to escalate to a human').
    */
   export interface LlmCondition {
     /**
-     * Natural-language criterion the LLM judges as true/false.
+     * Natural-language criterion the model routes on. On calls this is offered to the
+     * model as the transition tool's description; on chat channels it is judged as a
+     * statement in the post-reply evaluation call.
      */
     prompt: string;
 
@@ -1942,13 +2155,18 @@ export interface FlowNodeReq {
 
   /**
    * Per-node transcription override (model/language/region). Unset fields cascade
-   * from the assistant-level transcription.
+   * from the assistant-level transcription. A node that sets `model`,
+   * `fallback_models`, or `challenger` doesn't inherit the assistant's
+   * `fallback_models` or `challenger`; it uses only the ones it sets. Otherwise it
+   * inherits them, and they must fit the model and language the node runs; a change
+   * they no longer fit is rejected.
    */
   transcription?: TranscriptionSettings;
 
   /**
    * Node kind discriminator. `prompt` (default) is an LLM-driven step; `tool` is a
-   * standalone tool execution (see `ToolNodeReq`).
+   * standalone tool execution and `speak` a scripted message (see `ToolNodeReq` /
+   * `SpeakNodeReq`).
    */
   type?: 'prompt';
 
@@ -2018,11 +2236,29 @@ export interface InferenceEmbedding {
    */
   a2a_agents?: Array<AssistantA2AAgent>;
 
+  /**
+   * **Beta:** Configuration for the Telnyx open-source avatar provider. Use one of
+   * the six stock avatars or an organization-owned custom avatar returned by the
+   * Avatars API. Supported backgrounds are office, studio, and reception.
+   */
+  avatar_settings?: TelnyxAvatarSettings | null;
+
   /**
    * Conversation flow as returned by the API.
    */
   conversation_flow?: ConversationFlow;
 
+  /**
+   * Splits the conversation between a frontend model that talks to the caller and a
+   * backend model that does the work. On the GPT-Live route the frontend model
+   * cannot call tools at all — when it needs something done it raises a delegation
+   * and waits. On the chat completion route the frontend keeps a single `delegate`
+   * tool that returns immediately, so the conversation carries on while the backend
+   * works. Either way the backend's answer is spoken as commentary or kept as silent
+   * context, depending on `speak_results`. Beta feature.
+   */
+  delegation_settings?: DelegationSettings;
+
   description?: string;
 
   /**
@@ -2163,6 +2399,15 @@ export interface InferenceEmbedding {
 
   voice_settings?: InferenceEmbeddingVoiceSettings;
 
+  /**
+   * Streams conversation and telephony events to a WebSocket server you host, and
+   * accepts messages injected back into the conversation. Telnyx opens the
+   * connection as a client, once per conversation. Delivery is best effort
+   * throughout: while the connection is down events are dropped rather than queued,
+   * and no socket failure is ever allowed to affect the call. Beta feature.
+   */
+  websocket_settings?: WebsocketSettings;
+
   /**
    * Configuration settings for the assistant's web widget.
    */
@@ -2235,8 +2480,8 @@ export interface InferenceEmbeddingVoiceSettings {
    * preview it before saving.
    */
   background_audio?:
-    | InferenceEmbeddingVoiceSettings.UnionMember0
-    | InferenceEmbeddingVoiceSettings.UnionMember1
+    | InferenceEmbeddingVoiceSettings.BackgroundAudioUnionMember0
+    | InferenceEmbeddingVoiceSettings.BackgroundAudioUnionMember1
     | InferenceEmbeddingVoiceSettings.UnionMember2;
 
   /**
@@ -2321,6 +2566,17 @@ export interface InferenceEmbeddingVoiceSettings {
    */
   temperature?: number;
 
+  /**
+   * Optional sound played to the caller while the assistant runs a tool (for example
+   * a webhook or MCP tool). It replaces the background audio until the tool
+   * responds, then the background audio resumes. Defaults to null, which plays no
+   * sound; send `null` on update to clear it. Not played in conference calls.
+   */
+  tool_call_audio?:
+    | InferenceEmbeddingVoiceSettings.ToolCallAudioUnionMember0
+    | InferenceEmbeddingVoiceSettings.ToolCallAudioUnionMember1
+    | null;
+
   /**
    * Amplifies similarity to the original speaker voice. Increases computational load
    * and latency slightly. Only applicable when using ElevenLabs.
@@ -2328,15 +2584,16 @@ export interface InferenceEmbeddingVoiceSettings {
   use_speaker_boost?: boolean;
 
   /**
-   * The speed of the voice in the range [0.25, 2.0]. 1.0 is deafult speed. Larger
-   * numbers make the voice faster, smaller numbers make it slower. This is only
-   * applicable for Telnyx Natural voices and Soniox voices (0.7 to 1.3 for Soniox).
+   * The speed of the voice in the range [0.6, 1.5]. 1.0 is the default speed. Larger
+   * numbers make the voice faster, smaller numbers make it slower. Applies to Telnyx
+   * `Ultra` voices; values outside this range are rejected by the synthesis engine.
+   * Soniox voices support a speed range of 0.7 to 1.3.
    */
   voice_speed?: number;
 }
 
 export namespace InferenceEmbeddingVoiceSettings {
-  export interface UnionMember0 {
+  export interface BackgroundAudioUnionMember0 {
     /**
      * Select from predefined media options.
      */
@@ -2354,7 +2611,7 @@ export namespace InferenceEmbeddingVoiceSettings {
     volume?: number;
   }
 
-  export interface UnionMember1 {
+  export interface BackgroundAudioUnionMember1 {
     /**
      * Provide a direct URL to an MP3 file. The audio will loop during the call.
      */
@@ -2379,6 +2636,36 @@ export namespace InferenceEmbeddingVoiceSettings {
      */
     value: string;
   }
+
+  export interface ToolCallAudioUnionMember0 {
+    /**
+     * Select from predefined media options.
+     */
+    type: 'predefined_media';
+
+    /**
+     * The predefined media to use. `typing` plays a keyboard typing sound.
+     */
+    value: 'typing';
+
+    /**
+     * Volume level for the predefined media. Supports values from 0.0 to 1.0 in 0.1
+     * increments. `0.0` plays no sound.
+     */
+    volume?: number;
+  }
+
+  export interface ToolCallAudioUnionMember1 {
+    /**
+     * Provide a direct URL to an MP3 file. The audio loops while the tool runs.
+     */
+    type: 'media_url';
+
+    /**
+     * HTTPS URL to an MP3 file.
+     */
+    value: string;
+  }
 }
 
 export interface InferenceEmbeddingWebhookToolParams {
@@ -2932,6 +3219,16 @@ export interface StartSpeakingPlan {
 }
 
 export interface TelephonySettings {
+  /**
+   * When enabled, the `messages` array of the `call.conversation.ended` webhook
+   * contains the full conversation history in order: user and assistant turns,
+   * assistant tool calls (`tool_calls`), tool results (`role: tool` with
+   * `tool_call_id`), and informational `system` and `developer` entries. The
+   * assistant's instructions are never included. When disabled, `messages` contains
+   * only user and assistant text turns.
+   */
+  conversation_ended_full_history?: boolean;
+
   /**
    * Default Texml App used for voice calls with your assistant. This will be created
    * automatically on assistant creation.
@@ -3157,6 +3454,34 @@ export namespace TelephonySettings {
   }
 }
 
+/**
+ * **Beta:** Configuration for the Telnyx open-source avatar provider. Use one of
+ * the six stock avatars or an organization-owned custom avatar returned by the
+ * Avatars API. Supported backgrounds are office, studio, and reception.
+ */
+export interface TelnyxAvatarSettings {
+  /**
+   * The Telnyx stock avatar or organization-owned custom avatar to render.
+   */
+  avatar_id: AvatarsAPI.AvatarID;
+
+  /**
+   * The background to render.
+   */
+  background_id: 'office' | 'studio' | 'reception';
+
+  /**
+   * Required avatar model identifier, separate from `avatar_id`. The supported value
+   * is `foxtrot-1`. Omission, null, and unsupported model identifiers are rejected.
+   */
+  model: 'foxtrot-1';
+
+  /**
+   * Selects the Telnyx open-source avatar provider.
+   */
+  provider: 'telnyx';
+}
+
 /**
  * A standalone tool step in a conversation flow, as returned by the API.
  */
@@ -3169,13 +3494,24 @@ export interface ToolNode {
   /**
    * ID of the single shared (org-level) tool this node executes. When the flow
    * reaches this node the tool runs as a deliberate step (no LLM turn); its outgoing
-   * `tool_result` edges then route on the outcome. Arguments are filled from the
-   * conversation's dynamic variables by name — a dynamic variable whose name matches
-   * one of the tool's parameters supplies that argument. Cross-validated against the
-   * org's shared tools on write.
+   * `llm` / `expression` edges route the flow on the tool's outcome. Arguments are
+   * filled from the conversation's dynamic variables by name — a dynamic variable
+   * whose name matches one of the tool's parameters supplies that argument.
+   * Cross-validated against the org's shared tools on write.
    */
   shared_tool_id: string;
 
+  /**
+   * Optional message delivered to the user verbatim immediately before the tool
+   * executes — an announcement such as 'One moment while I look that up.' No LLM
+   * turn and no customer turn: the message is spoken/sent, then the tool runs, in
+   * the same deterministic step. `{{variable}}` placeholders are interpolated from
+   * the conversation's dynamic variables (unresolved → empty string); the tool's own
+   * result is not yet available when the message is rendered. Omit for a silent tool
+   * step.
+   */
+  message?: string;
+
   /**
    * Optional human-readable label, displayed in authoring UIs.
    */
@@ -3206,8 +3542,10 @@ export interface ToolNode {
  *
  * Unlike a prompt node, a tool node has no instructions or model — it isn't an LLM
  * turn. Reaching it deterministically runs one shared tool (arguments filled from
- * matching dynamic variables by name), then routes on the result via outgoing
- * `tool_result` edges.
+ * matching dynamic variables by name), then routes via outgoing `llm` /
+ * `expression` edges, with exactly one `default` fallback edge required when the
+ * node has any outgoing edges (the tool's outcome is readable as
+ * `telnyx_last_tool_status_code` in `expression` conditions).
  */
 export interface ToolNodeReq {
   /**
@@ -3218,13 +3556,24 @@ export interface ToolNodeReq {
   /**
    * ID of the single shared (org-level) tool this node executes. When the flow
    * reaches this node the tool runs as a deliberate step (no LLM turn); its outgoing
-   * `tool_result` edges then route on the outcome. Arguments are filled from the
-   * conversation's dynamic variables by name — a dynamic variable whose name matches
-   * one of the tool's parameters supplies that argument. Cross-validated against the
-   * org's shared tools on write.
+   * `llm` / `expression` edges route the flow on the tool's outcome. Arguments are
+   * filled from the conversation's dynamic variables by name — a dynamic variable
+   * whose name matches one of the tool's parameters supplies that argument.
+   * Cross-validated against the org's shared tools on write.
    */
   shared_tool_id: string;
 
+  /**
+   * Optional message delivered to the user verbatim immediately before the tool
+   * executes — an announcement such as 'One moment while I look that up.' No LLM
+   * turn and no customer turn: the message is spoken/sent, then the tool runs, in
+   * the same deterministic step. `{{variable}}` placeholders are interpolated from
+   * the conversation's dynamic variables (unresolved → empty string); the tool's own
+   * result is not yet available when the message is rendered. Omit for a silent tool
+   * step.
+   */
+  message?: string;
+
   /**
    * Optional human-readable label, displayed in authoring UIs.
    */
@@ -3273,6 +3622,24 @@ export interface TranscriptionSettings {
    */
   api_key_ref?: string;
 
+  /**
+   * A second speech-to-text model that transcribes alongside `transcription.model`,
+   * and the rule that decides which transcript the assistant uses.
+   */
+  challenger?: TranscriptionSettings.Challenger | null;
+
+  /**
+   * Up to 3 streaming models that take over transcription, in this order, when the
+   * model in use fails, at the start of a call or mid-call. `model` must be a
+   * streaming model too, and must support `language` alongside other models. On
+   * update, a list replaces the stored one: omit the field to keep the stored list,
+   * or send `null` or `[]` to remove it. When an update changes `model` or
+   * `language`, stored fallbacks that no longer fit are removed without an error.
+   * Can't be combined with `challenger`, the language booster; to replace a stored
+   * language booster, send `challenger: null` in the same request.
+   */
+  fallback_models?: Array<TranscriptionSettings.FallbackModel> | null;
+
   /**
    * The language of the audio to be transcribed. If not set, or if set to `auto`,
    * supported models will automatically detect the language. For `deepgram/flux`,
@@ -3318,6 +3685,7 @@ export interface TranscriptionSettings {
    * - `reson8/turns` is a turn-based streaming model covering 10 European languages
    *   with automatic language detection.
    * - `cohere/ar-stt` is a non-streaming Arabic and English transcription model.
+   * - `telnyx/basira` is a non-streaming Arabic transcription model.
    */
   model?:
     | 'deepgram/flux'
@@ -3334,6 +3702,7 @@ export interface TranscriptionSettings {
     | 'humain/realtime'
     | 'reson8/turns'
     | 'cohere/ar-stt'
+    | 'telnyx/basira'
     | 'distil-whisper/distil-large-v2'
     | 'openai/whisper-large-v3-turbo';
 
@@ -3346,6 +3715,124 @@ export interface TranscriptionSettings {
   settings?: TranscriptionSettingsConfig;
 }
 
+export namespace TranscriptionSettings {
+  /**
+   * A second speech-to-text model that transcribes alongside `transcription.model`,
+   * and the rule that decides which transcript the assistant uses.
+   */
+  export interface Challenger {
+    /**
+     * The language booster's model. It must be the same kind of model as
+     * `transcription.model`: both streaming (`deepgram/flux`, `deepgram/nova-3`,
+     * `deepgram/nova-2`, `assemblyai/universal-3-5-pro` or its legacy alias
+     * `assemblyai/universal-streaming`, `xai/grok-stt`, `soniox/stt-rt-v4`,
+     * `soniox/stt-rt-v5`, `humain/realtime`, `reson8/turns`) or both non-streaming
+     * (`azure/fast`, `nvidia/parakeet-v3`, `omi-health/omi-med-stt-v1`,
+     * `cohere/ar-stt`, `distil-whisper/distil-large-v2`,
+     * `openai/whisper-large-v3-turbo`, `telnyx/basira`). It can be the same model as
+     * `transcription.model` on a different `language`.
+     */
+    model:
+      | 'deepgram/flux'
+      | 'deepgram/nova-3'
+      | 'deepgram/nova-2'
+      | 'azure/fast'
+      | 'assemblyai/universal-3-5-pro'
+      | 'assemblyai/universal-streaming'
+      | 'xai/grok-stt'
+      | 'soniox/stt-rt-v4'
+      | 'soniox/stt-rt-v5'
+      | 'nvidia/parakeet-v3'
+      | 'omi-health/omi-med-stt-v1'
+      | 'humain/realtime'
+      | 'reson8/turns'
+      | 'cohere/ar-stt'
+      | 'telnyx/basira'
+      | 'distil-whisper/distil-large-v2'
+      | 'openai/whisper-large-v3-turbo';
+
+    /**
+     * The language this model transcribes. Omit it or set it to `null` to use the
+     * language of `transcription.model`. The request is rejected when this model
+     * doesn't support the language it would run. It is also rejected when it would run
+     * the same model on the same language as `transcription.model`.
+     */
+    language?: string | null;
+
+    /**
+     * How the assistant picks the transcript it uses. The models are compared on how
+     * complete and confident their transcripts are, not on language, so the rules work
+     * best when both models understand the callers' language.
+     *
+     * - `best_turn` (default): both models transcribe the whole call. Each turn uses
+     *   the language booster's transcript only when it scores higher than the
+     *   transcript of `transcription.model` (clearly higher with non-streaming
+     *   models). With streaming models, `transcription.model` also decides when each
+     *   turn ends. Available for every pair.
+     * - `best_engine`: both models transcribe the first turns, then the call continues
+     *   alone on the model whose transcripts scored higher. If neither clearly leads,
+     *   `transcription.model` continues. Streaming models only.
+     * - `merge_words`: both models transcribe each utterance and their words are
+     *   merged, keeping Arabic and English spoken in the same sentence. Available only
+     *   for `telnyx/basira` with `cohere/ar-stt`, in either order. The pair runs on
+     *   the language that applies to `telnyx/basira` (its own, or that of
+     *   `transcription.model`), which must be Arabic (`ar` or an `ar-` locale),
+     *   `multi`, or `auto`.
+     */
+    rule?: 'best_turn' | 'best_engine' | 'merge_words';
+
+    /**
+     * Settings for the language booster, with the same fields and limits as
+     * `transcription.settings`. Fields that don't apply to this model's provider are
+     * dropped, and the provider's defaults fill in the rest. Omit it or set it to
+     * `null` to use the settings of `transcription.model` where they apply to this
+     * model.
+     */
+    settings?: AssistantsAPI.TranscriptionSettingsConfig | null;
+  }
+
+  /**
+   * A streaming speech-to-text model that takes over transcription when the model in
+   * use fails.
+   */
+  export interface FallbackModel {
+    /**
+     * The fallback model. It must be a streaming model other than
+     * `transcription.model` and the other fallbacks: `deepgram/flux`,
+     * `deepgram/nova-3`, `deepgram/nova-2`, `assemblyai/universal-3-5-pro` (or its
+     * legacy alias `assemblyai/universal-streaming`), `xai/grok-stt`,
+     * `soniox/stt-rt-v4`, `soniox/stt-rt-v5`, `humain/realtime`, or `reson8/turns`.
+     */
+    model:
+      | 'deepgram/flux'
+      | 'deepgram/nova-3'
+      | 'deepgram/nova-2'
+      | 'assemblyai/universal-3-5-pro'
+      | 'assemblyai/universal-streaming'
+      | 'xai/grok-stt'
+      | 'soniox/stt-rt-v4'
+      | 'soniox/stt-rt-v5'
+      | 'humain/realtime'
+      | 'reson8/turns';
+
+    /**
+     * The language the fallback transcribes. Omit it or set it to `null` to use the
+     * language of `transcription.model`. The request is rejected when the fallback
+     * model doesn't support the language it would run.
+     */
+    language?: string | null;
+
+    /**
+     * Settings for the fallback, with the same fields and limits as
+     * `transcription.settings`. Fields that don't apply to this model's provider are
+     * dropped, and the provider's defaults fill in the rest. Omit it or set it to
+     * `null` to use the settings of `transcription.model` where they apply to this
+     * model.
+     */
+    settings?: AssistantsAPI.TranscriptionSettingsConfig | null;
+  }
+}
+
 export interface TranscriptionSettingsConfig {
   /**
    * Available only for soniox/stt-rt-v4 and soniox/stt-rt-v5. A comma-separated list
@@ -3598,9 +4085,9 @@ export interface VoiceSettings {
   use_speaker_boost?: boolean;
 
   /**
-   * The speed of the voice in the range [0.25, 2.0]. 1.0 is deafult speed. Larger
-   * numbers make the voice faster, smaller numbers make it slower. This is only
-   * applicable for Telnyx Natural voices.
+   * The speed of the voice in the range [0.6, 1.5]. 1.0 is the default speed. Larger
+   * numbers make the voice faster, smaller numbers make it slower. Applies to Telnyx
+   * `Ultra` voices; values outside this range are rejected by the synthesis engine.
    */
   voice_speed?: number;
 }
@@ -3799,6 +4286,35 @@ export namespace WebhookTool {
   }
 }
 
+/**
+ * Streams conversation and telephony events to a WebSocket server you host, and
+ * accepts messages injected back into the conversation. Telnyx opens the
+ * connection as a client, once per conversation. Delivery is best effort
+ * throughout: while the connection is down events are dropped rather than queued,
+ * and no socket failure is ever allowed to affect the call. Beta feature.
+ */
+export interface WebsocketSettings {
+  /**
+   * Integration secret identifier whose value Telnyx sends as an
+   * `Authorization: Bearer <value>` header on the upgrade request. Resolved on every
+   * connection attempt, so a rotated secret is picked up by the next reconnect.
+   */
+  auth_ref?: string;
+
+  /**
+   * Whether Telnyx opens a WebSocket to `url` for each of this assistant's
+   * conversations. Defaults to `false`.
+   */
+  enabled?: boolean;
+
+  /**
+   * The `ws://` or `wss://` endpoint Telnyx connects to. Required when `enabled` is
+   * `true`. Must be externally reachable — localhost, private IP ranges and `.local`
+   * domains are rejected.
+   */
+  url?: string;
+}
+
 /**
  * Configuration settings for the assistant's web widget.
  */
@@ -3881,6 +4397,18 @@ export interface AssistantSendSMSResponse {
   conversation_id?: string;
 }
 
+export interface AssistantWhatsappResponse {
+  /**
+   * ID of the conversation created for this WhatsApp chat.
+   */
+  conversation_id: string;
+
+  /**
+   * ID of the WhatsApp template message that was sent.
+   */
+  message_id: string;
+}
+
 export interface AssistantCreateParams {
   /**
    * Body param: System instructions for the assistant. These may be templated with
@@ -3905,6 +4433,13 @@ export interface AssistantCreateParams {
    */
   a2a_agents?: Array<AssistantA2AAgent>;
 
+  /**
+   * Body param: **Beta:** Configuration for the Telnyx open-source avatar provider.
+   * Use one of the six stock avatars or an organization-owned custom avatar returned
+   * by the Avatars API. Supported backgrounds are office, studio, and reception.
+   */
+  avatar_settings?: AvatarSettingsRequest | null;
+
   /**
    * Body param: Conversation flow as supplied by API clients (create / update).
    *
@@ -3914,6 +4449,17 @@ export interface AssistantCreateParams {
    */
   conversation_flow?: ConversationFlowReq;
 
+  /**
+   * Body param: Splits the conversation between a frontend model that talks to the
+   * caller and a backend model that does the work. On the GPT-Live route the
+   * frontend model cannot call tools at all — when it needs something done it raises
+   * a delegation and waits. On the chat completion route the frontend keeps a single
+   * `delegate` tool that returns immediately, so the conversation carries on while
+   * the backend works. Either way the backend's answer is spoken as commentary or
+   * kept as silent context, depending on `speak_results`. Beta feature.
+   */
+  delegation_settings?: DelegationSettings;
+
   /**
    * Body param
    */
@@ -4077,6 +4623,15 @@ export interface AssistantCreateParams {
    */
   voice_settings?: InferenceEmbeddingVoiceSettings;
 
+  /**
+   * Body param: Streams conversation and telephony events to a WebSocket server you
+   * host, and accepts messages injected back into the conversation. Telnyx opens the
+   * connection as a client, once per conversation. Delivery is best effort
+   * throughout: while the connection is down events are dropped rather than queued,
+   * and no socket failure is ever allowed to affect the call. Beta feature.
+   */
+  websocket_settings?: WebsocketSettings;
+
   /**
    * Body param: Configuration settings for the assistant's web widget.
    */
@@ -4127,6 +4682,14 @@ export interface AssistantImportsParams {
   'Idempotency-Key'?: string;
 }
 
+export interface AssistantDeleteParams {
+  /**
+   * Permanently delete the assistant immediately instead of soft-deleting it to the
+   * Recently Deleted list, where it stays restorable for 30 days.
+   */
+  hard_delete?: boolean;
+}
+
 export interface AssistantRetrieveParams {
   /**
    * Filter results by call control id.
@@ -4163,6 +4726,13 @@ export interface AssistantUpdateParams {
    */
   a2a_agents?: Array<AssistantA2AAgent>;
 
+  /**
+   * **Beta:** Configuration for the Telnyx open-source avatar provider. Use one of
+   * the six stock avatars or an organization-owned custom avatar returned by the
+   * Avatars API. Supported backgrounds are office, studio, and reception.
+   */
+  avatar_settings?: AvatarSettingsRequest | null;
+
   /**
    * Conversation flow as supplied by API clients (create / update).
    *
@@ -4172,6 +4742,17 @@ export interface AssistantUpdateParams {
    */
   conversation_flow?: ConversationFlowReq;
 
+  /**
+   * Splits the conversation between a frontend model that talks to the caller and a
+   * backend model that does the work. On the GPT-Live route the frontend model
+   * cannot call tools at all — when it needs something done it raises a delegation
+   * and waits. On the chat completion route the frontend keeps a single `delegate`
+   * tool that returns immediately, so the conversation carries on while the backend
+   * works. Either way the backend's answer is spoken as commentary or kept as silent
+   * context, depending on `speak_results`. Beta feature.
+   */
+  delegation_settings?: DelegationSettings;
+
   description?: string;
 
   /**
@@ -4331,6 +4912,15 @@ export interface AssistantUpdateParams {
 
   voice_settings?: InferenceEmbeddingVoiceSettings;
 
+  /**
+   * Streams conversation and telephony events to a WebSocket server you host, and
+   * accepts messages injected back into the conversation. Telnyx opens the
+   * connection as a client, once per conversation. Delivery is best effort
+   * throughout: while the connection is down events are dropped rather than queued,
+   * and no socket failure is ever allowed to affect the call. Beta feature.
+   */
+  websocket_settings?: WebsocketSettings;
+
   /**
    * Configuration settings for the assistant's web widget.
    */
@@ -4416,6 +5006,44 @@ export interface AssistantSendSMSParams {
   'Idempotency-Key'?: string;
 }
 
+export interface AssistantWhatsappParams {
+  /**
+   * Body param: Instruction for the assistant, including the values for the template
+   * variables, e.g. `Send the login verification code 482913 to the customer.`
+   */
+  content: string;
+
+  /**
+   * Body param: WhatsApp number on your account to send from, in E.164 format. Its
+   * messaging profile must have this assistant configured.
+   */
+  from: string;
+
+  /**
+   * Body param: Customer to message, as an E.164 phone number or a WhatsApp
+   * business-scoped user ID (BSUID).
+   */
+  to: string;
+
+  /**
+   * Body param: Metadata stored on the conversation. Keys starting with `telnyx_`
+   * and the `assistant_id` key are reserved.
+   */
+  conversation_metadata?: { [key: string]: string | number | boolean };
+
+  /**
+   * Header param: Optional opaque, unquoted key for safely retrying the same logical
+   * request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
+   * Generate a unique UUID v4 for each operation and reuse it only when retrying
+   * that operation with the same request. Invalid headers—including duplicate,
+   * empty, malformed, or overlong values—return 400 with error code 10015. A request
+   * already in progress with the same key returns 409; reusing the key with a
+   * different request returns 422. Only successful responses are replayed, for up to
+   * 24 hours. Do not include sensitive data in the key.
+   */
+  'Idempotency-Key'?: string;
+}
+
 Assistants.Tests = Tests;
 Assistants.CanaryDeploys = CanaryDeploys;
 Assistants.ScheduledEvents = ScheduledEvents;
@@ -4423,6 +5051,7 @@ Assistants.Tools = Tools;
 Assistants.Versions = Versions;
 Assistants.Tags = Tags;
 Assistants.Instructions = Instructions;
+Assistants.Deleted = Deleted;
 
 export declare namespace Assistants {
   export {
@@ -4435,10 +5064,12 @@ export declare namespace Assistants {
     type AssistantsList as AssistantsList,
     type AudioVisualizerConfig as AudioVisualizerConfig,
     type AuthenticationMethod as AuthenticationMethod,
+    type AvatarSettingsRequest as AvatarSettingsRequest,
     type BooleanOpExpression as BooleanOpExpression,
     type ComparisonExpression as ComparisonExpression,
     type ConversationFlow as ConversationFlow,
     type ConversationFlowReq as ConversationFlowReq,
+    type DelegationSettings as DelegationSettings,
     type EnabledFeatures as EnabledFeatures,
     type Expression as Expression,
     type ExternalLlm as ExternalLlm,
@@ -4470,6 +5101,7 @@ export declare namespace Assistants {
     type SpeakNodeReq as SpeakNodeReq,
     type StartSpeakingPlan as StartSpeakingPlan,
     type TelephonySettings as TelephonySettings,
+    type TelnyxAvatarSettings as TelnyxAvatarSettings,
     type ToolNode as ToolNode,
     type ToolNodeReq as ToolNodeReq,
     type TranscriptionEndpointingPlan as TranscriptionEndpointingPlan,
@@ -4478,18 +5110,22 @@ export declare namespace Assistants {
     type TransferTool as TransferTool,
     type VoiceSettings as VoiceSettings,
     type WebhookTool as WebhookTool,
+    type WebsocketSettings as WebsocketSettings,
     type WidgetSettings as WidgetSettings,
     type AssistantDeleteResponse as AssistantDeleteResponse,
     type AssistantChatResponse as AssistantChatResponse,
     type AssistantGetTexmlResponse as AssistantGetTexmlResponse,
     type AssistantSendSMSResponse as AssistantSendSMSResponse,
+    type AssistantWhatsappResponse as AssistantWhatsappResponse,
     type AssistantCreateParams as AssistantCreateParams,
     type AssistantImportsParams as AssistantImportsParams,
+    type AssistantDeleteParams as AssistantDeleteParams,
     type AssistantRetrieveParams as AssistantRetrieveParams,
     type AssistantUpdateParams as AssistantUpdateParams,
     type AssistantChatParams as AssistantChatParams,
     type AssistantCloneParams as AssistantCloneParams,
     type AssistantSendSMSParams as AssistantSendSMSParams,
+    type AssistantWhatsappParams as AssistantWhatsappParams,
   };
 
   export {
@@ -4562,4 +5198,11 @@ export declare namespace Assistants {
     type InstructionEnhanceResponse as InstructionEnhanceResponse,
     type InstructionEnhanceParams as InstructionEnhanceParams,
   };
+
+  export {
+    Deleted as Deleted,
+    type DeletedAssistant as DeletedAssistant,
+    type DeletedAssistantsDefaultFlatPagination as DeletedAssistantsDefaultFlatPagination,
+    type DeletedListParams as DeletedListParams,
+  };
 }