telnyx 6.74.2 → 7.1.0

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

@@ -2,17 +2,24 @@
 
 export {
   Assistants,
+  type ArithmeticExpression,
   type Assistant,
   type AssistantIntegration,
   type AssistantMcpServer,
   type AssistantTool,
   type AssistantsList,
   type AudioVisualizerConfig,
+  type AuthenticationMethod,
+  type BooleanOpExpression,
+  type ComparisonExpression,
+  type ConversationFlowReq,
   type EnabledFeatures,
+  type Expression,
   type ExternalLlm,
   type ExternalLlmReq,
   type FallbackConfig,
   type FallbackConfigReq,
+  type FlowEdge,
   type HangupTool,
   type HangupToolParams,
   type ImportMetadata,
@@ -21,11 +28,14 @@ export {
   type InferenceEmbeddingWebhookToolParams,
   type InsightSettings,
   type MessagingSettings,
+  type NodePosition,
   type Observability,
   type ObservabilityReq,
+  type ObservabilityStatus,
   type PostConversationSettings,
   type PostConversationSettingsReq,
   type PrivacySettings,
+  type PromptSyncStatus,
   type RetrievalTool,
   type StartSpeakingPlan,
   type TelephonySettings,
@@ -59,10 +69,12 @@ export {
   type CanaryDeployCreateParams,
   type CanaryDeployUpdateParams,
 } from './canary-deploys';
+export { Instructions, type InstructionEnhanceResponse, type InstructionEnhanceParams } from './instructions';
 export {
   ScheduledEvents,
   type ConversationChannelType,
   type EventStatus,
+  type ScheduledCallSettings,
   type ScheduledEventResponse,
   type ScheduledPhoneCallEventResponse,
   type ScheduledSMSEventResponse,
@@ -73,14 +85,7 @@ export {
   type ScheduledEventDeleteParams,
   type ScheduledEventListResponsesDefaultFlatPagination,
 } from './scheduled-events';
-export {
-  Tags,
-  type TagListResponse,
-  type TagAddResponse,
-  type TagRemoveResponse,
-  type TagAddParams,
-  type TagRemoveParams,
-} from './tags';
+export { Tags, type TagsResponse, type TagAddParams, type TagRemoveParams } from './tags';
 export {
   Tests,
   type AssistantTest,

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

@@ -0,0 +1,74 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Configure AI assistant specifications
+ */
+export class Instructions extends APIResource {
+  /**
+   * Enhance an assistant's instructions using an LLM. The endpoint reads the
+   * assistant's current instructions and tools, then streams back improved
+   * instructions as they are generated.
+   *
+   * Optionally provide an `enhancement_prompt` to steer the changes (for example,
+   * "make the instructions more concise" or "add error handling guidance"). When
+   * omitted, the assistant's existing instructions are used as the basis for the
+   * enhancement.
+   *
+   * The enhancement focuses on tool-calling reliability, clarity and precision,
+   * completeness and error handling, tool schema alignment, and conversation flow
+   * structure.
+   *
+   * The response is streamed as `text/plain` using chunked transfer encoding;
+   * consume the body incrementally to render the enhanced instructions as they
+   * arrive.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.ai.assistants.instructions.enhance(
+   *     'assistant_id',
+   *   );
+   * ```
+   */
+  enhance(
+    assistantID: string,
+    body: InstructionEnhanceParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<string> {
+    return this._client.post(path`/ai/assistants/${assistantID}/instructions/enhance`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: 'text/plain' }, options?.headers]),
+    });
+  }
+}
+
+export type InstructionEnhanceResponse = string;
+
+export interface InstructionEnhanceParams {
+  /**
+   * Optional guidance describing how the instructions should be enhanced. When
+   * provided, the LLM applies these requested changes in addition to fixing any
+   * identified issues.
+   */
+  enhancement_prompt?: string | null;
+
+  /**
+   * The instructions to enhance. When omitted, the assistant's existing instructions
+   * are used.
+   */
+  instructions?: string | null;
+}
+
+export declare namespace Instructions {
+  export {
+    type InstructionEnhanceResponse as InstructionEnhanceResponse,
+    type InstructionEnhanceParams as InstructionEnhanceParams,
+  };
+}

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

@@ -115,6 +115,20 @@ export type ConversationChannelType = 'phone_call' | 'sms_chat';
 
 export type EventStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
 
+/**
+ * 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.
+ */
+export interface ScheduledCallSettings {
+  /**
+   * SIP region passed to Telnyx when initiating an outbound call. Values match the
+   * Telnyx TeXML `SipRegion` parameter exactly. Telnyx defaults to `US` when
+   * omitted.
+   */
+  sip_region?: 'US' | 'Europe' | 'Canada' | 'Australia' | 'Middle East';
+}
+
 /**
  * Union type for different scheduled event response types
  */
@@ -138,6 +152,13 @@ export interface ScheduledPhoneCallEventResponse {
    */
   call_duration?: number;
 
+  /**
+   * 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;
+
   /**
    * Values: busy, canceled, no-answer, ringing, completed, failed, in-progress
    */
@@ -256,6 +277,13 @@ export interface ScheduledEventCreateParams {
    */
   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.
+   */
+  call_settings?: ScheduledCallSettings;
+
   /**
    * Metadata associated with the conversation. Telnyx provides several pieces of
    * metadata, but customers can also add their own.
@@ -283,18 +311,33 @@ export interface ScheduledEventCreateParams {
 }
 
 export interface ScheduledEventRetrieveParams {
+  /**
+   * Unique identifier of the assistant.
+   */
   assistant_id: string;
 }
 
 export interface ScheduledEventListParams extends DefaultFlatPaginationParams {
+  /**
+   * Filter results by conversation channel.
+   */
   conversation_channel?: ConversationChannelType;
 
+  /**
+   * Start of the date range filter (inclusive, ISO 8601).
+   */
   from_date?: string;
 
+  /**
+   * End of the date range filter (inclusive, ISO 8601).
+   */
   to_date?: string;
 }
 
 export interface ScheduledEventDeleteParams {
+  /**
+   * Unique identifier of the assistant.
+   */
   assistant_id: string;
 }
 
@@ -302,6 +345,7 @@ export declare namespace ScheduledEvents {
   export {
     type ConversationChannelType as ConversationChannelType,
     type EventStatus as EventStatus,
+    type ScheduledCallSettings as ScheduledCallSettings,
     type ScheduledEventResponse as ScheduledEventResponse,
     type ScheduledPhoneCallEventResponse as ScheduledPhoneCallEventResponse,
     type ScheduledSMSEventResponse as ScheduledSMSEventResponse,

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

@@ -14,10 +14,10 @@ export class Tags extends APIResource {
    *
    * @example
    * ```ts
-   * const tags = await client.ai.assistants.tags.list();
+   * const tagsResponse = await client.ai.assistants.tags.list();
    * ```
    */
-  list(options?: RequestOptions): APIPromise<TagListResponse> {
+  list(options?: RequestOptions): APIPromise<TagsResponse> {
     return this._client.get('/ai/assistants/tags', options);
   }
 
@@ -26,13 +26,13 @@ export class Tags extends APIResource {
    *
    * @example
    * ```ts
-   * const response = await client.ai.assistants.tags.add(
+   * const tagsResponse = await client.ai.assistants.tags.add(
    *   'assistant_id',
    *   { tag: 'tag' },
    * );
    * ```
    */
-  add(assistantID: string, body: TagAddParams, options?: RequestOptions): APIPromise<TagAddResponse> {
+  add(assistantID: string, body: TagAddParams, options?: RequestOptions): APIPromise<TagsResponse> {
     return this._client.post(path`/ai/assistants/${assistantID}/tags`, { body, ...options });
   }
 
@@ -41,26 +41,19 @@ export class Tags extends APIResource {
    *
    * @example
    * ```ts
-   * const tag = await client.ai.assistants.tags.remove('tag', {
-   *   assistant_id: 'assistant_id',
-   * });
+   * const tagsResponse = await client.ai.assistants.tags.remove(
+   *   'tag',
+   *   { assistant_id: 'assistant_id' },
+   * );
    * ```
    */
-  remove(tag: string, params: TagRemoveParams, options?: RequestOptions): APIPromise<TagRemoveResponse> {
+  remove(tag: string, params: TagRemoveParams, options?: RequestOptions): APIPromise<TagsResponse> {
     const { assistant_id } = params;
     return this._client.delete(path`/ai/assistants/${assistant_id}/tags/${tag}`, options);
   }
 }
 
-export interface TagListResponse {
-  tags: Array<string>;
-}
-
-export interface TagAddResponse {
-  tags: Array<string>;
-}
-
-export interface TagRemoveResponse {
+export interface TagsResponse {
   tags: Array<string>;
 }
 
@@ -69,14 +62,15 @@ export interface TagAddParams {
 }
 
 export interface TagRemoveParams {
+  /**
+   * Unique identifier of the assistant.
+   */
   assistant_id: string;
 }
 
 export declare namespace Tags {
   export {
-    type TagListResponse as TagListResponse,
-    type TagAddResponse as TagAddResponse,
-    type TagRemoveResponse as TagRemoveResponse,
+    type TagsResponse as TagsResponse,
     type TagAddParams as TagAddParams,
     type TagRemoveParams as TagRemoveParams,
   };

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

@@ -182,6 +182,9 @@ export interface TestRunResponse {
 export type TestStatus = 'pending' | 'starting' | 'running' | 'passed' | 'failed' | 'error';
 
 export interface RunRetrieveParams {
+  /**
+   * Unique identifier of the test.
+   */
   test_id: string;
 }
 

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

@@ -90,16 +90,22 @@ export namespace ToolTestResponse {
 }
 
 export interface ToolAddParams {
+  /**
+   * Unique identifier of the assistant.
+   */
   assistant_id: string;
 }
 
 export interface ToolRemoveParams {
+  /**
+   * Unique identifier of the assistant.
+   */
   assistant_id: string;
 }
 
 export interface ToolTestParams {
   /**
-   * Path param
+   * Path param: Unique identifier of the assistant.
    */
   assistant_id: string;
 

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

@@ -117,6 +117,15 @@ export class Versions extends APIResource {
 }
 
 export interface UpdateAssistant {
+  /**
+   * Conversation flow as supplied by API clients (create / update).
+   *
+   * A directed graph of `FlowNodeReq` connected by `FlowEdge`s. Validation enforces
+   * unique node/edge IDs, that `start_node_id` references a real node, and that
+   * every edge's endpoints reference real nodes.
+   */
+  conversation_flow?: AssistantsAPI.ConversationFlowReq;
+
   description?: string;
 
   /**
@@ -267,22 +276,31 @@ export interface UpdateAssistant {
 
 export interface VersionRetrieveParams {
   /**
-   * Path param
+   * Path param: Unique identifier of the assistant.
    */
   assistant_id: string;
 
   /**
-   * Query param
+   * Query param: Whether to include MCP servers in the response.
    */
   include_mcp_servers?: boolean;
 }
 
 export interface VersionUpdateParams {
   /**
-   * Path param
+   * Path param: Unique identifier of the assistant.
    */
   assistant_id: string;
 
+  /**
+   * Body param: Conversation flow as supplied by API clients (create / update).
+   *
+   * A directed graph of `FlowNodeReq` connected by `FlowEdge`s. Validation enforces
+   * unique node/edge IDs, that `start_node_id` references a real node, and that
+   * every edge's endpoints reference real nodes.
+   */
+  conversation_flow?: AssistantsAPI.ConversationFlowReq;
+
   /**
    * Body param
    */
@@ -469,10 +487,16 @@ export interface VersionUpdateParams {
 }
 
 export interface VersionDeleteParams {
+  /**
+   * Unique identifier of the assistant.
+   */
   assistant_id: string;
 }
 
 export interface VersionPromoteParams {
+  /**
+   * Unique identifier of the assistant.
+   */
   assistant_id: string;
 }
 

package/src/resources/ai/chat.ts

@@ -39,6 +39,211 @@ export interface BucketIDs {
   max_num_results?: number;
 }
 
+export interface ChatCompletionRequest {
+  /**
+   * A list of the previous chat messages for context.
+   */
+  messages: Array<ChatCompletionRequest.Message>;
+
+  /**
+   * If you are using an external inference provider like xAI or OpenAI, this field
+   * allows you to pass along a reference to your API key. After creating an
+   * [integration secret](https://developers.telnyx.com/api-reference/integration-secrets/create-a-secret)
+   * for you API key, pass the secret's `identifier` in this field.
+   */
+  api_key_ref?: string;
+
+  /**
+   * This is used with `use_beam_search` to determine how many candidate beams to
+   * explore.
+   */
+  best_of?: number;
+
+  /**
+   * This is used with `use_beam_search`. If `true`, generation stops as soon as
+   * there are `best_of` complete candidates; if `false`, a heuristic is applied and
+   * the generation stops when is it very unlikely to find better candidates.
+   */
+  early_stopping?: boolean;
+
+  /**
+   * Whether to enable the thinking/reasoning phase for models that support it (e.g.,
+   * QwQ, Qwen3). When set to false, the model will skip the internal reasoning step
+   * and respond directly, which can reduce latency. Defaults to true.
+   */
+  enable_thinking?: boolean;
+
+  /**
+   * Higher values will penalize the model from repeating the same output tokens.
+   */
+  frequency_penalty?: number;
+
+  /**
+   * If specified, the output will be exactly one of the choices.
+   */
+  guided_choice?: Array<string>;
+
+  /**
+   * Must be a valid JSON schema. If specified, the output will follow the JSON
+   * schema.
+   */
+  guided_json?: { [key: string]: unknown };
+
+  /**
+   * If specified, the output will follow the regex pattern.
+   */
+  guided_regex?: string;
+
+  /**
+   * This is used with `use_beam_search` to prefer shorter or longer completions.
+   */
+  length_penalty?: number;
+
+  /**
+   * Whether to return log probabilities of the output tokens or not. If true,
+   * returns the log probabilities of each output token returned in the `content` of
+   * `message`.
+   */
+  logprobs?: boolean;
+
+  /**
+   * Maximum number of completion tokens the model should generate.
+   */
+  max_tokens?: number;
+
+  /**
+   * This is an alternative to `top_p` that
+   * [many prefer](https://github.com/huggingface/transformers/issues/27670). Must be
+   * in [0, 1].
+   */
+  min_p?: number;
+
+  /**
+   * The language model to chat with.
+   */
+  model?: string;
+
+  /**
+   * This will return multiple choices for you instead of a single chat completion.
+   */
+  n?: number;
+
+  /**
+   * Higher values will penalize the model from repeating the same output tokens.
+   */
+  presence_penalty?: number;
+
+  /**
+   * Use this is you want to guarantee a JSON output without defining a schema. For
+   * control over the schema, use `guided_json`.
+   */
+  response_format?: ChatCompletionRequest.ResponseFormat;
+
+  /**
+   * If specified, the system will make a best effort to sample deterministically,
+   * such that repeated requests with the same `seed` and parameters should return
+   * the same result.
+   */
+  seed?: number;
+
+  /**
+   * Up to 4 sequences where the API will stop generating further tokens. The
+   * returned text will not contain the stop sequence.
+   */
+  stop?: string | Array<string>;
+
+  /**
+   * Whether or not to stream data-only server-sent events as they become available.
+   */
+  stream?: boolean;
+
+  /**
+   * Adjusts the "creativity" of the model. Lower values make the model more
+   * deterministic and repetitive, while higher values make the model more random and
+   * creative.
+   */
+  temperature?: number;
+
+  tool_choice?: 'none' | 'auto' | 'required';
+
+  /**
+   * The `function` tool type follows the same schema as the
+   * [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat).
+   * The `retrieval` tool type is unique to Telnyx. You may pass a list of
+   * [embedded storage buckets](https://developers.telnyx.com/api-reference/embeddings/embed-documents)
+   * for retrieval-augmented generation.
+   */
+  tools?: Array<ChatCompletionRequest.Function | ChatCompletionRequest.Retrieval>;
+
+  /**
+   * This is used with `logprobs`. An integer between 0 and 20 specifying the number
+   * of most likely tokens to return at each token position, each with an associated
+   * log probability.
+   */
+  top_logprobs?: number;
+
+  /**
+   * An alternative or complement to `temperature`. This adjusts how many of the top
+   * possibilities to consider.
+   */
+  top_p?: number;
+
+  /**
+   * Setting this to `true` will allow the model to
+   * [explore more completion options](https://huggingface.co/blog/how-to-generate#beam-search).
+   * This is not supported by OpenAI.
+   */
+  use_beam_search?: boolean;
+}
+
+export namespace ChatCompletionRequest {
+  export interface Message {
+    content: string | Array<Message.TextAndImageArray>;
+
+    role: 'system' | 'user' | 'assistant' | 'tool';
+  }
+
+  export namespace Message {
+    export interface TextAndImageArray {
+      type: 'text' | 'image_url';
+
+      image_url?: string;
+
+      text?: string;
+    }
+  }
+
+  /**
+   * Use this is you want to guarantee a JSON output without defining a schema. For
+   * control over the schema, use `guided_json`.
+   */
+  export interface ResponseFormat {
+    type: 'text' | 'json_object';
+  }
+
+  export interface Function {
+    function: Function.Function;
+
+    type: 'function';
+  }
+
+  export namespace Function {
+    export interface Function {
+      name: string;
+
+      description?: string;
+
+      parameters?: { [key: string]: unknown };
+    }
+  }
+
+  export interface Retrieval {
+    retrieval: ChatAPI.BucketIDs;
+
+    type: 'retrieval';
+  }
+}
+
 export type ChatCreateCompletionResponse = { [key: string]: unknown };
 
 export interface ChatCreateCompletionParams {
@@ -249,6 +454,7 @@ export namespace ChatCreateCompletionParams {
 export declare namespace Chat {
   export {
     type BucketIDs as BucketIDs,
+    type ChatCompletionRequest as ChatCompletionRequest,
     type ChatCreateCompletionResponse as ChatCreateCompletionResponse,
     type ChatCreateCompletionParams as ChatCreateCompletionParams,
   };

package/src/resources/ai/clusters.ts

@@ -228,6 +228,9 @@ export interface ClusterComputeParams {
 }
 
 export interface ClusterFetchGraphParams {
+  /**
+   * Filter results by cluster id.
+   */
   cluster_id?: number;
 }