retell-sdk 4.25.0 → 4.27.0

package/src/resources/agent.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../resource';
+import { isRequestOptions } from '../core';
 import * as Core from '../core';
 
 export class Agent extends APIResource {
@@ -14,8 +15,21 @@ export class Agent extends APIResource {
   /**
    * Retrieve details of a specific agent
    */
-  retrieve(agentId: string, options?: Core.RequestOptions): Core.APIPromise<AgentResponse> {
-    return this._client.get(`/get-agent/${agentId}`, options);
+  retrieve(
+    agentId: string,
+    query?: AgentRetrieveParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<AgentResponse>;
+  retrieve(agentId: string, options?: Core.RequestOptions): Core.APIPromise<AgentResponse>;
+  retrieve(
+    agentId: string,
+    query: AgentRetrieveParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<AgentResponse> {
+    if (isRequestOptions(query)) {
+      return this.retrieve(agentId, {}, query);
+    }
+    return this._client.get(`/get-agent/${agentId}`, { query, ...options });
   }
 
   /**
@@ -23,10 +37,15 @@ export class Agent extends APIResource {
    */
   update(
     agentId: string,
-    body: AgentUpdateParams,
+    params: AgentUpdateParams,
     options?: Core.RequestOptions,
   ): Core.APIPromise<AgentResponse> {
-    return this._client.patch(`/update-agent/${agentId}`, { body, ...options });
+    const { query_version, ...body } = params;
+    return this._client.patch(`/update-agent/${agentId}`, {
+      query: { version: query_version },
+      body,
+      ...options,
+    });
   }
 
   /**
@@ -45,6 +64,13 @@ export class Agent extends APIResource {
       headers: { Accept: '*/*', ...options?.headers },
     });
   }
+
+  /**
+   * Get all versions of an agent
+   */
+  getVersions(agentId: string, options?: Core.RequestOptions): Core.APIPromise<AgentGetVersionsResponse> {
+    return this._client.get(`/get-agent-versions/${agentId}`, options);
+  }
 }
 
 export interface AgentResponse {
@@ -326,6 +352,11 @@ export interface AgentResponse {
    */
   stt_mode?: 'fast' | 'accurate';
 
+  /**
+   * Version of the agent.
+   */
+  version?: number | null;
+
   /**
    * Optionally set the voice model used for the selected voice. Currently only
    * elevenlab voices have voice model selections. Set to null to remove voice model
@@ -523,6 +554,8 @@ export namespace AgentResponse {
 
 export type AgentListResponse = Array<AgentResponse>;
 
+export type AgentGetVersionsResponse = Array<AgentResponse>;
+
 export interface AgentCreateParams {
   /**
    * The Response Engine to attach to the agent. It is used to generate responses for
@@ -791,6 +824,11 @@ export interface AgentCreateParams {
    */
   stt_mode?: 'fast' | 'accurate';
 
+  /**
+   * Version of the agent.
+   */
+  version?: number | null;
+
   /**
    * Optionally set the voice model used for the selected voice. Currently only
    * elevenlab voices have voice model selections. Set to null to remove voice model
@@ -986,15 +1024,27 @@ export namespace AgentCreateParams {
   }
 }
 
+export interface AgentRetrieveParams {
+  /**
+   * Optional version of the API to use for this request. Default to 0.
+   */
+  version?: number;
+}
+
 export interface AgentUpdateParams {
   /**
-   * The name of the agent. Only used for your own reference.
+   * Query param: Optional version of the API to use for this request. Default to 0.
+   */
+  query_version?: number;
+
+  /**
+   * Body param: The name of the agent. Only used for your own reference.
    */
   agent_name?: string | null;
 
   /**
-   * If set, will add ambient environment sound to the call to make experience more
-   * realistic. Currently supports the following options:
+   * Body param: If set, will add ambient environment sound to the call to make
+   * experience more realistic. Currently supports the following options:
    *
    * - `coffee-shop`: Coffee shop ambience with people chatting in background.
    *   [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/coffee-shop.wav)
@@ -1027,24 +1077,24 @@ export interface AgentUpdateParams {
     | null;
 
   /**
-   * If set, will control the volume of the ambient sound. Value ranging from [0,2].
-   * Lower value means quieter ambient sound, while higher value means louder ambient
-   * sound. If unset, default value 1 will apply.
+   * Body param: If set, will control the volume of the ambient sound. Value ranging
+   * from [0,2]. Lower value means quieter ambient sound, while higher value means
+   * louder ambient sound. If unset, default value 1 will apply.
    */
   ambient_sound_volume?: number;
 
   /**
-   * Only applicable when enable_backchannel is true. Controls how often the agent
-   * would backchannel when a backchannel is possible. Value ranging from [0,1].
-   * Lower value means less frequent backchannel, while higher value means more
-   * frequent backchannel. If unset, default value 0.8 will apply.
+   * Body param: Only applicable when enable_backchannel is true. Controls how often
+   * the agent would backchannel when a backchannel is possible. Value ranging from
+   * [0,1]. Lower value means less frequent backchannel, while higher value means
+   * more frequent backchannel. If unset, default value 0.8 will apply.
    */
   backchannel_frequency?: number;
 
   /**
-   * Only applicable when enable_backchannel is true. A list of words that the agent
-   * would use as backchannel. If not set, default backchannel words will apply.
-   * Check out
+   * Body param: Only applicable when enable_backchannel is true. A list of words
+   * that the agent would use as backchannel. If not set, default backchannel words
+   * will apply. Check out
    * [backchannel default words](/agent/interaction-configuration#backchannel) for
    * more details. Note that certain voices do not work too well with certain words,
    * so it's recommended to expeirment before adding any words.
@@ -1052,69 +1102,70 @@ export interface AgentUpdateParams {
   backchannel_words?: Array<string> | null;
 
   /**
-   * If set, will delay the first message by the specified amount of milliseconds, so
-   * that it gives user more time to prepare to take the call. Valid range is [0,
-   * 5000]. If not set or set to 0, agent will speak immediately. Only applicable
-   * when agent speaks first.
+   * Body param: If set, will delay the first message by the specified amount of
+   * milliseconds, so that it gives user more time to prepare to take the call. Valid
+   * range is [0, 5000]. If not set or set to 0, agent will speak immediately. Only
+   * applicable when agent speaks first.
    */
   begin_message_delay_ms?: number;
 
   /**
-   * Provide a customized list of keywords to bias the transcriber model, so that
-   * these words are more likely to get transcribed. Commonly used for names, brands,
-   * street, etc.
+   * Body param: Provide a customized list of keywords to bias the transcriber model,
+   * so that these words are more likely to get transcribed. Commonly used for names,
+   * brands, street, etc.
    */
   boosted_keywords?: Array<string> | null;
 
   /**
-   * Controls whether the agent would backchannel (agent interjects the speaker with
-   * phrases like "yeah", "uh-huh" to signify interest and engagement). Backchannel
-   * when enabled tends to show up more in longer user utterances. If not set, agent
-   * will not backchannel.
+   * Body param: Controls whether the agent would backchannel (agent interjects the
+   * speaker with phrases like "yeah", "uh-huh" to signify interest and engagement).
+   * Backchannel when enabled tends to show up more in longer user utterances. If not
+   * set, agent will not backchannel.
    */
   enable_backchannel?: boolean;
 
   /**
-   * If set to true, will format transcription to number, date, email, etc. If set to
-   * false, will return transcripts in raw words. If not set, default value of true
-   * will apply. This currently only applies to English.
+   * Body param: If set to true, will format transcription to number, date, email,
+   * etc. If set to false, will return transcripts in raw words. If not set, default
+   * value of true will apply. This currently only applies to English.
    */
   enable_transcription_formatting?: boolean;
 
   /**
-   * If set to true, will detect whether the call enters a voicemail. Note that this
-   * feature is only available for phone calls.
+   * Body param: If set to true, will detect whether the call enters a voicemail.
+   * Note that this feature is only available for phone calls.
    */
   enable_voicemail_detection?: boolean;
 
   /**
-   * If users stay silent for a period after agent speech, end the call. The minimum
-   * value allowed is 10,000 ms (10 s). By default, this is set to 600000 (10 min).
+   * Body param: If users stay silent for a period after agent speech, end the call.
+   * The minimum value allowed is 10,000 ms (10 s). By default, this is set to 600000
+   * (10 min).
    */
   end_call_after_silence_ms?: number;
 
   /**
-   * When TTS provider for the selected voice is experiencing outages, we would use
-   * fallback voices listed here for the agent. Voice id and the fallback voice ids
-   * must be from different TTS providers. The system would go through the list in
-   * order, if the first one in the list is also having outage, it would use the next
-   * one. Set to null to remove voice fallback for the agent.
+   * Body param: When TTS provider for the selected voice is experiencing outages, we
+   * would use fallback voices listed here for the agent. Voice id and the fallback
+   * voice ids must be from different TTS providers. The system would go through the
+   * list in order, if the first one in the list is also having outage, it would use
+   * the next one. Set to null to remove voice fallback for the agent.
    */
   fallback_voice_ids?: Array<string> | null;
 
   /**
-   * Controls how sensitive the agent is to user interruptions. Value ranging from
-   * [0,1]. Lower value means it will take longer / more words for user to interrupt
-   * agent, while higher value means it's easier for user to interrupt agent. If
-   * unset, default value 1 will apply. When this is set to 0, agent would never be
-   * interrupted.
+   * Body param: Controls how sensitive the agent is to user interruptions. Value
+   * ranging from [0,1]. Lower value means it will take longer / more words for user
+   * to interrupt agent, while higher value means it's easier for user to interrupt
+   * agent. If unset, default value 1 will apply. When this is set to 0, agent would
+   * never be interrupted.
    */
   interruption_sensitivity?: number;
 
   /**
-   * Specifies what language (and dialect) the speech recognition will operate in.
-   * For instance, selecting `en-GB` optimizes speech recognition for British
-   * English. If unset, will use default value `en-US`. Select `multi` for
+   * Body param: Specifies what language (and dialect) the speech recognition will
+   * operate in. For instance, selecting `en-GB` optimizes speech recognition for
+   * British English. If unset, will use default value `en-US`. Select `multi` for
    * multilingual support, currently this supports Spanish and English.
    */
   language?:
@@ -1154,34 +1205,35 @@ export interface AgentUpdateParams {
     | 'multi';
 
   /**
-   * Maximum allowed length for the call, will force end the call if reached. The
-   * minimum value allowed is 60,000 ms (1 min), and maximum value allowed is
-   * 7,200,000 (2 hours). By default, this is set to 3,600,000 (1 hour).
+   * Body param: Maximum allowed length for the call, will force end the call if
+   * reached. The minimum value allowed is 60,000 ms (1 min), and maximum value
+   * allowed is 7,200,000 (2 hours). By default, this is set to 3,600,000 (1 hour).
    */
   max_call_duration_ms?: number;
 
   /**
-   * If set to true, will normalize the some part of text (number, currency, date,
-   * etc) to spoken to its spoken form for more consistent speech synthesis
-   * (sometimes the voice synthesize system itself might read these wrong with the
-   * raw text). For example, it will convert "Call my number 2137112342 on Jul 5th,
-   * 2024 for the $24.12 payment" to "Call my number two one three seven one one two
-   * three four two on july fifth, twenty twenty four for the twenty four dollars
-   * twelve cents payment" before starting audio generation.
+   * Body param: If set to true, will normalize the some part of text (number,
+   * currency, date, etc) to spoken to its spoken form for more consistent speech
+   * synthesis (sometimes the voice synthesize system itself might read these wrong
+   * with the raw text). For example, it will convert "Call my number 2137112342 on
+   * Jul 5th, 2024 for the $24.12 payment" to "Call my number two one three seven one
+   * one two three four two on july fifth, twenty twenty four for the twenty four
+   * dollars twelve cents payment" before starting audio generation.
    */
   normalize_for_speech?: boolean;
 
   /**
-   * Whether this agent opts out of sensitive data storage like transcript,
-   * recording, logging, inbound/outbound phone numbers, etc. These data can still be
-   * accessed securely via webhooks. If not set, default value of false will apply.
+   * Body param: Whether this agent opts out of sensitive data storage like
+   * transcript, recording, logging, inbound/outbound phone numbers, etc. These data
+   * can still be accessed securely via webhooks. If not set, default value of false
+   * will apply.
    */
   opt_out_sensitive_data_storage?: boolean;
 
   /**
-   * Post call analysis data to extract from the call. This data will augment the
-   * pre-defined variables extracted in the call analysis. This will be available
-   * after the call ends.
+   * Body param: Post call analysis data to extract from the call. This data will
+   * augment the pre-defined variables extracted in the call analysis. This will be
+   * available after the call ends.
    */
   post_call_analysis_data?: Array<
     | AgentUpdateParams.StringAnalysisData
@@ -1191,36 +1243,38 @@ export interface AgentUpdateParams {
   > | null;
 
   /**
-   * The model to use for post call analysis. Currently only supports gpt-4o-mini and
-   * gpt-4o. Default to gpt-4o-mini.
+   * Body param: The model to use for post call analysis. Currently only supports
+   * gpt-4o-mini and gpt-4o. Default to gpt-4o-mini.
    */
   post_call_analysis_model?: 'gpt-4o-mini' | 'gpt-4o';
 
   /**
-   * A list of words / phrases and their pronunciation to be used to guide the audio
-   * synthesize for consistent pronunciation. Currently only supported for English &
-   * 11labs voices. Set to null to remove pronunciation dictionary from this agent.
+   * Body param: A list of words / phrases and their pronunciation to be used to
+   * guide the audio synthesize for consistent pronunciation. Currently only
+   * supported for English & 11labs voices. Set to null to remove pronunciation
+   * dictionary from this agent.
    */
   pronunciation_dictionary?: Array<AgentUpdateParams.PronunciationDictionary> | null;
 
   /**
-   * If set, controls how many times agent would remind user when user is
+   * Body param: If set, controls how many times agent would remind user when user is
    * unresponsive. Must be a non negative integer. If unset, default value of 1 will
    * apply (remind once). Set to 0 to disable agent from reminding.
    */
   reminder_max_count?: number;
 
   /**
-   * If set (in milliseconds), will trigger a reminder to the agent to speak if the
-   * user has been silent for the specified duration after some agent speech. Must be
-   * a positive number. If unset, default value of 10000 ms (10 s) will apply.
+   * Body param: If set (in milliseconds), will trigger a reminder to the agent to
+   * speak if the user has been silent for the specified duration after some agent
+   * speech. Must be a positive number. If unset, default value of 10000 ms (10 s)
+   * will apply.
    */
   reminder_trigger_ms?: number;
 
   /**
-   * The Response Engine to attach to the agent. It is used to generate responses for
-   * the agent. You need to create a Response Engine first before attaching it to an
-   * agent.
+   * Body param: The Response Engine to attach to the agent. It is used to generate
+   * responses for the agent. You need to create a Response Engine first before
+   * attaching it to an agent.
    */
   response_engine?:
     | AgentUpdateParams.ResponseEngineRetellLm
@@ -1228,37 +1282,42 @@ export interface AgentUpdateParams {
     | AgentUpdateParams.ResponseEngineConversationFlow;
 
   /**
-   * Controls how responsive is the agent. Value ranging from [0,1]. Lower value
-   * means less responsive agent (wait more, respond slower), while higher value
-   * means faster exchanges (respond when it can). If unset, default value 1 will
-   * apply.
+   * Body param: Controls how responsive is the agent. Value ranging from [0,1].
+   * Lower value means less responsive agent (wait more, respond slower), while
+   * higher value means faster exchanges (respond when it can). If unset, default
+   * value 1 will apply.
    */
   responsiveness?: number;
 
   /**
-   * If set, the phone ringing will last for the specified amount of milliseconds.
-   * This applies for both outbound call ringtime, and call transfer ringtime.
-   * Default to 30000 (30 s). Valid range is [5000, 90000].
+   * Body param: If set, the phone ringing will last for the specified amount of
+   * milliseconds. This applies for both outbound call ringtime, and call transfer
+   * ringtime. Default to 30000 (30 s). Valid range is [5000, 90000].
    */
   ring_duration_ms?: number;
 
   /**
-   * If set, determines whether speech to text should focus on latency or accuracy.
-   * Default to fast mode.
+   * Body param: If set, determines whether speech to text should focus on latency or
+   * accuracy. Default to fast mode.
    */
   stt_mode?: 'fast' | 'accurate';
 
   /**
-   * Unique voice id used for the agent. Find list of available voices and their
-   * preview in Dashboard.
+   * Body param: Version of the agent.
+   */
+  body_version?: number | null;
+
+  /**
+   * Body param: Unique voice id used for the agent. Find list of available voices
+   * and their preview in Dashboard.
    */
   voice_id?: string;
 
   /**
-   * Optionally set the voice model used for the selected voice. Currently only
-   * elevenlab voices have voice model selections. Set to null to remove voice model
-   * selection, and default ones will apply. Check out the dashboard for details on
-   * each voice model.
+   * Body param: Optionally set the voice model used for the selected voice.
+   * Currently only elevenlab voices have voice model selections. Set to null to
+   * remove voice model selection, and default ones will apply. Check out the
+   * dashboard for details on each voice model.
    */
   voice_model?:
     | 'eleven_turbo_v2'
@@ -1271,47 +1330,47 @@ export interface AgentUpdateParams {
     | 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
-   * will apply.
+   * Body param: 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 will apply.
    */
   voice_speed?: number;
 
   /**
-   * Controls how stable the voice is. Value ranging from [0,2]. Lower value means
-   * more stable, and higher value means more variant speech generation. Currently
-   * this setting only applies to `11labs` voices. If unset, default value 1 will
-   * apply.
+   * Body param: Controls how stable the voice is. Value ranging from [0,2]. Lower
+   * value means more stable, and higher value means more variant speech generation.
+   * Currently this setting only applies to `11labs` voices. If unset, default value
+   * 1 will apply.
    */
   voice_temperature?: number;
 
   /**
-   * Configures when to stop running voicemail detection, as it becomes unlikely to
-   * hit voicemail after a couple minutes, and keep running it will only have
-   * negative impact. The minimum value allowed is 5,000 ms (5 s), and maximum value
-   * allowed is 180,000 (3 minutes). By default, this is set to 30,000 (30 s).
+   * Body param: Configures when to stop running voicemail detection, as it becomes
+   * unlikely to hit voicemail after a couple minutes, and keep running it will only
+   * have negative impact. The minimum value allowed is 5,000 ms (5 s), and maximum
+   * value allowed is 180,000 (3 minutes). By default, this is set to 30,000 (30 s).
    */
   voicemail_detection_timeout_ms?: number;
 
   /**
-   * The message to be played when the call enters a voicemail. Note that this
-   * feature is only available for phone calls. If you want to hangup after hitting
-   * voicemail, set this to empty string.
+   * Body param: The message to be played when the call enters a voicemail. Note that
+   * this feature is only available for phone calls. If you want to hangup after
+   * hitting voicemail, set this to empty string.
    */
   voicemail_message?: string;
 
   /**
-   * If set, will control the volume of the agent. Value ranging from [0,2]. Lower
-   * value means quieter agent speech, while higher value means louder agent speech.
-   * If unset, default value 1 will apply.
+   * Body param: If set, will control the volume of the agent. Value ranging from
+   * [0,2]. Lower value means quieter agent speech, while higher value means louder
+   * agent speech. If unset, default value 1 will apply.
    */
   volume?: number;
 
   /**
-   * The webhook for agent to listen to call events. See what events it would get at
-   * [webhook doc](/features/webhook). If set, will binds webhook events for this
-   * agent to the specified url, and will ignore the account level webhook for this
-   * agent. Set to `null` to remove webhook url from this agent.
+   * Body param: The webhook for agent to listen to call events. See what events it
+   * would get at [webhook doc](/features/webhook). If set, will binds webhook events
+   * for this agent to the specified url, and will ignore the account level webhook
+   * for this agent. Set to `null` to remove webhook url from this agent.
    */
   webhook_url?: string | null;
 }
@@ -1453,7 +1512,9 @@ export declare namespace Agent {
   export {
     type AgentResponse as AgentResponse,
     type AgentListResponse as AgentListResponse,
+    type AgentGetVersionsResponse as AgentGetVersionsResponse,
     type AgentCreateParams as AgentCreateParams,
+    type AgentRetrieveParams as AgentRetrieveParams,
     type AgentUpdateParams as AgentUpdateParams,
   };
 }

package/src/resources/call.ts

@@ -240,6 +240,11 @@ export interface PhoneCallResponse {
     | PhoneCallResponse.ToolCallResultUtterance
     | PhoneCallResponse.DtmfUtterance
   >;
+
+  /**
+   * The version of the agent.
+   */
+  version?: number | null;
 }
 
 export namespace PhoneCallResponse {
@@ -953,6 +958,11 @@ export interface WebCallResponse {
     | WebCallResponse.ToolCallResultUtterance
     | WebCallResponse.DtmfUtterance
   >;
+
+  /**
+   * The version of the agent.
+   */
+  version?: number | null;
 }
 
 export namespace WebCallResponse {
@@ -1639,6 +1649,11 @@ export namespace CallListParams {
      * Only retrieve calls with specific user sentiment(s).
      */
     user_sentiment?: Array<'Negative' | 'Positive' | 'Neutral' | 'Unknown'>;
+
+    /**
+     * The version of the agent to use for the call.
+     */
+    version?: Array<number>;
   }
 
   export namespace FilterCriteria {
@@ -1694,6 +1709,13 @@ export interface CallCreatePhoneCallParams {
    */
   override_agent_id?: string;
 
+  /**
+   * For this particular call, override the agent version used with this version.
+   * This does not bind the agent version to this number, this is for one time
+   * override.
+   */
+  override_agent_version?: number;
+
   /**
    * Add optional dynamic variables in key value pairs of string that injects into
    * your Response Engine prompt and tool description. Only applicable for Response
@@ -1709,6 +1731,11 @@ export interface CallCreateWebCallParams {
    */
   agent_id: string;
 
+  /**
+   * The version of the agent to use for the call.
+   */
+  agent_version?: number;
+
   /**
    * An arbitrary object for storage purpose only. You can put anything here like
    * your internal customer id associated with the call. Not used for processing. You
@@ -1730,6 +1757,11 @@ export interface CallRegisterPhoneCallParams {
    */
   agent_id: string;
 
+  /**
+   * The version of the agent to use for the call.
+   */
+  agent_version?: number;
+
   /**
    * Direction of the phone call. Stored for tracking purpose.
    */

package/src/resources/index.ts

@@ -4,7 +4,9 @@ export {
   Agent,
   type AgentResponse,
   type AgentListResponse,
+  type AgentGetVersionsResponse,
   type AgentCreateParams,
+  type AgentRetrieveParams,
   type AgentUpdateParams,
 } from './agent';
 export { BatchCall, type BatchCallResponse, type BatchCallCreateBatchCallParams } from './batch-call';
@@ -33,6 +35,7 @@ export {
   type LlmResponse,
   type LlmListResponse,
   type LlmCreateParams,
+  type LlmRetrieveParams,
   type LlmUpdateParams,
 } from './llm';
 export {