telnyx 7.15.0 → 7.17.0

package/src/resources/ai/assistants/canary-deploys.ts

@@ -82,10 +82,18 @@ export class CanaryDeploys extends APIResource {
    */
   create(
     assistantID: string,
-    body: CanaryDeployCreateParams,
+    params: CanaryDeployCreateParams,
     options?: RequestOptions,
   ): APIPromise<CanaryDeployResponse> {
-    return this._client.post(path`/ai/assistants/${assistantID}/canary-deploys`, { body, ...options });
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post(path`/ai/assistants/${assistantID}/canary-deploys`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -240,7 +248,22 @@ export interface Serve {
 }
 
 export interface CanaryDeployCreateParams {
+  /**
+   * Body param
+   */
   rules?: Array<RuleInput>;
+
+  /**
+   * 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;
 }
 
 export interface CanaryDeployUpdateParams {

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

@@ -12,6 +12,7 @@ export {
   type AuthenticationMethod,
   type BooleanOpExpression,
   type ComparisonExpression,
+  type ConversationFlow,
   type ConversationFlowReq,
   type EnabledFeatures,
   type Expression,
@@ -20,6 +21,8 @@ export {
   type FallbackConfig,
   type FallbackConfigReq,
   type FlowEdge,
+  type FlowNode,
+  type FlowNodeReq,
   type HangupTool,
   type HangupToolParams,
   type ImportMetadata,
@@ -37,8 +40,12 @@ export {
   type PrivacySettings,
   type PromptSyncStatus,
   type RetrievalTool,
+  type SpeakNode,
+  type SpeakNodeReq,
   type StartSpeakingPlan,
   type TelephonySettings,
+  type ToolNode,
+  type ToolNodeReq,
   type TranscriptionEndpointingPlan,
   type TranscriptionSettings,
   type TranscriptionSettingsConfig,
@@ -55,6 +62,7 @@ export {
   type AssistantRetrieveParams,
   type AssistantUpdateParams,
   type AssistantChatParams,
+  type AssistantCloneParams,
   type AssistantSendSMSParams,
 } from './assistants';
 export {

package/src/resources/ai/assistants/scheduled-events.ts

@@ -60,10 +60,18 @@ export class ScheduledEvents extends APIResource {
    */
   create(
     assistantID: string,
-    body: ScheduledEventCreateParams,
+    params: ScheduledEventCreateParams,
     options?: RequestOptions,
   ): APIPromise<ScheduledEventResponse> {
-    return this._client.post(path`/ai/assistants/${assistantID}/scheduled_events`, { body, ...options });
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post(path`/ai/assistants/${assistantID}/scheduled_events`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -87,7 +95,8 @@ export class ScheduledEvents extends APIResource {
   }
 
   /**
-   * Retrieve a scheduled event by event ID
+   * Returns the details of a single scheduled event configured for the specified
+   * assistant.
    *
    * @example
    * ```ts
@@ -278,53 +287,74 @@ export interface ScheduledEventListParams extends DefaultFlatPaginationParams {
 
 export interface ScheduledEventCreateParams {
   /**
-   * The datetime at which the event should be scheduled. Formatted as ISO 8601.
+   * Body param: The datetime at which the event should be scheduled. Formatted as
+   * ISO 8601.
    */
   scheduled_at_fixed_datetime: string;
 
   /**
-   * The phone number, SIP URI, to schedule the call or text from.
+   * Body param: The phone number, SIP URI, to schedule the call or text from.
    */
   telnyx_agent_target: string;
 
+  /**
+   * Body param
+   */
   telnyx_conversation_channel: ConversationChannelType;
 
   /**
-   * The phone number, SIP URI, to schedule the call or text to.
+   * Body param: The phone number, SIP URI, to schedule the call or text to.
    */
   telnyx_end_user_target: string;
 
   /**
-   * Per-call telephony overrides applied when a scheduled phone-call event
-   * dispatches. Phone-call events only. New per-call dispatch options should be
-   * added here rather than as top-level event fields.
+   * Body param: Per-call telephony overrides applied when a scheduled phone-call
+   * event dispatches. Phone-call events only. New per-call dispatch options should
+   * be added here rather than as top-level event fields.
    */
   call_settings?: ScheduledCallSettings;
 
   /**
-   * Metadata associated with the conversation. Telnyx provides several pieces of
-   * metadata, but customers can also add their own.
+   * Body param: Metadata associated with the conversation. Telnyx provides several
+   * pieces of metadata, but customers can also add their own.
    */
   conversation_metadata?: { [key: string]: string | number | boolean };
 
   /**
-   * A map of dynamic variable names to values. These variables can be referenced in
-   * the assistant's instructions and messages using {{variable_name}} syntax.
+   * Body param: A map of dynamic variable names to values. These variables can be
+   * referenced in the assistant's instructions and messages using {{variable_name}}
+   * syntax.
    */
   dynamic_variables?: { [key: string]: string };
 
   /**
-   * Configure number of retries on client errors: busy, no-answer, failed, canceled
-   * (caller hung up before the callee answered)
+   * Body param: Configure number of retries on client errors: busy, no-answer,
+   * failed, canceled (caller hung up before the callee answered)
    */
   max_retries_client_errors?: number;
 
+  /**
+   * Body param
+   */
   retry_interval_secs?: number;
 
   /**
-   * Required for sms scheduled events. The text to be sent to the end user.
+   * Body param: Required for sms scheduled events. The text to be sent to the end
+   * user.
    */
   text?: string;
+
+  /**
+   * 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;
 }
 
 export interface ScheduledEventDeleteParams {

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

@@ -37,7 +37,8 @@ export class Tags extends APIResource {
   }
 
   /**
-   * Remove a tag from an AI assistant.
+   * Removes the specified tag from the AI assistant and returns the assistant's
+   * updated tag list.
    *
    * @example
    * ```ts

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

@@ -7,6 +7,7 @@ import {
   type DefaultFlatPaginationParams,
   PagePromise,
 } from '../../../../core/pagination';
+import { buildHeaders } from '../../../../internal/headers';
 import { RequestOptions } from '../../../../internal/request-options';
 import { path } from '../../../../internal/utils/path';
 
@@ -51,10 +52,18 @@ export class Runs extends APIResource {
    */
   trigger(
     testID: string,
-    body: RunTriggerParams | null | undefined = {},
+    params: RunTriggerParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<TestRunResponse> {
-    return this._client.post(path`/ai/assistants/tests/${testID}/runs`, { body, ...options });
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params ?? {};
+    return this._client.post(path`/ai/assistants/tests/${testID}/runs`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -190,11 +199,23 @@ export interface RunListParams extends DefaultFlatPaginationParams {
 
 export interface RunTriggerParams {
   /**
-   * Optional assistant version ID to use for this test run. If provided, the version
-   * must exist or a 400 error will be returned. If not provided, test will run on
-   * main version
+   * Body param: Optional assistant version ID to use for this test run. If provided,
+   * the version must exist or a 400 error will be returned. If not provided, test
+   * will run on main version
    */
   destination_version_id?: string;
+
+  /**
+   * 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;
 }
 
 export interface RunRetrieveParams {

package/src/resources/ai/assistants/tests/test-suites/runs.ts

@@ -9,6 +9,7 @@ import {
   type DefaultFlatPaginationParams,
   PagePromise,
 } from '../../../../../core/pagination';
+import { buildHeaders } from '../../../../../internal/headers';
 import { RequestOptions } from '../../../../../internal/request-options';
 import { path } from '../../../../../internal/utils/path';
 
@@ -55,10 +56,18 @@ export class Runs extends APIResource {
    */
   trigger(
     suiteName: string,
-    body: RunTriggerParams | null | undefined = {},
+    params: RunTriggerParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<RunTriggerResponse> {
-    return this._client.post(path`/ai/assistants/tests/test-suites/${suiteName}/runs`, { body, ...options });
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params ?? {};
+    return this._client.post(path`/ai/assistants/tests/test-suites/${suiteName}/runs`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 }
 
@@ -106,11 +115,23 @@ export interface RunListParams extends DefaultFlatPaginationParams {
 
 export interface RunTriggerParams {
   /**
-   * Optional assistant version ID to use for all test runs in this suite. If
-   * provided, the version must exist or a 400 error will be returned. If not
-   * provided, test will run on main version
+   * Body param: Optional assistant version ID to use for all test runs in this
+   * suite. If provided, the version must exist or a 400 error will be returned. If
+   * not provided, test will run on main version
    */
   destination_version_id?: string;
+
+  /**
+   * 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;
 }
 
 export declare namespace Runs {

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

@@ -78,8 +78,16 @@ export class Tests extends APIResource {
    *   });
    * ```
    */
-  create(body: TestCreateParams, options?: RequestOptions): APIPromise<AssistantTest> {
-    return this._client.post('/ai/assistants/tests', { body, ...options });
+  create(params: TestCreateParams, options?: RequestOptions): APIPromise<AssistantTest> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/ai/assistants/tests', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -230,52 +238,64 @@ export interface TestListParams extends DefaultFlatPaginationParams {
 
 export interface TestCreateParams {
   /**
-   * The target destination for the test conversation. Format depends on the channel:
-   * phone number for SMS/voice, webhook URL for web chat, etc.
+   * Body param: The target destination for the test conversation. Format depends on
+   * the channel: phone number for SMS/voice, webhook URL for web chat, etc.
    */
   destination: string;
 
   /**
-   * Detailed instructions that define the test scenario and what the assistant
-   * should accomplish. This guides the test execution and evaluation.
+   * Body param: Detailed instructions that define the test scenario and what the
+   * assistant should accomplish. This guides the test execution and evaluation.
    */
   instructions: string;
 
   /**
-   * A descriptive name for the assistant test. This will be used to identify the
-   * test in the UI and reports.
+   * Body param: A descriptive name for the assistant test. This will be used to
+   * identify the test in the UI and reports.
    */
   name: string;
 
   /**
-   * Evaluation criteria used to assess the assistant's performance. Each rubric item
-   * contains a name and specific criteria for evaluation.
+   * Body param: Evaluation criteria used to assess the assistant's performance. Each
+   * rubric item contains a name and specific criteria for evaluation.
    */
   rubric: Array<TestCreateParams.Rubric>;
 
   /**
-   * Optional detailed description of what this test evaluates and its purpose. Helps
-   * team members understand the test's objectives.
+   * Body param: Optional detailed description of what this test evaluates and its
+   * purpose. Helps team members understand the test's objectives.
    */
   description?: string;
 
   /**
-   * Maximum duration in seconds that the test conversation should run before timing
-   * out. If not specified, uses system default timeout.
+   * Body param: Maximum duration in seconds that the test conversation should run
+   * before timing out. If not specified, uses system default timeout.
    */
   max_duration_seconds?: number;
 
   /**
-   * The communication channel through which the test will be conducted. Determines
-   * how the assistant will receive and respond to test messages.
+   * Body param: The communication channel through which the test will be conducted.
+   * Determines how the assistant will receive and respond to test messages.
    */
   telnyx_conversation_channel?: TelnyxConversationChannel;
 
   /**
-   * Optional test suite name to group related tests together. Useful for organizing
-   * tests by feature, team, or release cycle.
+   * Body param: Optional test suite name to group related tests together. Useful for
+   * organizing tests by feature, team, or release cycle.
    */
   test_suite?: string;
+
+  /**
+   * 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;
 }
 
 export namespace TestCreateParams {

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

@@ -10,7 +10,9 @@ import { path } from '../../../internal/utils/path';
  */
 export class Tools extends APIResource {
   /**
-   * Test a webhook tool for an assistant
+   * Executes a test invocation of the specified webhook tool for the assistant and
+   * returns the outcome, so you can verify the webhook's behavior before relying on
+   * it in conversations.
    *
    * @example
    * ```ts
@@ -30,7 +32,8 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Detach a tool from an AI assistant.
+   * Detaches the specified tool from the AI assistant so the assistant can no longer
+   * invoke it.
    *
    * @example
    * ```ts

package/src/resources/ai/collections/collections.ts

@@ -142,18 +142,27 @@ export class Collections extends APIResource {
    *
    * @example
    * ```ts
-   * const response =
-   *   await client.ai.collections.retrieveDocuments(
-   *     'support-transcripts',
-   *   );
+   * // Automatically fetches more pages as needed.
+   * for await (const collectionRetrieveDocumentsResponse of client.ai.collections.retrieveDocuments(
+   *   'support-transcripts',
+   * )) {
+   *   // ...
+   * }
    * ```
    */
   retrieveDocuments(
     slug: string,
     query: CollectionRetrieveDocumentsParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<CollectionRetrieveDocumentsResponse> {
-    return this._client.get(path`/ai/collections/${slug}/documents`, { query, ...options });
+  ): PagePromise<
+    CollectionRetrieveDocumentsResponsesDefaultFlatPagination,
+    CollectionRetrieveDocumentsResponse
+  > {
+    return this._client.getAPIList(
+      path`/ai/collections/${slug}/documents`,
+      DefaultFlatPagination<CollectionRetrieveDocumentsResponse>,
+      { query, ...options },
+    );
   }
 
   /**
@@ -197,6 +206,9 @@ export class Collections extends APIResource {
 
 export type CollectionsDefaultFlatPagination = DefaultFlatPagination<Collection>;
 
+export type CollectionRetrieveDocumentsResponsesDefaultFlatPagination =
+  DefaultFlatPagination<CollectionRetrieveDocumentsResponse>;
+
 export interface Collection {
   created_at?: string;
 
@@ -227,65 +239,39 @@ export interface CollectionEnvelope {
 }
 
 export interface CollectionRetrieveDocumentsResponse {
-  data?: Array<CollectionRetrieveDocumentsResponse.Data>;
-
-  meta?: CollectionRetrieveDocumentsResponse.Meta;
-}
-
-export namespace CollectionRetrieveDocumentsResponse {
-  export interface Data {
-    id?: string;
-
-    chunk_index?: number;
-
-    chunk_total?: number;
-
-    ingested_at?: string;
-
-    metadata?: { [key: string]: unknown };
-
-    organization_id?: string;
-
-    record_created_at?: string;
+  id?: string;
 
-    record_id?: string;
+  chunk_index?: number;
 
-    /**
-     * The source record kind this chunk came from (e.g. `voice`, `meeting_bot`,
-     * `message`).
-     */
-    record_type?: string;
+  chunk_total?: number;
 
-    region?: string;
+  ingested_at?: string;
 
-    /**
-     * Relevance score (higher = more relevant) for ranked search. `0.0` for plain
-     * catalog listings (when `query` is omitted).
-     */
-    score?: number;
+  metadata?: { [key: string]: unknown };
 
-    text?: string;
+  organization_id?: string;
 
-    user_id?: string;
-  }
-
-  export interface Meta {
-    collection_slug?: string;
+  record_created_at?: string;
 
-    page_number?: number;
+  record_id?: string;
 
-    page_size?: number;
-
-    retrieval_type?: string;
+  /**
+   * The source record kind this chunk came from (e.g. `voice`, `meeting_bot`,
+   * `message`).
+   */
+  record_type?: string;
 
-    searched_sources?: Array<string>;
+  region?: string;
 
-    top_k?: number;
+  /**
+   * Relevance score (higher = more relevant) for ranked search. `0.0` for plain
+   * catalog listings (when `query` is omitted).
+   */
+  score?: number;
 
-    total_pages?: number;
+  text?: string;
 
-    total_results?: number;
-  }
+  user_id?: string;
 }
 
 export interface CollectionListParams extends DefaultFlatPaginationParams {}
@@ -317,7 +303,7 @@ export interface CollectionCreateParams {
   sources?: Array<SourcesAPI.SourceRequest>;
 }
 
-export interface CollectionRetrieveDocumentsParams {
+export interface CollectionRetrieveDocumentsParams extends DefaultFlatPaginationParams {
   /**
    * Field filters applied before ranking, using `filter[field][operator]=value`.
    * Supported operators: `eq` (default), `in`, `gte`, `gt`, `lte`, `lt`, `contains`.
@@ -327,16 +313,6 @@ export interface CollectionRetrieveDocumentsParams {
    */
   filter?: { [key: string]: unknown };
 
-  /**
-   * Page number to return (1-based). Defaults to 1.
-   */
-  'page[number]'?: number;
-
-  /**
-   * Number of results per page. Defaults to 20.
-   */
-  'page[size]'?: number;
-
   /**
    * Natural-language search query. When provided, the text is matched against the
    * collection's document chunks using the collection's `retrieval_type` (vector or
@@ -378,6 +354,7 @@ export declare namespace Collections {
     type CollectionEnvelope as CollectionEnvelope,
     type CollectionRetrieveDocumentsResponse as CollectionRetrieveDocumentsResponse,
     type CollectionsDefaultFlatPagination as CollectionsDefaultFlatPagination,
+    type CollectionRetrieveDocumentsResponsesDefaultFlatPagination as CollectionRetrieveDocumentsResponsesDefaultFlatPagination,
     type CollectionListParams as CollectionListParams,
     type CollectionCreateParams as CollectionCreateParams,
     type CollectionRetrieveDocumentsParams as CollectionRetrieveDocumentsParams,

package/src/resources/ai/collections/index.ts

@@ -10,6 +10,7 @@ export {
   type CollectionRetrieveDocumentsParams,
   type CollectionUpdateParams,
   type CollectionsDefaultFlatPagination,
+  type CollectionRetrieveDocumentsResponsesDefaultFlatPagination,
 } from './collections';
 export {
   Settings,

package/src/resources/ai/collections/sources.ts

@@ -25,7 +25,9 @@ export class Sources extends APIResource {
   }
 
   /**
-   * Attaches a new source to a collection.
+   * Attaches a new content source to the specified collection and returns the
+   * created source. The source's content is ingested and embedded so it becomes
+   * searchable within the collection.
    *
    * @example
    * ```ts