telnyx 7.26.0 → 7.27.0

package/src/resources/messages/rcs.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../../core/resource';
 import * as MessagesAPI from './messages';
 import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
@@ -43,8 +44,16 @@ export class Rcs extends APIResource {
    * });
    * ```
    */
-  send(body: RcSendParams, options?: RequestOptions): APIPromise<RcSendResponse> {
-    return this._client.post('/messages/rcs', { body, ...options });
+  send(params: RcSendParams, options?: RequestOptions): APIPromise<RcSendResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/messages/rcs', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 }
 
@@ -128,35 +137,56 @@ export interface RcGenerateDeeplinkParams {
 
 export interface RcSendParams {
   /**
-   * RCS Agent ID
+   * Body param: RCS Agent ID
    */
   agent_id: string;
 
+  /**
+   * Body param
+   */
   agent_message: MessagesAPI.RcsAgentMessage;
 
   /**
-   * A valid messaging profile ID
+   * Body param: A valid messaging profile ID
    */
   messaging_profile_id: string;
 
   /**
-   * Phone number in +E.164 format
+   * Body param: Phone number in +E.164 format
    */
   to: string;
 
+  /**
+   * Body param
+   */
   mms_fallback?: RcSendParams.MmsFallback;
 
+  /**
+   * Body param
+   */
   sms_fallback?: RcSendParams.SMSFallback;
 
   /**
-   * Message type - must be set to "RCS"
+   * Body param: Message type - must be set to "RCS"
    */
   type?: 'RCS';
 
   /**
-   * The URL where webhooks related to this message will be sent.
+   * Body param: The URL where webhooks related to this message will be sent.
    */
   webhook_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;
 }
 
 export namespace RcSendParams {

package/src/resources/phone-numbers/csv-downloads.ts

@@ -44,8 +44,11 @@ export class CsvDownloads extends APIResource {
     params: CsvDownloadCreateParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<CsvDownloadCreateResponse> {
-    const { csv_format, filter } = params ?? {};
-    return this._client.post('/phone_numbers/csv_downloads', { query: { csv_format, filter }, ...options });
+    const { csv_format, filter, include_managed_accounts } = params ?? {};
+    return this._client.post('/phone_numbers/csv_downloads', {
+      query: { csv_format, filter, include_managed_accounts },
+      ...options,
+    });
   }
 
   /**
@@ -113,6 +116,16 @@ export interface CsvDownloadCreateParams {
    * filter[emergency_address_id], filter[customer_reference]
    */
   filter?: CsvDownloadCreateParams.Filter;
+
+  /**
+   * When true, the CSV includes phone numbers from all managed accounts in addition
+   * to the requesting account's own numbers. Only applies to V2 format; ignored for
+   * V1. The export appends `user_id` and `email` columns identifying the account
+   * that owns each number. When a filter is provided, it applies to the combined set
+   * of numbers. Requires access to managed accounts; requests without that access
+   * are rejected.
+   */
+  include_managed_accounts?: boolean;
 }
 
 export namespace CsvDownloadCreateParams {

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

@@ -22,6 +22,7 @@ export {
 } from './csv-downloads';
 export {
   Jobs,
+  type NumbersPhoneNumbersJob,
   type PhoneNumbersJob,
   type JobRetrieveResponse,
   type JobDeleteBatchResponse,
@@ -31,7 +32,7 @@ export {
   type JobDeleteBatchParams,
   type JobUpdateEmergencySettingsBatchParams,
   type JobUpdateBatchParams,
-  type PhoneNumbersJobsDefaultFlatPagination,
+  type NumbersPhoneNumbersJobsDefaultFlatPagination,
 } from './jobs';
 export {
   Messaging,
@@ -42,6 +43,7 @@ export {
 } from './messaging';
 export {
   PhoneNumbers,
+  type NumbersError73c9788e53,
   type NumbersPhoneNumberDetailed,
   type PhoneNumberDetailed,
   type PhoneNumberRetrieveResponse,

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

@@ -3,6 +3,7 @@
 import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
 import * as JobsAPI from '../phone-number-blocks/jobs';
+import * as PhoneNumbersAPI from './phone-numbers';
 import * as VoiceAPI from './voice';
 import { APIPromise } from '../../core/api-promise';
 import { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../../core/pagination';
@@ -23,7 +24,7 @@ export class Jobs extends APIResource {
    * @example
    * ```ts
    * // Automatically fetches more pages as needed.
-   * for await (const phoneNumbersJob of client.phoneNumbers.jobs.list()) {
+   * for await (const numbersPhoneNumbersJob of client.phoneNumbers.jobs.list()) {
    *   // ...
    * }
    * ```
@@ -31,8 +32,8 @@ export class Jobs extends APIResource {
   list(
     query: JobListParams | null | undefined = {},
     options?: RequestOptions,
-  ): PagePromise<PhoneNumbersJobsDefaultFlatPagination, PhoneNumbersJob> {
-    return this._client.getAPIList('/phone_numbers/jobs', DefaultFlatPagination<PhoneNumbersJob>, {
+  ): PagePromise<NumbersPhoneNumbersJobsDefaultFlatPagination, NumbersPhoneNumbersJob> {
+    return this._client.getAPIList('/phone_numbers/jobs', DefaultFlatPagination<NumbersPhoneNumbersJob>, {
       query,
       ...options,
     });
@@ -128,7 +129,301 @@ export class Jobs extends APIResource {
   }
 }
 
-export type PhoneNumbersJobsDefaultFlatPagination = DefaultFlatPagination<PhoneNumbersJob>;
+export type NumbersPhoneNumbersJobsDefaultFlatPagination = DefaultFlatPagination<NumbersPhoneNumbersJob>;
+
+export interface NumbersPhoneNumbersJob {
+  /**
+   * Identifies the resource.
+   */
+  id?: string;
+
+  /**
+   * ISO 8601 formatted date indicating when the resource was created.
+   */
+  created_at?: string;
+
+  /**
+   * ISO 8601 formatted date indicating when the estimated time of completion of the
+   * background job.
+   */
+  etc?: string;
+
+  failed_operations?: Array<NumbersPhoneNumbersJob.FailedOperation>;
+
+  /**
+   * Effective parameters saved when the job was created, not a snapshot of the
+   * original HTTP request or current phone-number settings. Update jobs include the
+   * saved update fields; emergency-settings jobs include the saved emergency fields;
+   * delete jobs include only targets. Absent fields are omitted, and saved false,
+   * null and empty values are preserved. Tags may be normalized to arrays;
+   * filter-created jobs contain resolved target identifiers rather than the original
+   * filters. Historical jobs with no saved arguments return an empty object.
+   */
+  parameters?: NumbersPhoneNumbersJob.Parameters;
+
+  pending_operations?: Array<NumbersPhoneNumbersJob.PendingOperation>;
+
+  phone_numbers?: Array<Shared.PhoneNumbersJobPhoneNumber>;
+
+  /**
+   * Identifies the type of the resource.
+   */
+  record_type?: string;
+
+  /**
+   * Indicates the completion status of the background update.
+   */
+  status?: 'pending' | 'in_progress' | 'completed' | 'failed' | 'expired';
+
+  successful_operations?: Array<NumbersPhoneNumbersJob.SuccessfulOperation>;
+
+  /**
+   * Identifies the type of the background job.
+   */
+  type?: 'update_emergency_settings' | 'delete_phone_numbers' | 'update_phone_numbers';
+
+  /**
+   * ISO 8601 formatted date indicating when the resource was updated.
+   */
+  updated_at?: string;
+}
+
+export namespace NumbersPhoneNumbersJob {
+  export interface FailedOperation {
+    /**
+     * The phone number's ID
+     */
+    id?: string;
+
+    errors?: Array<PhoneNumbersAPI.NumbersError73c9788e53>;
+
+    /**
+     * The phone number in e164 format.
+     */
+    phone_number?: string;
+  }
+
+  /**
+   * Effective parameters saved when the job was created, not a snapshot of the
+   * original HTTP request or current phone-number settings. Update jobs include the
+   * saved update fields; emergency-settings jobs include the saved emergency fields;
+   * delete jobs include only targets. Absent fields are omitted, and saved false,
+   * null and empty values are preserved. Tags may be normalized to arrays;
+   * filter-created jobs contain resolved target identifiers rather than the original
+   * filters. Historical jobs with no saved arguments return an empty object.
+   */
+  export interface Parameters {
+    /**
+     * Saved add_tags for an update_phone_numbers job. Values reflect creation-time
+     * normalization.
+     */
+    add_tags?: Array<string> | null;
+
+    /**
+     * Saved billing_group_id supplied for an update_phone_numbers job.
+     */
+    billing_group_id?: string | null;
+
+    /**
+     * Saved connection_id supplied for an update_phone_numbers job.
+     */
+    connection_id?: string | null;
+
+    /**
+     * Saved customer_reference supplied for an update_phone_numbers job.
+     */
+    customer_reference?: string | null;
+
+    /**
+     * Saved deletion_lock_enabled supplied for an update_phone_numbers job.
+     */
+    deletion_lock_enabled?: boolean | null;
+
+    /**
+     * Saved emergency address identifier for an update_emergency_settings job. An
+     * explicitly supplied null is preserved.
+     */
+    emergency_address_id?: string | null;
+
+    /**
+     * Saved emergency-services setting for an update_emergency_settings job.
+     */
+    emergency_enabled?: boolean | null;
+
+    /**
+     * Saved external_pin supplied for an update_phone_numbers job.
+     */
+    external_pin?: string | null;
+
+    /**
+     * Saved hd_voice_enabled supplied for an update_phone_numbers job.
+     */
+    hd_voice_enabled?: boolean | null;
+
+    /**
+     * Saved target phone numbers in E.164 format and/or identifiers. Jobs created
+     * using filters contain the resolved identifiers, not the original filter
+     * expression. Stored identifier types are preserved.
+     */
+    phone_numbers?: Array<string | number>;
+
+    /**
+     * Saved remove_tags for an update_phone_numbers job. Values reflect creation-time
+     * normalization.
+     */
+    remove_tags?: Array<string> | null;
+
+    /**
+     * Saved tags for an update_phone_numbers job. Values reflect creation-time
+     * normalization.
+     */
+    tags?: Array<string> | null;
+
+    /**
+     * Saved voice settings for an update_phone_numbers job, using the public field
+     * names and nesting. Only settings present at creation are returned.
+     */
+    voice?: Parameters.Voice;
+  }
+
+  export namespace Parameters {
+    /**
+     * Saved voice settings for an update_phone_numbers job, using the public field
+     * names and nesting. Only settings present at creation are returned.
+     */
+    export interface Voice {
+      call_forwarding?: Voice.CallForwarding;
+
+      call_recording?: Voice.CallRecording;
+
+      /**
+       * Saved caller_id_name_enabled setting.
+       */
+      caller_id_name_enabled?: boolean | null;
+
+      cnam_listing?: Voice.CnamListing;
+
+      /**
+       * Saved inbound_call_screening setting.
+       */
+      inbound_call_screening?: string | null;
+
+      media_features?: Voice.MediaFeatures;
+
+      /**
+       * Saved tech_prefix_enabled setting.
+       */
+      tech_prefix_enabled?: boolean | null;
+
+      /**
+       * Saved usage_payment_method setting.
+       */
+      usage_payment_method?: string | null;
+    }
+
+    export namespace Voice {
+      export interface CallForwarding {
+        /**
+         * Saved call_forwarding_enabled setting.
+         */
+        call_forwarding_enabled?: boolean | null;
+
+        /**
+         * Saved forwarding_type setting.
+         */
+        forwarding_type?: string | null;
+
+        /**
+         * Saved forwards_to setting.
+         */
+        forwards_to?: string | null;
+      }
+
+      export interface CallRecording {
+        /**
+         * Saved inbound_call_recording_channels setting.
+         */
+        inbound_call_recording_channels?: string | null;
+
+        /**
+         * Saved inbound_call_recording_enabled setting.
+         */
+        inbound_call_recording_enabled?: boolean | null;
+
+        /**
+         * Saved inbound_call_recording_format setting.
+         */
+        inbound_call_recording_format?: string | null;
+
+        /**
+         * Saved record_continue_on_hold setting.
+         */
+        record_continue_on_hold?: boolean | null;
+      }
+
+      export interface CnamListing {
+        /**
+         * Saved cnam_listing_details setting.
+         */
+        cnam_listing_details?: string | null;
+
+        /**
+         * Saved cnam_listing_enabled setting.
+         */
+        cnam_listing_enabled?: boolean | null;
+      }
+
+      export interface MediaFeatures {
+        /**
+         * Saved accept_any_rtp_packets_enabled setting.
+         */
+        accept_any_rtp_packets_enabled?: boolean | null;
+
+        /**
+         * Saved rtp_auto_adjust_enabled setting.
+         */
+        rtp_auto_adjust_enabled?: boolean | null;
+
+        /**
+         * Saved t38_fax_gateway_enabled setting.
+         */
+        t38_fax_gateway_enabled?: boolean | null;
+      }
+    }
+  }
+
+  /**
+   * The phone numbers pending confirmation on update results. Entries in this list
+   * are transient, and will be moved to either successful_operations or
+   * failed_operations once the processing is done.
+   */
+  export interface PendingOperation {
+    /**
+     * The phone number's ID
+     */
+    id?: string;
+
+    /**
+     * The phone number in e164 format.
+     */
+    phone_number?: string;
+  }
+
+  /**
+   * The phone numbers successfully updated.
+   */
+  export interface SuccessfulOperation {
+    /**
+     * The phone number's ID
+     */
+    id?: string;
+
+    /**
+     * The phone number in e164 format.
+     */
+    phone_number?: string;
+  }
+}
 
 export interface PhoneNumbersJob {
   /**
@@ -225,19 +520,19 @@ export namespace PhoneNumbersJob {
 }
 
 export interface JobRetrieveResponse {
-  data?: PhoneNumbersJob;
+  data?: NumbersPhoneNumbersJob;
 }
 
 export interface JobDeleteBatchResponse {
-  data?: PhoneNumbersJob;
+  data?: NumbersPhoneNumbersJob;
 }
 
 export interface JobUpdateBatchResponse {
-  data?: PhoneNumbersJob;
+  data?: NumbersPhoneNumbersJob;
 }
 
 export interface JobUpdateEmergencySettingsBatchResponse {
-  data?: PhoneNumbersJob;
+  data?: NumbersPhoneNumbersJob;
 }
 
 export interface JobListParams extends DefaultFlatPaginationParams {
@@ -263,12 +558,15 @@ export namespace JobListParams {
    */
   export interface Filter {
     /**
-     * Returns jobs whose creation-time customer reference exactly matches the supplied
-     * value, not the current reference on a phone number. Only jobs within the lookup
-     * window (90 days by default) are returned. Supply a single non-blank string of up
-     * to 250 characters, without null characters, using
-     * `filter[customer_reference]=yourcustomerrefhere`. An invalid filter value
-     * returns HTTP 422.
+     * Exact, case-sensitive match for the customer reference supplied when the job was
+     * created. Only jobs created within the last 90 days are returned, including for
+     * accounts otherwise exempt from job retention limits. Searches the stored job
+     * reference, not the current reference on a phone number. Multiple jobs may share
+     * a reference. Combines with the other filters and account ownership. Supply a
+     * single non-blank string of up to 250 characters, without null characters, using
+     * `filter[customer_reference]=yourcustomerrefhere`. Whitespace is preserved; blank
+     * strings, arrays, and objects return HTTP 422. An invalid filter value returns
+     * HTTP 422. The literal string `null` is matched as text.
      */
     customer_reference?: string;
 
@@ -344,7 +642,12 @@ export interface JobUpdateBatchParams {
   connection_id?: string;
 
   /**
-   * Body param: A customer reference string for customer look ups.
+   * Body param: Sets the customer reference on the selected phone numbers and
+   * retains the supplied value on the job. Recover the job without its ID using GET
+   * /phone_numbers/jobs with filter[customer_reference] within 90 days of job
+   * creation. This body field updates the numbers; the separate
+   * filter[customer_reference] query parameter selects numbers by their current
+   * reference.
    */
   customer_reference?: string;
 
@@ -485,12 +788,13 @@ export namespace JobUpdateBatchParams {
 
 export declare namespace Jobs {
   export {
+    type NumbersPhoneNumbersJob as NumbersPhoneNumbersJob,
     type PhoneNumbersJob as PhoneNumbersJob,
     type JobRetrieveResponse as JobRetrieveResponse,
     type JobDeleteBatchResponse as JobDeleteBatchResponse,
     type JobUpdateBatchResponse as JobUpdateBatchResponse,
     type JobUpdateEmergencySettingsBatchResponse as JobUpdateEmergencySettingsBatchResponse,
-    type PhoneNumbersJobsDefaultFlatPagination as PhoneNumbersJobsDefaultFlatPagination,
+    type NumbersPhoneNumbersJobsDefaultFlatPagination as NumbersPhoneNumbersJobsDefaultFlatPagination,
     type JobListParams as JobListParams,
     type JobDeleteBatchParams as JobDeleteBatchParams,
     type JobUpdateEmergencySettingsBatchParams as JobUpdateEmergencySettingsBatchParams,

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

@@ -33,8 +33,9 @@ import {
   JobUpdateEmergencySettingsBatchParams,
   JobUpdateEmergencySettingsBatchResponse,
   Jobs,
+  NumbersPhoneNumbersJob,
+  NumbersPhoneNumbersJobsDefaultFlatPagination,
   PhoneNumbersJob,
-  PhoneNumbersJobsDefaultFlatPagination,
 } from './jobs';
 import * as MessagingAPI from './messaging';
 import {
@@ -186,6 +187,39 @@ export type NumbersPhoneNumberDetailedsDefaultFlatPagination =
 export type PhoneNumberSlimListResponsesDefaultFlatPagination =
   DefaultFlatPagination<PhoneNumberSlimListResponse>;
 
+export interface NumbersError73c9788e53 {
+  code?: string;
+
+  detail?: string;
+
+  meta?: NumbersError73c9788e53.Meta;
+
+  source?: NumbersError73c9788e53.Source;
+
+  title?: string;
+}
+
+export namespace NumbersError73c9788e53 {
+  export interface Meta {
+    /**
+     * URL with additional information on the error.
+     */
+    url?: string;
+  }
+
+  export interface Source {
+    /**
+     * Indicates which query parameter caused the error.
+     */
+    parameter?: string;
+
+    /**
+     * JSON pointer (RFC6901) to the offending entity.
+     */
+    pointer?: string;
+  }
+}
+
 export interface NumbersPhoneNumberDetailed {
   /**
    * Identifies the resource.
@@ -1276,6 +1310,7 @@ PhoneNumbers.Voicemail = Voicemail;
 
 export declare namespace PhoneNumbers {
   export {
+    type NumbersError73c9788e53 as NumbersError73c9788e53,
     type NumbersPhoneNumberDetailed as NumbersPhoneNumberDetailed,
     type PhoneNumberDetailed as PhoneNumberDetailed,
     type PhoneNumberRetrieveResponse as PhoneNumberRetrieveResponse,
@@ -1312,12 +1347,13 @@ export declare namespace PhoneNumbers {
 
   export {
     Jobs as Jobs,
+    type NumbersPhoneNumbersJob as NumbersPhoneNumbersJob,
     type PhoneNumbersJob as PhoneNumbersJob,
     type JobRetrieveResponse as JobRetrieveResponse,
     type JobDeleteBatchResponse as JobDeleteBatchResponse,
     type JobUpdateBatchResponse as JobUpdateBatchResponse,
     type JobUpdateEmergencySettingsBatchResponse as JobUpdateEmergencySettingsBatchResponse,
-    type PhoneNumbersJobsDefaultFlatPagination as PhoneNumbersJobsDefaultFlatPagination,
+    type NumbersPhoneNumbersJobsDefaultFlatPagination as NumbersPhoneNumbersJobsDefaultFlatPagination,
     type JobListParams as JobListParams,
     type JobDeleteBatchParams as JobDeleteBatchParams,
     type JobUpdateEmergencySettingsBatchParams as JobUpdateEmergencySettingsBatchParams,

package/src/resources/porting-orders/phone-number-blocks.ts

@@ -133,6 +133,7 @@ export interface PortingPhoneNumberBlock {
   phone_number_type?:
     | 'landline'
     | 'local'
+    | 'localcommercial'
     | 'mobile'
     | 'multipurpose'
     | 'national'

package/src/resources/porting-orders/porting-orders.ts

@@ -420,6 +420,7 @@ export interface PortingOrder {
   phone_number_type?:
     | 'landline'
     | 'local'
+    | 'localcommercial'
     | 'mobile'
     | 'multipurpose'
     | 'national'

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

@@ -59,6 +59,7 @@ export interface PortingPhoneNumber {
   phone_number_type?:
     | 'landline'
     | 'local'
+    | 'localcommercial'
     | 'mobile'
     | 'multipurpose'
     | 'national'

package/src/resources/shared.ts

@@ -10,6 +10,11 @@ export interface APIError {
 
   description?: string;
 
+  /**
+   * A human-readable explanation of the error.
+   */
+  detail?: string;
+
   meta?: { [key: string]: unknown };
 
   source?: APIError.Source;