telnyx 7.16.0 → 7.18.0

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

package/src/resources/ai/conversations/conversations.ts

@@ -70,7 +70,8 @@ export class Conversations extends APIResource {
   }
 
   /**
-   * Create a new AI Conversation.
+   * Creates a new AI conversation, the container for messages exchanged with an
+   * assistant, and returns the created conversation.
    *
    * @example
    * ```ts
@@ -79,8 +80,16 @@ export class Conversations extends APIResource {
    * });
    * ```
    */
-  create(body: ConversationCreateParams, options?: RequestOptions): APIPromise<Conversation> {
-    return this._client.post('/ai/conversations', { body, ...options });
+  create(params: ConversationCreateParams, options?: RequestOptions): APIPromise<Conversation> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/ai/conversations', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -170,13 +179,17 @@ export class Conversations extends APIResource {
    */
   addMessage(
     conversationID: string,
-    body: ConversationAddMessageParams,
+    params: ConversationAddMessageParams,
     options?: RequestOptions,
   ): APIPromise<void> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
     return this._client.post(path`/ai/conversations/${conversationID}/message`, {
       body,
       ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+      headers: buildHeaders([
+        { Accept: '*/*', ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
     });
   }
 }
@@ -334,12 +347,27 @@ export interface ConversationListParams {
 
 export interface ConversationCreateParams {
   /**
-   * Metadata associated with the conversation. Set `ai_disabled` to `true` to create
-   * the conversation with AI message responses disabled.
+   * Body param: Metadata associated with the conversation. Set `ai_disabled` to
+   * `true` to create the conversation with AI message responses disabled.
    */
   metadata?: { [key: string]: string };
 
+  /**
+   * Body param
+   */
   name?: 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 ConversationUpdateParams {
@@ -352,21 +380,57 @@ export interface ConversationUpdateParams {
 }
 
 export interface ConversationAddMessageParams {
+  /**
+   * Body param
+   */
   role: string;
 
+  /**
+   * Body param
+   */
   content?: string;
 
+  /**
+   * Body param
+   */
   metadata?: { [key: string]: string | number | boolean | Array<string | number | boolean> };
 
+  /**
+   * Body param
+   */
   name?: string;
 
+  /**
+   * Body param
+   */
   sent_at?: string;
 
+  /**
+   * Body param
+   */
   tool_call_id?: string;
 
+  /**
+   * Body param
+   */
   tool_calls?: Array<{ [key: string]: unknown }>;
 
+  /**
+   * Body param
+   */
   tool_choice?: string | { [key: string]: unknown };
+
+  /**
+   * 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;
 }
 
 Conversations.InsightGroups = InsightGroups;

package/src/resources/ai/conversations/insight-groups/insight-groups.ts

@@ -21,7 +21,9 @@ export class InsightGroups extends APIResource {
   insights: InsightGroupsInsightsAPI.Insights = new InsightGroupsInsightsAPI.Insights(this._client);
 
   /**
-   * Get all insight groups
+   * Returns a paginated list of your insight template groups. Groups organize
+   * related insight templates that are applied together when analyzing
+   * conversations.
    *
    * @example
    * ```ts
@@ -43,7 +45,8 @@ export class InsightGroups extends APIResource {
   }
 
   /**
-   * Create a new insight group
+   * Creates a new insight template group for organizing related insight templates,
+   * and returns the created group.
    *
    * @example
    * ```ts
@@ -54,14 +57,22 @@ export class InsightGroups extends APIResource {
    * ```
    */
   insightGroups(
-    body: InsightGroupInsightGroupsParams,
+    params: InsightGroupInsightGroupsParams,
     options?: RequestOptions,
   ): APIPromise<InsightTemplateGroupDetail> {
-    return this._client.post('/ai/conversations/insight-groups', { body, ...options });
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/ai/conversations/insight-groups', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * Delete insight group by ID
+   * Permanently deletes the specified insight template group by its ID.
    *
    * @example
    * ```ts
@@ -78,7 +89,8 @@ export class InsightGroups extends APIResource {
   }
 
   /**
-   * Get insight group by ID
+   * Returns the details of a single insight template group, including the insight
+   * templates assigned to it.
    *
    * @example
    * ```ts
@@ -93,7 +105,7 @@ export class InsightGroups extends APIResource {
   }
 
   /**
-   * Update an insight template group
+   * Updates the specified insight template group and returns the updated group.
    *
    * @example
    * ```ts
@@ -140,11 +152,32 @@ export interface InsightTemplateGroupDetail {
 export interface InsightGroupRetrieveInsightGroupsParams extends DefaultFlatPaginationParams {}
 
 export interface InsightGroupInsightGroupsParams {
+  /**
+   * Body param
+   */
   name: string;
 
+  /**
+   * Body param
+   */
   description?: string;
 
+  /**
+   * Body param
+   */
   webhook?: 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 InsightGroupUpdateParams {

package/src/resources/ai/conversations/insight-groups/insights.ts

@@ -11,7 +11,7 @@ import { path } from '../../../../internal/utils/path';
  */
 export class Insights extends APIResource {
   /**
-   * Assign an insight to a group
+   * Assigns the specified insight template to the specified insight template group.
    *
    * @example
    * ```ts
@@ -30,7 +30,8 @@ export class Insights extends APIResource {
   }
 
   /**
-   * Remove an insight from a group
+   * Removes the specified insight template from the specified group. The insight
+   * template itself is not deleted.
    *
    * @example
    * ```ts

package/src/resources/ai/conversations/insights.ts

@@ -16,7 +16,8 @@ import { path } from '../../../internal/utils/path';
  */
 export class Insights extends APIResource {
   /**
-   * Get all insights
+   * Returns a paginated list of your insight templates. Insight templates define
+   * analyses that run over AI conversations to extract structured findings.
    *
    * @example
    * ```ts
@@ -37,7 +38,8 @@ export class Insights extends APIResource {
   }
 
   /**
-   * Create a new insight
+   * Creates a new insight template defining an analysis to run over conversations,
+   * and returns the created template.
    *
    * @example
    * ```ts
@@ -49,12 +51,20 @@ export class Insights extends APIResource {
    *   });
    * ```
    */
-  create(body: InsightCreateParams, options?: RequestOptions): APIPromise<InsightTemplateDetail> {
-    return this._client.post('/ai/conversations/insights', { body, ...options });
+  create(params: InsightCreateParams, options?: RequestOptions): APIPromise<InsightTemplateDetail> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/ai/conversations/insights', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * Delete insight by ID
+   * Permanently deletes the specified insight template by its ID.
    *
    * @example
    * ```ts
@@ -71,7 +81,8 @@ export class Insights extends APIResource {
   }
 
   /**
-   * Get insight by ID
+   * Returns the details of a single insight template by its ID, including its
+   * configuration.
    *
    * @example
    * ```ts
@@ -86,7 +97,7 @@ export class Insights extends APIResource {
   }
 
   /**
-   * Update an insight template
+   * Updates the specified insight template and returns the updated template.
    *
    * @example
    * ```ts
@@ -139,16 +150,37 @@ export interface InsightTemplateDetail {
 export interface InsightListParams extends DefaultFlatPaginationParams {}
 
 export interface InsightCreateParams {
+  /**
+   * Body param
+   */
   instructions: string;
 
+  /**
+   * Body param
+   */
   name: string;
 
   /**
-   * If specified, the output will follow the JSON schema.
+   * Body param: If specified, the output will follow the JSON schema.
    */
   json_schema?: string | { [key: string]: unknown };
 
+  /**
+   * Body param
+   */
   webhook?: 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 InsightUpdateParams {

package/src/resources/ai/conversations/messages.ts

@@ -60,6 +60,8 @@ export interface MessageListResponse {
    */
   created_at?: string;
 
+  metadata?: { [key: string]: string | number | boolean | Array<string | number | boolean> };
+
   /**
    * The datetime the message was sent to the end user.
    */

package/src/resources/ai/embeddings/buckets.ts

@@ -11,7 +11,8 @@ import { path } from '../../../internal/utils/path';
  */
 export class Buckets extends APIResource {
   /**
-   * Get all embedding buckets for a user.
+   * Returns the list of storage buckets that have been embedded for your account,
+   * for use with similarity search.
    *
    * @example
    * ```ts

package/src/resources/ai/embeddings/embeddings.ts

@@ -5,6 +5,7 @@ import * as EmbeddingsAPI from './embeddings';
 import * as BucketsAPI from './buckets';
 import { BucketListResponse, BucketRetrieveResponse, Buckets } from './buckets';
 import { APIPromise } from '../../../core/api-promise';
+import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
@@ -75,8 +76,16 @@ export class Embeddings extends APIResource {
    * );
    * ```
    */
-  create(body: EmbeddingCreateParams, options?: RequestOptions): APIPromise<EmbeddingResponse> {
-    return this._client.post('/ai/embeddings', { body, ...options });
+  create(params: EmbeddingCreateParams, options?: RequestOptions): APIPromise<EmbeddingResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/ai/embeddings', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -128,8 +137,16 @@ export class Embeddings extends APIResource {
    * });
    * ```
    */
-  url(body: EmbeddingURLParams, options?: RequestOptions): APIPromise<EmbeddingResponse> {
-    return this._client.post('/ai/embeddings/url', { body, ...options });
+  url(params: EmbeddingURLParams, options?: RequestOptions): APIPromise<EmbeddingResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/ai/embeddings/url', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -271,21 +288,42 @@ export interface EmbeddingListParams {
 }
 
 export interface EmbeddingCreateParams {
+  /**
+   * Body param
+   */
   bucket_name: string;
 
+  /**
+   * Body param
+   */
   document_chunk_overlap_size?: number;
 
+  /**
+   * Body param
+   */
   document_chunk_size?: number;
 
   /**
-   * Supported models to vectorize and embed documents.
+   * Body param: Supported models to vectorize and embed documents.
    */
   embedding_model?: 'thenlper/gte-large' | 'intfloat/multilingual-e5-large';
 
   /**
-   * Supported types of custom document loaders for embeddings.
+   * Body param: Supported types of custom document loaders for embeddings.
    */
   loader?: 'default' | 'intercom';
+
+  /**
+   * 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 EmbeddingSimilaritySearchParams {
@@ -298,14 +336,27 @@ export interface EmbeddingSimilaritySearchParams {
 
 export interface EmbeddingURLParams {
   /**
-   * Name of the bucket to store the embeddings. This bucket must already exist.
+   * Body param: Name of the bucket to store the embeddings. This bucket must already
+   * exist.
    */
   bucket_name: string;
 
   /**
-   * The URL of the webpage to embed
+   * Body param: The URL of the webpage to embed
    */
   url: 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;
 }
 
 Embeddings.Buckets = Buckets;

package/src/resources/ai/fine-tuning/jobs.ts

@@ -22,7 +22,8 @@ export class Jobs extends APIResource {
   }
 
   /**
-   * Create a new fine tuning job.
+   * Creates a new fine-tuning job that trains a model on the provided dataset, and
+   * returns the created job.
    *
    * @example
    * ```ts
@@ -40,7 +41,8 @@ export class Jobs extends APIResource {
   }
 
   /**
-   * Retrieve a fine tuning job by `job_id`.
+   * Returns the details of a single fine-tuning job by its job_id, including its
+   * current status.
    *
    * @example
    * ```ts
@@ -53,7 +55,7 @@ export class Jobs extends APIResource {
   }
 
   /**
-   * Cancel a fine tuning job.
+   * Cancels the specified in-progress fine-tuning job and returns the updated job.
    *
    * @example
    * ```ts

package/src/resources/ai/index.ts

@@ -8,6 +8,7 @@ export {
   type AISummarizeResponse,
   type AISummarizeParams,
   type AIRetrieveConversationHistoriesParams,
+  type AIRetrieveConversationHistoriesResponsesDefaultFlatPagination,
 } from './ai';
 export { Anthropic } from './anthropic/index';
 export {
@@ -22,6 +23,7 @@ export {
   type AuthenticationMethod,
   type BooleanOpExpression,
   type ComparisonExpression,
+  type ConversationFlow,
   type ConversationFlowReq,
   type EnabledFeatures,
   type Expression,
@@ -30,6 +32,8 @@ export {
   type FallbackConfig,
   type FallbackConfigReq,
   type FlowEdge,
+  type FlowNode,
+  type FlowNodeReq,
   type HangupTool,
   type HangupToolParams,
   type ImportMetadata,
@@ -47,8 +51,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,
@@ -65,6 +73,7 @@ export {
   type AssistantRetrieveParams,
   type AssistantUpdateParams,
   type AssistantChatParams,
+  type AssistantCloneParams,
   type AssistantSendSMSParams,
 } from './assistants/index';
 export { Audio, type AudioTranscribeResponse, type AudioTranscribeParams } from './audio';
@@ -85,10 +94,8 @@ export {
   Collections,
   type Collection,
   type CollectionEnvelope,
-  type CollectionRetrieveDocumentsResponse,
   type CollectionListParams,
   type CollectionCreateParams,
-  type CollectionRetrieveDocumentsParams,
   type CollectionUpdateParams,
   type CollectionsDefaultFlatPagination,
 } from './collections/index';
@@ -118,6 +125,7 @@ export {
 } from './embeddings/index';
 export { FineTuning } from './fine-tuning/index';
 export { Integrations, type Integration, type IntegrationListResponse } from './integrations/index';
+export { Knowledge } from './knowledge/index';
 export {
   McpServers,
   type McpServer,

package/src/resources/ai/integrations/connections.ts

@@ -8,7 +8,8 @@ import { path } from '../../../internal/utils/path';
 
 export class Connections extends APIResource {
   /**
-   * List user setup integrations
+   * Returns the list of integration connections you have set up, linking your
+   * account to third-party services.
    *
    * @example
    * ```ts
@@ -38,7 +39,7 @@ export class Connections extends APIResource {
   }
 
   /**
-   * Get user setup integrations
+   * Returns the details of a single integration connection by its ID.
    *
    * @example
    * ```ts

package/src/resources/ai/integrations/integrations.ts

@@ -16,7 +16,8 @@ export class Integrations extends APIResource {
   connections: ConnectionsAPI.Connections = new ConnectionsAPI.Connections(this._client);
 
   /**
-   * List all available integrations.
+   * Returns the list of third-party integrations available to connect to your AI
+   * assistants and workflows.
    *
    * @example
    * ```ts
@@ -28,7 +29,8 @@ export class Integrations extends APIResource {
   }
 
   /**
-   * Retrieve integration details
+   * Returns the details of a single available integration, including its
+   * configuration details.
    *
    * @example
    * ```ts