telnyx 7.13.0 → 7.14.0

package/src/resources/ai/tools.ts

@@ -11,7 +11,7 @@ import { path } from '../../internal/utils/path';
  */
 export class Tools extends APIResource {
   /**
-   * List Tools
+   * Retrieve a list of the custom AI tools configured on your account.
    *
    * @example
    * ```ts
@@ -32,7 +32,7 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Create Tool
+   * Create a new custom AI tool that can be attached to AI assistants.
    *
    * @example
    * ```ts
@@ -47,7 +47,7 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Delete Tool
+   * Delete a custom AI tool.
    *
    * @example
    * ```ts
@@ -59,7 +59,7 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Get Tool
+   * Retrieve the details of a specific AI tool.
    *
    * @example
    * ```ts
@@ -73,7 +73,7 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Update Tool
+   * Update the configuration of an existing AI tool.
    *
    * @example
    * ```ts
@@ -126,6 +126,52 @@ export interface SharedToolResponse {
   timeout_ms?: number;
 }
 
+/**
+ * Configuration for an update_dynamic_variables tool.
+ */
+export interface UpdateDynamicVariablesToolParams {
+  /**
+   * Description of the tool passed to the assistant, guiding when to call it and
+   * which variables to update.
+   */
+  description: string;
+
+  /**
+   * The function name surfaced to the LLM. Must match the OpenAI function-name
+   * pattern `^[a-zA-Z0-9_-]+$` and be unique across the assistant's function,
+   * webhook, and client_side tools.
+   */
+  name: string;
+
+  /**
+   * The dynamic variables the assistant is allowed to write. At least one is
+   * required.
+   */
+  updatable_variables: Array<UpdateDynamicVariablesToolParams.UpdatableVariable>;
+}
+
+export namespace UpdateDynamicVariablesToolParams {
+  export interface UpdatableVariable {
+    /**
+     * The dynamic-variable key to update. Must match `^[a-zA-Z0-9._-]+$` and may not
+     * start with the reserved `telnyx_` prefix (reserved for system variables). The
+     * `pattern` encodes both rules via a negative lookahead.
+     */
+    name: string;
+
+    /**
+     * Optional description of the variable, guiding the assistant on what value to
+     * capture.
+     */
+    description?: string;
+
+    /**
+     * Optional hint for the variable's value type (e.g. `string`).
+     */
+    type?: string;
+  }
+}
+
 export type ToolDeleteResponse = unknown;
 
 export interface ToolListParams extends DefaultFlatPaginationParams {
@@ -159,6 +205,11 @@ export interface ToolCreateParams {
 
   timeout_ms?: number;
 
+  /**
+   * Configuration for an update_dynamic_variables tool.
+   */
+  update_dynamic_variables?: UpdateDynamicVariablesToolParams;
+
   webhook?: { [key: string]: unknown };
 
   [k: string]: unknown;
@@ -183,6 +234,11 @@ export interface ToolUpdateParams {
 
   type?: string;
 
+  /**
+   * Configuration for an update_dynamic_variables tool.
+   */
+  update_dynamic_variables?: UpdateDynamicVariablesToolParams;
+
   webhook?: { [key: string]: unknown };
 
   [k: string]: unknown;
@@ -192,6 +248,7 @@ export declare namespace Tools {
   export {
     type PayToolParams as PayToolParams,
     type SharedToolResponse as SharedToolResponse,
+    type UpdateDynamicVariablesToolParams as UpdateDynamicVariablesToolParams,
     type ToolDeleteResponse as ToolDeleteResponse,
     type SharedToolResponsesDefaultFlatPagination as SharedToolResponsesDefaultFlatPagination,
     type ToolListParams as ToolListParams,

package/src/resources/alphanumeric-sender-ids.ts

@@ -106,6 +106,16 @@ export interface AlphanumericSenderID {
   us_long_code_fallback?: string;
 }
 
+export interface MessagingPaginationMeta0b38e7044b {
+  page_number: number;
+
+  page_size: number;
+
+  total_pages: number;
+
+  total_results: number;
+}
+
 export interface AlphanumericSenderIDCreateResponse {
   data?: AlphanumericSenderID;
 }
@@ -145,6 +155,7 @@ export interface AlphanumericSenderIDCreateParams {
 export declare namespace AlphanumericSenderIDs {
   export {
     type AlphanumericSenderID as AlphanumericSenderID,
+    type MessagingPaginationMeta0b38e7044b as MessagingPaginationMeta0b38e7044b,
     type AlphanumericSenderIDCreateResponse as AlphanumericSenderIDCreateResponse,
     type AlphanumericSenderIDRetrieveResponse as AlphanumericSenderIDRetrieveResponse,
     type AlphanumericSenderIDDeleteResponse as AlphanumericSenderIDDeleteResponse,

package/src/resources/available-phone-number-blocks.ts

@@ -10,7 +10,9 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class AvailablePhoneNumberBlocks extends APIResource {
   /**
-   * List available phone number blocks
+   * Searches the Telnyx inventory for available contiguous phone-number blocks.
+   * Results can be filtered by locality, country, national destination code, and
+   * number type.
    */
   list(
     query: AvailablePhoneNumberBlockListParams | null | undefined = {},

package/src/resources/available-phone-numbers.ts

@@ -10,7 +10,10 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class AvailablePhoneNumbers extends APIResource {
   /**
-   * List available phone numbers
+   * Searches the Telnyx inventory for available phone numbers. Filters support
+   * number patterns, location, number type, features, reservability, and other
+   * inventory constraints; the response includes matching numbers and search
+   * metadata.
    */
   list(
     query: AvailablePhoneNumberListParams | null | undefined = {},

package/src/resources/balance.ts

@@ -9,7 +9,8 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class Balance extends APIResource {
   /**
-   * Get user balance details
+   * Retrieve the current balance, available credit, and credit limit for your
+   * account.
    */
   retrieve(options?: RequestOptions): APIPromise<BalanceRetrieveResponse> {
     return this._client.get('/balance', options);

package/src/resources/billing-groups.ts

@@ -11,7 +11,7 @@ import { path } from '../internal/utils/path';
  */
 export class BillingGroups extends APIResource {
   /**
-   * List all billing groups
+   * Retrieve a paginated list of billing groups on your account.
    *
    * @example
    * ```ts
@@ -32,7 +32,8 @@ export class BillingGroups extends APIResource {
   }
 
   /**
-   * Create a billing group
+   * Create a new billing group, which can be used to organize resources for billing
+   * purposes.
    *
    * @example
    * ```ts
@@ -46,7 +47,7 @@ export class BillingGroups extends APIResource {
   }
 
   /**
-   * Delete a billing group
+   * Delete a billing group from your account.
    *
    * @example
    * ```ts
@@ -60,7 +61,7 @@ export class BillingGroups extends APIResource {
   }
 
   /**
-   * Get a billing group
+   * Retrieve the details of a specific billing group.
    *
    * @example
    * ```ts
@@ -74,7 +75,7 @@ export class BillingGroups extends APIResource {
   }
 
   /**
-   * Update a billing group
+   * Update the properties of an existing billing group.
    *
    * @example
    * ```ts

package/src/resources/calls/actions.ts

@@ -757,7 +757,8 @@ export class Actions extends APIResource {
   }
 
   /**
-   * Noise Suppression Start (BETA)
+   * Start noise suppression on an active call to reduce background noise. This
+   * feature is currently in beta.
    *
    * @example
    * ```ts
@@ -776,7 +777,8 @@ export class Actions extends APIResource {
   }
 
   /**
-   * Noise Suppression Stop (BETA)
+   * Stop noise suppression previously started on an active call. This feature is
+   * currently in beta.
    *
    * @example
    * ```ts

package/src/resources/channel-zones.ts

@@ -16,6 +16,14 @@ export class ChannelZones extends APIResource {
    * <a href="https://support.telnyx.com/en/articles/8428806-global-channel-billing">Telnyx
    * Support Articles</a> section for full information and examples of how to utilize
    * Channel Billing.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const gcbChannelZone of client.channelZones.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: ChannelZoneListParams | null | undefined = {},
@@ -32,6 +40,14 @@ export class ChannelZones extends APIResource {
    * account to handle multiple simultaneous inbound calls to Non-US numbers. Use
    * this endpoint to increase or decrease your capacity based on expected call
    * volume.
+   *
+   * @example
+   * ```ts
+   * const gcbChannelZone = await client.channelZones.update(
+   *   'channel_zone_id',
+   *   { channels: 0 },
+   * );
+   * ```
    */
   update(
     channelZoneID: string,

package/src/resources/comments.ts

@@ -12,7 +12,8 @@ import { path } from '../internal/utils/path';
  */
 export class Comments extends APIResource {
   /**
-   * Retrieve all comments
+   * Returns comments associated with number-order records. Results can be filtered
+   * by record type and record ID and include pagination metadata.
    *
    * @example
    * ```ts
@@ -27,7 +28,8 @@ export class Comments extends APIResource {
   }
 
   /**
-   * Create a comment
+   * Creates a comment associated with a supported number-order record. The response
+   * contains the created comment.
    *
    * @example
    * ```ts
@@ -39,7 +41,8 @@ export class Comments extends APIResource {
   }
 
   /**
-   * Retrieve a comment
+   * Returns the comment identified by `id`, including its associated record and
+   * comment metadata.
    *
    * @example
    * ```ts
@@ -51,7 +54,8 @@ export class Comments extends APIResource {
   }
 
   /**
-   * Mark a comment as read
+   * Marks the specified comment as read. The response contains the updated read
+   * state for the comment.
    *
    * @example
    * ```ts

package/src/resources/credential-connections/credential-connections.ts

@@ -176,6 +176,13 @@ export interface CredentialConnection {
 
   connection_name?: string;
 
+  /**
+   * Whether conversation persistence is enabled for this connection. When enabled,
+   * calls handled by the connection are transcribed, stored, and indexed. Defaults
+   * to false.
+   */
+  conversation_persistence?: boolean;
+
   /**
    * ISO-8601 formatted date indicating when the resource was created.
    */
@@ -718,6 +725,13 @@ export interface CredentialConnectionUpdateParams {
    */
   connection_name?: string;
 
+  /**
+   * Whether conversation persistence is enabled for this connection. When enabled,
+   * calls handled by the connection are transcribed, stored, and indexed. Defaults
+   * to false.
+   */
+  conversation_persistence?: boolean;
+
   /**
    * When enabled, Telnyx will generate comfort noise when you place the call on
    * hold. If disabled, you will need to generate comfort noise or on hold music to

package/src/resources/email-blocks/email-blocks.ts

@@ -27,6 +27,14 @@ export class EmailBlocks extends APIResource {
    *
    * Sort defaults to `-created_at` (desc); only `created_at` is sortable. A `--`
    * prefix is an error. `nil`/empty filter values are silently dropped.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const emailBlock of client.emailBlocks.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: EmailBlockListParams | null | undefined = {},
@@ -46,6 +54,14 @@ export class EmailBlocks extends APIResource {
    * `bounce_category`, `dsn_code`, `meta`, and `group_id` are **not accepted** on
    * the public surface. Use the unsubscribe-group suppression endpoint or the
    * internal create surface for those.
+   *
+   * @example
+   * ```ts
+   * const emailBlockResponse = await client.emailBlocks.create({
+   *   to: 'spammer@bad.tld',
+   *   expires_at: '2026-12-31T23:59:59Z',
+   * });
+   * ```
    */
   create(body: EmailBlockCreateParams, options?: RequestOptions): APIPromise<EmailBlockResponse> {
     return this._client.post('/email_blocks', { body, ...options });
@@ -65,6 +81,11 @@ export class EmailBlocks extends APIResource {
    * `id,to,from,reason,source,scope,status,domain_id, created_at,updated_at,expires_at,group_id`.
    * The CSV carries the `group_id` column so group-scoped suppressions' group link
    * survives the export (empty for account-scope rows).
+   *
+   * @example
+   * ```ts
+   * const response = await client.emailBlocks.retrieveExport();
+   * ```
    */
   retrieveExport(
     query: EmailBlockRetrieveExportParams | null | undefined = {},
@@ -81,13 +102,29 @@ export class EmailBlocks extends APIResource {
    * Soft-deletes (status → `removed`; tombstone retained). A `removed` audit event
    * is appended unless the block was already `removed` (idempotent — returns the
    * existing row with `200` and no new event). Mutates `updated_at`.
+   *
+   * @example
+   * ```ts
+   * const emailBlockResponse = await client.emailBlocks.delete(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   delete(id: string, options?: RequestOptions): APIPromise<EmailBlockResponse> {
     return this._client.delete(path`/email_blocks/${id}`, options);
   }
 
   /**
-   * Retrieve a suppression
+   * Returns the account-owned suppression identified by ID. Cross-account lookups
+   * and malformed IDs return `404` without exposing another account’s data.
+   *
+   * @example
+   * ```ts
+   * const emailBlockResponse =
+   *   await client.emailBlocks.retrieve(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   );
+   * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<EmailBlockResponse> {
     return this._client.get(path`/email_blocks/${id}`, options);
@@ -98,6 +135,13 @@ export class EmailBlocks extends APIResource {
    * max 100). No `sort`, no `filter`, no cursor — ordering is fixed
    * `desc occurred_at, desc id`. Verifies the block belongs to the account first
    * (cross-account → 404).
+   *
+   * @example
+   * ```ts
+   * const response = await client.emailBlocks.retrieveEvents(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   retrieveEvents(
     id: string,

package/src/resources/email-blocks/import.ts

@@ -23,6 +23,15 @@ export class Import extends APIResource {
    *   `block_ttl_days` applies only to imported `manual_block` rows; other reasons
    *   get `expires_at: nil`. Provider is auto-detected from the CSV header
    *   (`sendgrid` / `mailgun` / `ses` / `generic`).
+   *
+   * @example
+   * ```ts
+   * const emailBlockImportResponse =
+   *   await client.emailBlocks.import.create({
+   *     file: fs.createReadStream('path/to/file'),
+   *     block_ttl_days: 30,
+   *   });
+   * ```
    */
   create(body: ImportCreateParams, options?: RequestOptions): APIPromise<EmailBlockImportResponse> {
     return this._client.post(
@@ -37,6 +46,14 @@ export class Import extends APIResource {
    * `processed_rows`/`created_count`/`existing_count`/ `skipped_count`/`error_count`
    * only when `status == completed`; `errors` only when non-empty; `failure_reason`
    * only on terminal failure.
+   *
+   * @example
+   * ```ts
+   * const emailBlockImportResponse =
+   *   await client.emailBlocks.import.retrieve(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   );
+   * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<EmailBlockImportResponse> {
     return this._client.get(path`/email_blocks/import/${id}`, options);

package/src/resources/email-domains/email-domains.ts

@@ -47,7 +47,8 @@ export class EmailDomains extends APIResource {
   }
 
   /**
-   * Create an email domain
+   * Registers a domain for email sending and optional inbound delivery. The response
+   * includes the domain configuration and current verification state.
    *
    * @example
    * ```ts
@@ -68,7 +69,8 @@ export class EmailDomains extends APIResource {
   }
 
   /**
-   * List DNS records for an email domain
+   * Returns the DNS records Telnyx generated for domain ownership and DKIM
+   * verification, plus MX records when inbound delivery is enabled.
    *
    * @example
    * ```ts
@@ -86,7 +88,8 @@ export class EmailDomains extends APIResource {
   }
 
   /**
-   * Verify DNS records for an email domain
+   * Checks the published DNS records against the records required for the email
+   * domain and returns the latest verification results.
    *
    * @example
    * ```ts
@@ -101,7 +104,8 @@ export class EmailDomains extends APIResource {
   }
 
   /**
-   * Delete an email domain
+   * Deletes an email domain configuration. Verified domains require `force=true`,
+   * and shared domains are read-only for non-owner accounts.
    *
    * @example
    * ```ts
@@ -137,7 +141,9 @@ export class EmailDomains extends APIResource {
   }
 
   /**
-   * Update an email domain
+   * Updates mutable settings for an existing email domain, including inbound
+   * delivery and tracking configuration. Shared domains are read-only for non-owner
+   * accounts.
    *
    * @example
    * ```ts

package/src/resources/email-domains/webhooks.ts

@@ -11,7 +11,8 @@ import { path } from '../../internal/utils/path';
  */
 export class Webhooks extends APIResource {
   /**
-   * List webhooks for an email domain
+   * Returns a paginated list of webhook subscriptions scoped to the email domain.
+   * Results can be sorted by creation time.
    *
    * @example
    * ```ts
@@ -65,7 +66,8 @@ export class Webhooks extends APIResource {
   }
 
   /**
-   * Delete a webhook
+   * Deletes the webhook subscription identified by ID within the specified email
+   * domain and returns the deleted subscription.
    *
    * @example
    * ```ts
@@ -86,7 +88,8 @@ export class Webhooks extends APIResource {
   }
 
   /**
-   * Retrieve a webhook
+   * Returns the webhook subscription identified by ID within the specified email
+   * domain.
    *
    * @example
    * ```ts

package/src/resources/email-inboxes/drafts.ts

@@ -147,7 +147,11 @@ export class Drafts extends APIResource {
    * const emailDraftResponse =
    *   await client.emailInboxes.drafts.patch(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   *     { inbox_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
+   *     {
+   *       inbox_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *       subject: 'Quarterly update (revised)',
+   *       text_body: 'Updated body.',
+   *     },
    *   );
    * ```
    */

package/src/resources/email-templates.ts

@@ -54,7 +54,8 @@ export class EmailTemplates extends APIResource {
   }
 
   /**
-   * Delete an email template
+   * Deletes the account-owned template. The operation returns `204` with no body and
+   * prevents future sends or renders from using the deleted template ID.
    *
    * @example
    * ```ts
@@ -71,7 +72,8 @@ export class EmailTemplates extends APIResource {
   }
 
   /**
-   * Get an email template
+   * Returns the account-owned template identified by ID, including its Liquid
+   * subject and bodies, declared variables, and timestamps.
    *
    * @example
    * ```ts
@@ -94,6 +96,7 @@ export class EmailTemplates extends APIResource {
    * const emailTemplateResponse =
    *   await client.emailTemplates.replace(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     { subject: 'Welcome aboard, {{first_name}}!' },
    *   );
    * ```
    */
@@ -113,6 +116,7 @@ export class EmailTemplates extends APIResource {
    * const emailTemplateResponse =
    *   await client.emailTemplates.update(
    *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     { subject: 'Welcome aboard, {{first_name}}!' },
    *   );
    * ```
    */

package/src/resources/email-unsubscribe-groups/email-unsubscribe-groups.ts

@@ -26,6 +26,14 @@ export class EmailUnsubscribeGroups extends APIResource {
    * Uses the shared `QueryParser.parse_offset/1` — a malformed `page` (e.g. flat
    * `?page=1` instead of `?page[number]=1`) returns `400` (code `10015`), consistent
    * with `GET /v2/email_blocks`. `meta` includes `total_pages`.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const unsubscribeGroup of client.emailUnsubscribeGroups.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: EmailUnsubscribeGroupListParams | null | undefined = {},
@@ -38,7 +46,17 @@ export class EmailUnsubscribeGroups extends APIResource {
   }
 
   /**
-   * Create an unsubscribe group
+   * Creates an account-owned unsubscribe group for associating email categories with
+   * separate recipient suppression lists.
+   *
+   * @example
+   * ```ts
+   * const unsubscribeGroupResponse =
+   *   await client.emailUnsubscribeGroups.create({
+   *     name: 'Marketing Newsletter',
+   *     description: 'Weekly product updates and promotions',
+   *   });
+   * ```
    */
   create(
     body: EmailUnsubscribeGroupCreateParams,
@@ -54,6 +72,13 @@ export class EmailUnsubscribeGroups extends APIResource {
    * hard-deletes the group. Without `force` and active suppressions present → `409`.
    * Audit trail is preserved. `force` only accepts the string `"true"` or boolean
    * `true`; all other values are false.
+   *
+   * @example
+   * ```ts
+   * await client.emailUnsubscribeGroups.delete(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   delete(
     id: string,
@@ -69,7 +94,15 @@ export class EmailUnsubscribeGroups extends APIResource {
   }
 
   /**
-   * Retrieve an unsubscribe group
+   * Returns the account-owned unsubscribe group identified by ID.
+   *
+   * @example
+   * ```ts
+   * const unsubscribeGroupResponse =
+   *   await client.emailUnsubscribeGroups.retrieve(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   );
+   * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<UnsubscribeGroupResponse> {
     return this._client.get(path`/email_unsubscribe_groups/${id}`, options);
@@ -77,6 +110,17 @@ export class EmailUnsubscribeGroups extends APIResource {
 
   /**
    * Partial update (only `name` / `description`). `PUT` is not routed.
+   *
+   * @example
+   * ```ts
+   * const unsubscribeGroupResponse =
+   *   await client.emailUnsubscribeGroups.update(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     {
+   *       description: 'Weekly product updates and promotions',
+   *     },
+   *   );
+   * ```
    */
   update(
     id: string,