retell-sdk 5.63.0 → 5.65.0

package/resources/call.d.ts

@@ -66,16 +66,30 @@ export declare class Call extends APIResource {
      */
     createPhoneCall(body: CallCreatePhoneCallParams, options?: RequestOptions): APIPromise<PhoneCallResponse>;
     /**
-     * Create a new web call
+     * Create a new web call and return browser connection details.
      *
      * @example
      * ```ts
-     * const webCallResponse = await client.call.createWebCall({
-     *   agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
-     * });
+     * const createWebCallResponse =
+     *   await client.call.createWebCall({
+     *     agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
+     *   });
+     * ```
+     */
+    createWebCall(body: CallCreateWebCallParams, options?: RequestOptions): APIPromise<CreateWebCallResponse>;
+    /**
+     * Mint a subscribe-only access token for an in-progress call so a client can
+     * listen to live audio. The returned token grants join + subscribe on the call's
+     * existing audio room; it cannot publish. The call must be in ONGOING status.
+     *
+     * @example
+     * ```ts
+     * const response = await client.call.listenLive(
+     *   '119c3f8e47135a29e65947eeb34cf12d',
+     * );
      * ```
      */
-    createWebCall(body: CallCreateWebCallParams, options?: RequestOptions): APIPromise<WebCallResponse>;
+    listenLive(callID: string, options?: RequestOptions): APIPromise<CallListenLiveResponse>;
     /**
      * Register a new phone call for custom telephony
      *
@@ -108,6 +122,20 @@ export declare class Call extends APIResource {
      * ```
      */
     stop(callID: string, options?: RequestOptions): APIPromise<void>;
+    /**
+     * Take over an in-progress call from the AI agent. The agent stops responding and
+     * the specified live-listen participant is allowed to speak directly to the
+     * caller. The call must be in ONGOING status.
+     *
+     * @example
+     * ```ts
+     * const response = await client.call.takeOverLive(
+     *   '119c3f8e47135a29e65947eeb34cf12d',
+     *   { participant_id: 'listener_a1b2c3d4e5f6g7h8i9j0' },
+     * );
+     * ```
+     */
+    takeOverLive(callID: string, body: CallTakeOverLiveParams, options?: RequestOptions): APIPromise<CallTakeOverLiveResponse>;
     /**
      * Update an ongoing call at runtime. Supports overriding dynamic variables,
      * metadata, and the data storage setting on the running call, and controlling the
@@ -138,6 +166,35 @@ export declare class Call extends APIResource {
     updateLive(callID: string, body: CallUpdateLiveParams, options?: RequestOptions): APIPromise<CallUpdateLiveResponse>;
 }
 export type CallResponse = WebCallResponse | PhoneCallResponse;
+export interface CreateWebCallResponse {
+    /**
+     * Token authorizing this browser to join the web call. Pass it to your frontend.
+     */
+    access_token: string;
+    /**
+     * Unique identifier for the web call.
+     */
+    call_id: string;
+    /**
+     * Unix epoch ms when the access_token expires.
+     */
+    expires_at: number;
+    /**
+     * ICE servers to configure before the browser creates its peer connection.
+     */
+    ice_servers: Array<CreateWebCallResponse.IceServer>;
+    /**
+     * Connection transport to select in the web client.
+     */
+    transport: 'gateway';
+}
+export declare namespace CreateWebCallResponse {
+    interface IceServer {
+        urls: string | Array<string>;
+        credential?: string;
+        username?: string;
+    }
+}
 export interface PhoneCallResponse {
     /**
      * Corresponding agent id of this call.
@@ -2080,8 +2137,8 @@ export interface CallListResponse {
     /**
      * Whether more results are available.
      */
-    has_more?: boolean;
-    items?: Array<CallListResponse.V3WebCallResponse | CallListResponse.V3PhoneCallResponse>;
+    has_more: boolean;
+    items: Array<CallListResponse.V3WebCallResponse | CallListResponse.V3PhoneCallResponse>;
     /**
      * Pagination key for the next page.
      */
@@ -3274,6 +3331,64 @@ export declare namespace CallListResponse {
         }
     }
 }
+export interface CallListenLiveResponse {
+    /**
+     * Subscribe-only JWT scoped to the call's room. Cannot publish. Listener
+     * participant is hidden from other participants.
+     */
+    access_token: string;
+    /**
+     * Unix epoch ms when the access_token expires.
+     */
+    expires_at: number;
+    /**
+     * Identity this listener joins as, and the value to hand back to
+     * /v2/take-over-live-call. Returned on both transports; a `livekit` client can
+     * equally read it off its own room object, a `gateway` one has no equivalent to
+     * read.
+     */
+    participant_id: string;
+    /**
+     * Room name to join. Always the call's original room — does not follow warm
+     * transfers.
+     */
+    room_name: string;
+    /**
+     * Public side of the gateway instance handling this call, for diagnostics only —
+     * the client's media address comes from the SDP answer's ICE candidates. `gateway`
+     * transport only.
+     */
+    gateway_ip?: string;
+    /**
+     * ICE servers the client must configure before creating its PeerConnection — they
+     * cannot be added afterwards. `gateway` transport only.
+     */
+    ice_servers?: Array<CallListenLiveResponse.IceServer>;
+    /**
+     * Which media stack issued the access_token, and therefore where the client
+     * signals. The two tokens are indistinguishable, so a client must read this rather
+     * than infer it. `gateway` clients address Retell itself; `livekit` clients
+     * connect to the returned `url`. Optional only because a server predating the
+     * field omits it during a rollout; treat absent as `livekit`.
+     */
+    transport?: 'livekit' | 'gateway';
+    /**
+     * Server URL the client should connect to with the access_token. Present only when
+     * `transport` is `livekit`; a `gateway` listener signals to Retell and needs no
+     * address.
+     */
+    url?: string;
+}
+export declare namespace CallListenLiveResponse {
+    interface IceServer {
+        urls: string | Array<string>;
+        credential?: string;
+        username?: string;
+    }
+}
+export interface CallTakeOverLiveResponse {
+    success: boolean;
+}
 export interface CallUpdateLiveResponse {
     success: boolean;
 }
@@ -3360,15 +3475,19 @@ export declare namespace CallListParams {
         call_successful?: FilterCriteria.CallSuccessful;
         call_type?: FilterCriteria.CallType;
         /**
-         * Filter by combined cost of the call.
+         * Filter by total call cost in cents.
          */
         combined_cost?: FilterCriteria.NumberFilter | FilterCriteria.RangeFilter;
         /**
-         * Filter by custom analysis data fields.
+         * Filter by custom post-call analysis outputs. Each filter `key` matches the
+         * configured output's `name`.
          */
         custom_analysis_data?: Array<FilterCriteria.StringFilter | FilterCriteria.NumberFilter | FilterCriteria.BooleanFilter | FilterCriteria.RangeFilter | FilterCriteria.EnumFilter | FilterCriteria.PresentFilter>;
         /**
-         * Filter by custom attributes fields.
+         * Filter by organization-level attributes that attach business context to calls,
+         * such as customer tier or campaign, so calls can be organized and filtered
+         * consistently in Call History. Use the attribute ID as `key` and the call's
+         * attribute value as `value`.
          */
         custom_attributes?: Array<FilterCriteria.StringFilter | FilterCriteria.NumberFilter | FilterCriteria.BooleanFilter | FilterCriteria.RangeFilter | FilterCriteria.EnumFilter | FilterCriteria.PresentFilter>;
         data_storage_setting?: FilterCriteria.DataStorageSetting;
@@ -3379,11 +3498,12 @@ export declare namespace CallListParams {
          */
         duration_ms?: FilterCriteria.NumberFilter | FilterCriteria.RangeFilter;
         /**
-         * Filter by dynamic variables.
+         * Filter by dynamic variables stored on the call. Each filter `key` matches a
+         * dynamic-variable name.
          */
-        dynamic_variables?: Array<FilterCriteria.DynamicVariable>;
+        dynamic_variables?: Array<FilterCriteria.StringFilter | FilterCriteria.NumberFilter | FilterCriteria.BooleanFilter | FilterCriteria.RangeFilter | FilterCriteria.EnumFilter | FilterCriteria.PresentFilter>;
         /**
-         * Filter by end-to-end latency p50.
+         * Filter by per-call p50 end-to-end latency in milliseconds.
          */
         e2e_latency_p50?: FilterCriteria.NumberFilter | FilterCriteria.RangeFilter;
         /**
@@ -3399,7 +3519,8 @@ export declare namespace CallListParams {
          */
         in_voicemail?: FilterCriteria.InVoicemail;
         /**
-         * Filter by metadata fields.
+         * Filter by values stored in the call's `metadata`. Each filter `key` matches a
+         * top-level metadata key.
          */
         metadata?: Array<FilterCriteria.StringFilter | FilterCriteria.NumberFilter | FilterCriteria.BooleanFilter | FilterCriteria.RangeFilter | FilterCriteria.EnumFilter | FilterCriteria.PresentFilter>;
         /**
@@ -3423,7 +3544,7 @@ export declare namespace CallListParams {
              */
             agent_id: string;
             /**
-             * Specific versions to filter on. If not provided, all versions are included.
+             * Specific versions to filter on. If omitted or empty, all versions are included.
              */
             version?: Array<number>;
         }
@@ -3697,17 +3818,77 @@ export declare namespace CallListParams {
              */
             value: Array<number>;
         }
-        interface DynamicVariable {
-            /**
-             * The dynamic variable name to filter on.
-             */
-            key: string;
+        interface StringFilter {
             /**
              * eq: equal, ne: not equal, sw: starts with, ew: ends with, co: contains
              */
             op: 'eq' | 'ne' | 'sw' | 'ew' | 'co';
             type: 'string';
             value: string;
+            /**
+             * The field name to filter on.
+             */
+            key?: string;
+        }
+        interface NumberFilter {
+            /**
+             * eq: equal, ne: not equal, gt: greater than, ge: greater than or equal, lt: less
+             * than, le: less than or equal
+             */
+            op: 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le';
+            type: 'number';
+            value: number;
+            /**
+             * The field name to filter on.
+             */
+            key?: string;
+        }
+        interface BooleanFilter {
+            op: 'eq';
+            type: 'boolean';
+            value: boolean;
+            /**
+             * The field name to filter on.
+             */
+            key?: string;
+        }
+        interface RangeFilter {
+            /**
+             * bt: between
+             */
+            op: 'bt';
+            type: 'range';
+            /**
+             * [lower_bound, upper_bound]
+             */
+            value: Array<number>;
+            /**
+             * The field name to filter on.
+             */
+            key?: string;
+        }
+        interface EnumFilter {
+            /**
+             * in: value is one of the listed values
+             */
+            op: 'in';
+            type: 'enum';
+            value: Array<string>;
+            /**
+             * The field name to filter on.
+             */
+            key?: string;
+        }
+        interface PresentFilter {
+            /**
+             * pr: present (has value), np: not present
+             */
+            op: 'pr' | 'np';
+            type: 'present';
+            /**
+             * The field name to filter on.
+             */
+            key?: string;
         }
         interface NumberFilter {
             /**
@@ -4315,7 +4496,7 @@ export declare namespace CallCreatePhoneCallParams {
              * available voice models. Set to null to remove voice model selection, and default
              * ones will apply. Check out dashboard for more details of each voice model.
              */
-            voice_model?: 'eleven_flash_v2' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3' | 'sonic-3' | 'sonic-3-latest' | 'sonic-3.5' | 'tts-1' | 'gpt-4o-mini-tts' | 'speech-02-turbo' | 'speech-2.8-turbo' | 's1' | 's2-pro' | 's2.1-pro' | null;
+            voice_model?: 'eleven_flash_v2' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3' | 'sonic-3' | 'sonic-3-latest' | 'sonic-3.5' | 'sonic-3.6' | 'tts-1' | 'gpt-4o-mini-tts' | 'speech-02-turbo' | 'speech-2.8-turbo' | 's1' | 's2-pro' | 's2.1-pro' | 'inworld-tts-2' | 'inworld-tts-2-flash' | null;
             /**
              * Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower
              * speech, while higher value means faster speech rate. If unset, default value 1
@@ -4384,7 +4565,9 @@ export declare namespace CallCreatePhoneCallParams {
             interface CustomSttConfig {
                 /**
                  * Endpointing timeout in milliseconds. Minimum is 100 for Azure, 10 for Deepgram,
-                 * 500 for Soniox, 100 for AssemblyAI.
+                 * 500 for Soniox, 100 for AssemblyAI. For AssemblyAI, this sets min_turn_silence
+                 * (100-3000 ms). max_turn_silence adds half of this value, rounded to the nearest
+                 * millisecond and bounded to 500-1000 ms, with a total cap of 3000 ms.
                  */
                 endpointing_ms: number;
                 /**
@@ -5261,7 +5444,7 @@ export declare namespace CallCreateWebCallParams {
              * available voice models. Set to null to remove voice model selection, and default
              * ones will apply. Check out dashboard for more details of each voice model.
              */
-            voice_model?: 'eleven_flash_v2' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3' | 'sonic-3' | 'sonic-3-latest' | 'sonic-3.5' | 'tts-1' | 'gpt-4o-mini-tts' | 'speech-02-turbo' | 'speech-2.8-turbo' | 's1' | 's2-pro' | 's2.1-pro' | null;
+            voice_model?: 'eleven_flash_v2' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3' | 'sonic-3' | 'sonic-3-latest' | 'sonic-3.5' | 'sonic-3.6' | 'tts-1' | 'gpt-4o-mini-tts' | 'speech-02-turbo' | 'speech-2.8-turbo' | 's1' | 's2-pro' | 's2.1-pro' | 'inworld-tts-2' | 'inworld-tts-2-flash' | null;
             /**
              * Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower
              * speech, while higher value means faster speech rate. If unset, default value 1
@@ -5330,7 +5513,9 @@ export declare namespace CallCreateWebCallParams {
             interface CustomSttConfig {
                 /**
                  * Endpointing timeout in milliseconds. Minimum is 100 for Azure, 10 for Deepgram,
-                 * 500 for Soniox, 100 for AssemblyAI.
+                 * 500 for Soniox, 100 for AssemblyAI. For AssemblyAI, this sets min_turn_silence
+                 * (100-3000 ms). max_turn_silence adds half of this value, rounded to the nearest
+                 * millisecond and bounded to 500-1000 ms, with a total cap of 3000 ms.
                  */
                 endpointing_ms: number;
                 /**
@@ -6206,7 +6391,7 @@ export declare namespace CallRegisterPhoneCallParams {
              * available voice models. Set to null to remove voice model selection, and default
              * ones will apply. Check out dashboard for more details of each voice model.
              */
-            voice_model?: 'eleven_flash_v2' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3' | 'sonic-3' | 'sonic-3-latest' | 'sonic-3.5' | 'tts-1' | 'gpt-4o-mini-tts' | 'speech-02-turbo' | 'speech-2.8-turbo' | 's1' | 's2-pro' | 's2.1-pro' | null;
+            voice_model?: 'eleven_flash_v2' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3' | 'sonic-3' | 'sonic-3-latest' | 'sonic-3.5' | 'sonic-3.6' | 'tts-1' | 'gpt-4o-mini-tts' | 'speech-02-turbo' | 'speech-2.8-turbo' | 's1' | 's2-pro' | 's2.1-pro' | 'inworld-tts-2' | 'inworld-tts-2-flash' | null;
             /**
              * Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower
              * speech, while higher value means faster speech rate. If unset, default value 1
@@ -6275,7 +6460,9 @@ export declare namespace CallRegisterPhoneCallParams {
             interface CustomSttConfig {
                 /**
                  * Endpointing timeout in milliseconds. Minimum is 100 for Azure, 10 for Deepgram,
-                 * 500 for Soniox, 100 for AssemblyAI.
+                 * 500 for Soniox, 100 for AssemblyAI. For AssemblyAI, this sets min_turn_silence
+                 * (100-3000 ms). max_turn_silence adds half of this value, rounded to the nearest
+                 * millisecond and bounded to 500-1000 ms, with a total cap of 3000 ms.
                  */
                 endpointing_ms: number;
                 /**
@@ -6779,6 +6966,13 @@ export declare namespace CallRegisterPhoneCallParams {
         }
     }
 }
+export interface CallTakeOverLiveParams {
+    /**
+     * The id of the live-listen participant to upgrade, obtained when joining via
+     * /v2/listen-live-call.
+     */
+    participant_id: string;
+}
 export interface CallUpdateLiveParams {
     /**
      * Live agent control. At least one of `additional_context` or `trigger_response`
@@ -6844,6 +7038,6 @@ export declare namespace CallUpdateLiveParams {
     }
 }
 export declare namespace Call {
-    export { type CallResponse as CallResponse, type PhoneCallResponse as PhoneCallResponse, type WebCallResponse as WebCallResponse, type CallListResponse as CallListResponse, type CallUpdateLiveResponse as CallUpdateLiveResponse, type CallUpdateParams as CallUpdateParams, type CallListParams as CallListParams, type CallCreatePhoneCallParams as CallCreatePhoneCallParams, type CallCreateWebCallParams as CallCreateWebCallParams, type CallRegisterPhoneCallParams as CallRegisterPhoneCallParams, type CallUpdateLiveParams as CallUpdateLiveParams, };
+    export { type CallResponse as CallResponse, type CreateWebCallResponse as CreateWebCallResponse, type PhoneCallResponse as PhoneCallResponse, type WebCallResponse as WebCallResponse, type CallListResponse as CallListResponse, type CallListenLiveResponse as CallListenLiveResponse, type CallTakeOverLiveResponse as CallTakeOverLiveResponse, type CallUpdateLiveResponse as CallUpdateLiveResponse, type CallUpdateParams as CallUpdateParams, type CallListParams as CallListParams, type CallCreatePhoneCallParams as CallCreatePhoneCallParams, type CallCreateWebCallParams as CallCreateWebCallParams, type CallRegisterPhoneCallParams as CallRegisterPhoneCallParams, type CallTakeOverLiveParams as CallTakeOverLiveParams, type CallUpdateLiveParams as CallUpdateLiveParams, };
 }
 //# sourceMappingURL=call.d.ts.map