telnyx 7.13.0 → 7.14.0

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

@@ -119,8 +119,9 @@ export class Assistants extends APIResource {
    * @example
    * ```ts
    * const assistantsList = await client.ai.assistants.imports({
-   *   api_key_ref: 'api_key_ref',
+   *   api_key_ref: 'string',
    *   provider: 'elevenlabs',
+   *   import_ids: ['string'],
    * });
    * ```
    */
@@ -250,7 +251,11 @@ export class Assistants extends APIResource {
    * ```ts
    * const response = await client.ai.assistants.sendSMS(
    *   'assistant_id',
-   *   { from: 'from', to: 'to' },
+   *   {
+   *     from: 'From',
+   *     to: 'To',
+   *     text: 'Text',
+   *   },
    * );
    * ```
    */
@@ -386,7 +391,8 @@ export type AssistantTool =
   | AssistantTool.SendDtmf
   | AssistantTool.SendMessage
   | AssistantTool.SkipTurn
-  | AssistantTool.Pay;
+  | AssistantTool.Pay
+  | AssistantTool.UpdateDynamicVariables;
 
 export namespace AssistantTool {
   export interface ClientSideTool {
@@ -913,6 +919,22 @@ export namespace AssistantTool {
 
     type: 'pay';
   }
+
+  /**
+   * The update_dynamic_variables tool lets the assistant write values into the
+   * conversation's dynamic-variables context during the call. Updated variables are
+   * available to later `{{variable}}` interpolation (prompts, speak nodes, message
+   * templates) and to flow edge conditions. Declare each variable the assistant is
+   * allowed to set under `updatable_variables`.
+   */
+  export interface UpdateDynamicVariables {
+    type: 'update_dynamic_variables';
+
+    /**
+     * Configuration for an update_dynamic_variables tool.
+     */
+    update_dynamic_variables: ToolsAPI.UpdateDynamicVariablesToolParams;
+  }
 }
 
 export interface AssistantsList {
@@ -2311,6 +2333,13 @@ export interface TelephonySettings {
    */
   default_texml_app_id?: string;
 
+  /**
+   * Disable inbound DTMF for the entire call. Must be set to true if a 'pay' tool is
+   * configured anywhere on the assistant — on the main tool array or on any workflow
+   * node — enforced at write time.
+   */
+  disable_dtmf?: boolean;
+
   /**
    * The noise suppression engine to use. Use 'disabled' to turn off noise
    * suppression.

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

@@ -58,6 +58,25 @@ export class CanaryDeploys extends APIResource {
    * const canaryDeployResponse =
    *   await client.ai.assistants.canaryDeploys.create(
    *     'assistant_id',
+   *     {
+   *       rules: [
+   *         {
+   *           match: [
+   *             {
+   *               attribute: 'Attribute',
+   *               operator: 'in',
+   *               values: ['string'],
+   *             },
+   *           ],
+   *           serve: {
+   *             version_id: 'Version Id',
+   *             rollout: [
+   *               { version_id: 'Version Id', weight: 0 },
+   *             ],
+   *           },
+   *         },
+   *       ],
+   *     },
    *   );
    * ```
    */
@@ -81,6 +100,25 @@ export class CanaryDeploys extends APIResource {
    * const canaryDeployResponse =
    *   await client.ai.assistants.canaryDeploys.update(
    *     'assistant_id',
+   *     {
+   *       rules: [
+   *         {
+   *           match: [
+   *             {
+   *               attribute: 'Attribute',
+   *               operator: 'in',
+   *               values: ['string'],
+   *             },
+   *           ],
+   *           serve: {
+   *             version_id: 'Version Id',
+   *             rollout: [
+   *               { version_id: 'Version Id', weight: 0 },
+   *             ],
+   *           },
+   *         },
+   *       ],
+   *     },
    *   );
    * ```
    */

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

@@ -33,6 +33,10 @@ export class Instructions extends APIResource {
    * const response =
    *   await client.ai.assistants.instructions.enhance(
    *     'assistant_id',
+   *     {
+   *       enhancement_prompt: 'string',
+   *       instructions: 'string',
+   *     },
    *   );
    * ```
    */

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

@@ -10,7 +10,7 @@ import { path } from '../../../internal/utils/path';
  */
 export class Tags extends APIResource {
   /**
-   * Get All Tags
+   * Retrieve all tags that have been applied to your AI assistants.
    *
    * @example
    * ```ts
@@ -22,13 +22,13 @@ export class Tags extends APIResource {
   }
 
   /**
-   * Add Assistant Tag
+   * Add a tag to an AI assistant. Tags help you organize and filter your assistants.
    *
    * @example
    * ```ts
    * const tagsResponse = await client.ai.assistants.tags.add(
    *   'assistant_id',
-   *   { tag: 'tag' },
+   *   { tag: 'Tag' },
    * );
    * ```
    */
@@ -37,7 +37,7 @@ export class Tags extends APIResource {
   }
 
   /**
-   * Remove Assistant Tag
+   * Remove a tag from an AI assistant.
    *
    * @example
    * ```ts

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

@@ -116,7 +116,16 @@ export class Tests extends APIResource {
    * @example
    * ```ts
    * const assistantTest =
-   *   await client.ai.assistants.tests.update('test_id');
+   *   await client.ai.assistants.tests.update('test_id', {
+   *     description: 'Description',
+   *     destination: 'Destination',
+   *     instructions: 'Instructions',
+   *     max_duration_seconds: 30,
+   *     name: 'Name',
+   *     rubric: [{ name: 'string', criteria: 'string' }],
+   *     telnyx_conversation_channel: 'phone_call',
+   *     test_suite: 'Test Suite',
+   *   });
    * ```
    */
   update(testID: string, body: TestUpdateParams, options?: RequestOptions): APIPromise<AssistantTest> {

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

@@ -16,7 +16,11 @@ export class Tools extends APIResource {
    * ```ts
    * const response = await client.ai.assistants.tools.test(
    *   'tool_id',
-   *   { assistant_id: 'assistant_id' },
+   *   {
+   *     assistant_id: 'assistant_id',
+   *     arguments: { order_id: 'order_12345' },
+   *     dynamic_variables: { customer_name: 'Ada' },
+   *   },
    * );
    * ```
    */
@@ -26,7 +30,7 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Remove Assistant Tool
+   * Detach a tool from an AI assistant.
    *
    * @example
    * ```ts
@@ -42,7 +46,7 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Add Assistant Tool
+   * Attach an existing tool to an AI assistant.
    *
    * @example
    * ```ts

package/src/resources/ai/clusters.ts

@@ -14,7 +14,7 @@ import { path } from '../../internal/utils/path';
  */
 export class Clusters extends APIResource {
   /**
-   * List all clusters
+   * Retrieve a paginated list of clustering tasks and their statuses.
    *
    * @example
    * ```ts
@@ -42,7 +42,11 @@ export class Clusters extends APIResource {
    * @example
    * ```ts
    * const response = await client.ai.clusters.compute({
-   *   bucket: 'bucket',
+   *   bucket: 'string',
+   *   files: ['string'],
+   *   min_cluster_size: 25,
+   *   min_subcluster_size: 5,
+   *   prefix: 'string',
    * });
    * ```
    */
@@ -51,7 +55,7 @@ export class Clusters extends APIResource {
   }
 
   /**
-   * Delete a cluster
+   * Delete a clustering task and its computed results.
    *
    * @example
    * ```ts
@@ -66,7 +70,7 @@ export class Clusters extends APIResource {
   }
 
   /**
-   * Fetch a cluster
+   * Fetch the results of a clustering task, including the discovered clusters.
    *
    * @example
    * ```ts
@@ -84,7 +88,7 @@ export class Clusters extends APIResource {
   }
 
   /**
-   * Fetch a cluster visualization
+   * Fetch a visualization image of the clusters computed by a clustering task.
    *
    * @example
    * ```ts

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

@@ -0,0 +1,409 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as SettingsAPI from './settings';
+import {
+  RetrievalSettings,
+  RetrievalSettingsWrapper,
+  SettingCreateParams,
+  SettingPatchAllParams,
+  Settings,
+  SettingsEnvelope,
+  SettingsRequest,
+} from './settings';
+import * as SourcesAPI from './sources';
+import {
+  Source,
+  SourceCreateParams,
+  SourceCreateResponse,
+  SourceDeleteParams,
+  SourceListResponse,
+  SourceReplaceParams,
+  SourceReplaceResponse,
+  SourceRequest,
+  SourceType,
+  Sources,
+} from './sources';
+import { APIPromise } from '../../../core/api-promise';
+import {
+  DefaultFlatPagination,
+  type DefaultFlatPaginationParams,
+  PagePromise,
+} from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Create and manage logical collections of your Telnyx data, tune retrieval settings, manage sources, and run collection-scoped semantic search.
+ */
+export class Collections extends APIResource {
+  settings: SettingsAPI.Settings = new SettingsAPI.Settings(this._client);
+  sources: SourcesAPI.Sources = new SourcesAPI.Sources(this._client);
+
+  /**
+   * Fetches a single collection by its `uuid`.
+   *
+   * @example
+   * ```ts
+   * const collectionEnvelope =
+   *   await client.ai.collections.retrieveByID(
+   *     '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   *   );
+   * ```
+   */
+  retrieveByID(uuid: string, options?: RequestOptions): APIPromise<CollectionEnvelope> {
+    return this._client.get(path`/ai/collections/${uuid}`, options);
+  }
+
+  /**
+   * Returns a paginated list of collections in your organization.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const collection of client.ai.collections.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: CollectionListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CollectionsDefaultFlatPagination, Collection> {
+    return this._client.getAPIList('/ai/collections', DefaultFlatPagination<Collection>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Creates a new collection scoped to your organization. Optionally attach sources
+   * and retrieval settings at creation time. If `slug` is omitted, one is derived
+   * from `name` and must be unique within your organization.
+   *
+   * @example
+   * ```ts
+   * const collectionEnvelope =
+   *   await client.ai.collections.create({
+   *     name: 'Support Transcripts',
+   *   });
+   * ```
+   */
+  create(body: CollectionCreateParams, options?: RequestOptions): APIPromise<CollectionEnvelope> {
+    return this._client.post('/ai/collections', { body, ...options });
+  }
+
+  /**
+   * Fetches a single collection by its `slug`.
+   *
+   * @example
+   * ```ts
+   * const collectionEnvelope =
+   *   await client.ai.collections.retrieve(
+   *     'support-transcripts',
+   *   );
+   * ```
+   */
+  retrieve(slug: string, options?: RequestOptions): APIPromise<CollectionEnvelope> {
+    return this._client.get(path`/ai/collections/slug/${slug}`, options);
+  }
+
+  /**
+   * Runs search over the documents in a collection, ranked by relevance to `query`.
+   * The collection's `retrieval_type` setting selects the strategy: `vector`
+   * (semantic similarity), `hybrid` (vector similarity fused with keyword matching),
+   * or `keyword` (lexical BM25 matching). When `query` is omitted, returns a plain
+   * catalog listing of the collection's documents.
+   *
+   * **How it works:**
+   *
+   * 1. For `vector` and `hybrid`, the `query` text is embedded into a
+   *    1024-dimensional vector using the multilingual-e5-large model.
+   * 2. For `vector`, the embedding is compared against the collection's indexed
+   *    document chunks using semantic similarity; for `hybrid`, those similarity
+   *    scores are fused with keyword-match scores; for `keyword`, only lexical BM25
+   *    matching is applied.
+   * 3. Results are ranked by `score` (descending) and paginated via `page[number]` /
+   *    `page[size]`.
+   *
+   * **Authentication:** Requires a Telnyx API key via `Authorization: Bearer <key>`.
+   * Results are automatically scoped to your organization and cannot be overridden.
+   *
+   * **Filtering:** Use `filter[field][operator]=value` query parameters to narrow
+   * results before search. Supported operators: `eq` (default), `in`, `gte`, `gt`,
+   * `lte`, `lt`, `contains`. Metadata fields resolve to `metadata.<field>`.
+   *
+   * **Examples:**
+   *
+   * - `GET /v2/ai/collections/my-collection/documents?query=billing+issue&top_k=10`
+   * - `GET /v2/ai/collections/my-collection/documents?query=refund&sources=voice,message`
+   * - `GET /v2/ai/collections/my-collection/documents?query=outage&filter[record_created_at][gte]=2026-01-01T00:00:00Z`
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await 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 });
+  }
+
+  /**
+   * Soft-deletes a collection. Its `slug` is freed and may be reused by a new
+   * collection.
+   *
+   * @example
+   * ```ts
+   * await client.ai.collections.delete(
+   *   '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   * );
+   * ```
+   */
+  delete(uuid: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/ai/collections/${uuid}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Updates a collection's metadata (`name` and/or `description`). Sources and
+   * settings are managed through their own sub-resources.
+   *
+   * @example
+   * ```ts
+   * const collectionEnvelope =
+   *   await client.ai.collections.update(
+   *     '6a09ccbd-8f9b-4c3a-9b0e-2f1d3c4b5a6e',
+   *   );
+   * ```
+   */
+  update(
+    uuid: string,
+    body: CollectionUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<CollectionEnvelope> {
+    return this._client.patch(path`/ai/collections/${uuid}`, { body, ...options });
+  }
+}
+
+export type CollectionsDefaultFlatPagination = DefaultFlatPagination<Collection>;
+
+export interface Collection {
+  created_at?: string;
+
+  description?: string;
+
+  name?: string;
+
+  /**
+   * Identifies the record type. Always `ai_collection`.
+   */
+  record_type?: string;
+
+  settings?: SettingsAPI.RetrievalSettingsWrapper;
+
+  slug?: string;
+
+  sources?: Array<SourcesAPI.Source>;
+
+  status?: string;
+
+  updated_at?: string;
+
+  uuid?: string;
+}
+
+export interface CollectionEnvelope {
+  data?: Collection;
+}
+
+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;
+
+    record_id?: string;
+
+    /**
+     * The source record kind this chunk came from (e.g. `voice`, `meeting_bot`,
+     * `message`).
+     */
+    record_type?: string;
+
+    region?: string;
+
+    /**
+     * Relevance score (higher = more relevant) for ranked search. `0.0` for plain
+     * catalog listings (when `query` is omitted).
+     */
+    score?: number;
+
+    text?: string;
+
+    user_id?: string;
+  }
+
+  export interface Meta {
+    collection_slug?: string;
+
+    page_number?: number;
+
+    page_size?: number;
+
+    retrieval_type?: string;
+
+    searched_sources?: Array<string>;
+
+    top_k?: number;
+
+    total_pages?: number;
+
+    total_results?: number;
+  }
+}
+
+export interface CollectionListParams extends DefaultFlatPaginationParams {}
+
+export interface CollectionCreateParams {
+  /**
+   * Human-readable collection name.
+   */
+  name: string;
+
+  /**
+   * Optional description.
+   */
+  description?: string;
+
+  /**
+   * Optional retrieval settings.
+   */
+  settings?: SettingsAPI.RetrievalSettingsWrapper;
+
+  /**
+   * Optional slug (unique per organization). Derived from `name` when omitted.
+   */
+  slug?: string;
+
+  /**
+   * Optional sources to attach at creation time.
+   */
+  sources?: Array<SourcesAPI.SourceRequest>;
+}
+
+export interface CollectionRetrieveDocumentsParams {
+  /**
+   * Field filters applied before ranking, using `filter[field][operator]=value`.
+   * Supported operators: `eq` (default), `in`, `gte`, `gt`, `lte`, `lt`, `contains`.
+   * Known fields: `record_type`, `record_id`, `user_id`, `record_created_at`,
+   * `ingested_at`; any other name resolves to a `metadata.<field>` filter. Example:
+   * `filter[record_id][eq]=rec_123`.
+   */
+  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
+   * hybrid). When omitted, documents are returned as a plain catalog listing.
+   */
+  query?: string;
+
+  /**
+   * Override the collection's configured retrieval strategy for this request. Echoed
+   * back in `meta.retrieval_type`.
+   */
+  retrieval_type?: 'vector' | 'hybrid' | 'keyword';
+
+  /**
+   * Comma-separated list of source types to restrict the search to. When omitted,
+   * all of the collection's sources are searched.
+   */
+  sources?: string;
+
+  /**
+   * Maximum number of ranked results to consider. When omitted, the collection's
+   * configured `top_k` setting is used.
+   */
+  top_k?: number;
+}
+
+export interface CollectionUpdateParams {
+  description?: string;
+
+  name?: string;
+}
+
+Collections.Settings = Settings;
+Collections.Sources = Sources;
+
+export declare namespace Collections {
+  export {
+    type Collection as Collection,
+    type CollectionEnvelope as CollectionEnvelope,
+    type CollectionRetrieveDocumentsResponse as CollectionRetrieveDocumentsResponse,
+    type CollectionsDefaultFlatPagination as CollectionsDefaultFlatPagination,
+    type CollectionListParams as CollectionListParams,
+    type CollectionCreateParams as CollectionCreateParams,
+    type CollectionRetrieveDocumentsParams as CollectionRetrieveDocumentsParams,
+    type CollectionUpdateParams as CollectionUpdateParams,
+  };
+
+  export {
+    Settings as Settings,
+    type RetrievalSettings as RetrievalSettings,
+    type RetrievalSettingsWrapper as RetrievalSettingsWrapper,
+    type SettingsEnvelope as SettingsEnvelope,
+    type SettingsRequest as SettingsRequest,
+    type SettingPatchAllParams as SettingPatchAllParams,
+    type SettingCreateParams as SettingCreateParams,
+  };
+
+  export {
+    Sources as Sources,
+    type Source as Source,
+    type SourceRequest as SourceRequest,
+    type SourceType as SourceType,
+    type SourceCreateResponse as SourceCreateResponse,
+    type SourceListResponse as SourceListResponse,
+    type SourceReplaceResponse as SourceReplaceResponse,
+    type SourceCreateParams as SourceCreateParams,
+    type SourceReplaceParams as SourceReplaceParams,
+    type SourceDeleteParams as SourceDeleteParams,
+  };
+}

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

@@ -0,0 +1,34 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Collections,
+  type Collection,
+  type CollectionEnvelope,
+  type CollectionRetrieveDocumentsResponse,
+  type CollectionListParams,
+  type CollectionCreateParams,
+  type CollectionRetrieveDocumentsParams,
+  type CollectionUpdateParams,
+  type CollectionsDefaultFlatPagination,
+} from './collections';
+export {
+  Settings,
+  type RetrievalSettings,
+  type RetrievalSettingsWrapper,
+  type SettingsEnvelope,
+  type SettingsRequest,
+  type SettingPatchAllParams,
+  type SettingCreateParams,
+} from './settings';
+export {
+  Sources,
+  type Source,
+  type SourceRequest,
+  type SourceType,
+  type SourceCreateResponse,
+  type SourceListResponse,
+  type SourceReplaceResponse,
+  type SourceCreateParams,
+  type SourceReplaceParams,
+  type SourceDeleteParams,
+} from './sources';