telnyx 7.25.0 → 7.27.0

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;

package/src/resources/sip-registration-status.ts

@@ -0,0 +1,188 @@
+// 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 { RequestOptions } from '../internal/request-options';
+
+/**
+ * UAC connection operations
+ */
+export class SipRegistrationStatus extends APIResource {
+  /**
+   * Returns the live SIP registration status for a Telnyx endpoint: whether it is
+   * currently registered, when the current registration expires, and the last
+   * response Telnyx received from the registrar.
+   *
+   * The endpoint supports three credential types, selected with the
+   * `credential_type` query parameter. Each type is keyed by a different identifier:
+   *
+   * | `credential_type`           | Keyed by        | Use case                                                                   |
+   * | --------------------------- | --------------- | -------------------------------------------------------------------------- |
+   * | `uac_external_credential`   | `connection_id` | A UAC (SIP attach) connection that registers to an external PBX.           |
+   * | `telephony_credential`      | `username`      | An ephemeral, one-time-use telephony credential.                           |
+   * | `sip_credential_connection` | `username`      | A traditional SIP credential connection that registers directly to Telnyx. |
+   *
+   * The authenticated account is taken from your API key; you can only read the
+   * registration status of connections and credentials your account owns.
+   */
+  list(
+    query: SipRegistrationStatusListParams,
+    options?: RequestOptions,
+  ): APIPromise<SipRegistrationStatusListResponse> {
+    return this._client.get('/sip_registration_status', { query, ...options });
+  }
+}
+
+export interface SipRegistrationStatusListResponse {
+  /**
+   * Identifier of the connection associated with the credential.
+   */
+  connection_id?: string;
+
+  /**
+   * Human-readable connection name.
+   */
+  connection_name?: string;
+
+  /**
+   * The credential type that was looked up.
+   */
+  credential_type?: 'uac_external_credential' | 'telephony_credential' | 'sip_credential_connection';
+
+  /**
+   * SIP username used for the registration.
+   */
+  credential_username?: string;
+
+  /**
+   * SIP response from the last registration attempt.
+   */
+  last_registration_response?: string | null;
+
+  /**
+   * True if the endpoint is currently registered.
+   */
+  registered?: boolean;
+
+  /**
+   * Detailed registration information reported by the registrar. The populated
+   * fields depend on `credential_type`: UAC external credentials report
+   * `auth_retries`, `uptime`, `next_action_at`, `failures`, and `sip_uri_user_host`;
+   * telephony credentials and SIP credential connections report `ua_ip`, `ua_port`,
+   * `transport`, and `last_modified`. All types report `expires`, but its unit
+   * differs by `credential_type` — see that field.
+   */
+  sip_registration_details?: SipRegistrationStatusListResponse.SipRegistrationDetails;
+
+  /**
+   * Human-readable registration status derived from the registrar state.
+   */
+  sip_registration_status?:
+    | 'unregistering'
+    | 'connection_disabled'
+    | 'standby'
+    | 'failed'
+    | 'trying'
+    | 'registered'
+    | 'unknown';
+}
+
+export namespace SipRegistrationStatusListResponse {
+  /**
+   * Detailed registration information reported by the registrar. The populated
+   * fields depend on `credential_type`: UAC external credentials report
+   * `auth_retries`, `uptime`, `next_action_at`, `failures`, and `sip_uri_user_host`;
+   * telephony credentials and SIP credential connections report `ua_ip`, `ua_port`,
+   * `transport`, and `last_modified`. All types report `expires`, but its unit
+   * differs by `credential_type` — see that field.
+   */
+  export interface SipRegistrationDetails {
+    /**
+     * Number of authentication retries on the last attempt (uac_external_credential).
+     */
+    auth_retries?: number;
+
+    /**
+     * When the current registration expires. The unit depends on `credential_type`:
+     * for `uac_external_credential` this is a Unix timestamp (seconds since epoch) of
+     * the next scheduled re-registration; for `telephony_credential` and
+     * `sip_credential_connection` this is the registration lifetime in seconds as
+     * negotiated with the registrar (the `Expires` value, defaulting to 3600 when the
+     * endpoint sends none).
+     */
+    expires?: number;
+
+    /**
+     * Count of consecutive registration failures (uac_external_credential).
+     */
+    failures?: number;
+
+    /**
+     * Timestamp when the registration was last modified (telephony_credential and
+     * sip_credential_connection).
+     */
+    last_modified?: string;
+
+    /**
+     * Unix timestamp of the next scheduled registration action
+     * (uac_external_credential).
+     */
+    next_action_at?: number;
+
+    /**
+     * SIP URI user@host of the registered contact (uac_external_credential).
+     */
+    sip_uri_user_host?: string;
+
+    /**
+     * Transport used for the registration, e.g. UDP/TCP/TLS (telephony_credential and
+     * sip_credential_connection).
+     */
+    transport?: string;
+
+    /**
+     * IP address of the registered user agent (telephony_credential and
+     * sip_credential_connection).
+     */
+    ua_ip?: string;
+
+    /**
+     * Port of the registered user agent (telephony_credential and
+     * sip_credential_connection).
+     */
+    ua_port?: number;
+
+    /**
+     * Registration uptime reported by the registrar (uac_external_credential).
+     */
+    uptime?: number;
+  }
+}
+
+export interface SipRegistrationStatusListParams {
+  /**
+   * The kind of credential to look up. `uac_external_credential` is keyed by
+   * `connection_id`; `telephony_credential` and `sip_credential_connection` are
+   * keyed by `username`.
+   */
+  credential_type: 'uac_external_credential' | 'telephony_credential' | 'sip_credential_connection';
+
+  /**
+   * Identifier of the UAC connection to look up. Required when `credential_type` is
+   * `uac_external_credential`.
+   */
+  connection_id?: string;
+
+  /**
+   * SIP username to look up. Required when `credential_type` is
+   * `telephony_credential` or `sip_credential_connection`.
+   */
+  username?: string;
+}
+
+export declare namespace SipRegistrationStatus {
+  export {
+    type SipRegistrationStatusListResponse as SipRegistrationStatusListResponse,
+    type SipRegistrationStatusListParams as SipRegistrationStatusListParams,
+  };
+}

package/src/resources/speech-to-text/speech-to-text.ts

@@ -263,9 +263,10 @@ export interface SpeechToTextRetrieveTranscriptionParams {
   /**
    * Silence duration (in milliseconds) that triggers end-of-speech detection. When
    * set, the engine uses this value to determine when a speaker has stopped talking.
-   * Supported by `xAI`, `Deepgram`, `Google`, `Speechmatics`, and `Soniox`. `Soniox`
-   * accepts values between 500 and 3000. Other engines may not support this
-   * parameter.
+   * Supported by `xAI`, `Deepgram`, `Google`, `Speechmatics`
+   * (`speechmatics/standard` only; `speechmatics/linden-1` uses fixed service-side
+   * voice activity detection and ignores it), and `Soniox`. `Soniox` accepts values
+   * between 500 and 3000. Other engines may not support this parameter.
    */
   endpointing?: number;
 
@@ -289,7 +290,12 @@ export interface SpeechToTextRetrieveTranscriptionParams {
   /**
    * The language spoken in the audio stream. For `cohere/ar-stt`, this must be `ar`
    * or `en` — unlike other engines, Cohere does not auto-detect the language, and
-   * rejects unsupported values including `auto`; omitting it defaults to `ar`.
+   * rejects unsupported values including `auto`; omitting it defaults to `ar`. For
+   * `speechmatics/linden-1`, omitting it defaults to `en`; `auto`, `auto_beta`,
+   * `multi`, or a language outside its supported list is rejected when the
+   * connection is established. `speechmatics/linden-1` also accepts `en-US`,
+   * `en-GB`, `en-AU`, `cmn-Hans`, and `cmn-Hant`, which select the spelling or
+   * script variant (`en` alone uses the default spelling).
    */
   language?: string;
 
@@ -312,6 +318,7 @@ export interface SpeechToTextRetrieveTranscriptionParams {
     | 'openai/whisper-large-v3-turbo'
     | 'xai/grok-stt'
     | 'speechmatics/standard'
+    | 'speechmatics/linden-1'
     | 'soniox/stt-rt-v4'
     | 'nvidia/parakeet-v3'
     | 'omi-health/omi-med-stt-v1'
@@ -329,6 +336,7 @@ export interface SpeechToTextRetrieveTranscriptionParams {
    * Audio sample rate in Hz. Required when `input_format` is a raw encoding
    * (`linear16`, `linear32`) — those formats carry no header metadata. Ignored for
    * container formats (`mp3`, `wav`), which self-describe their rate.
+   * `speechmatics/linden-1` accepts only `16000`.
    */
   sample_rate?: number;
 }

package/src/resources/telephony-credentials.ts

@@ -102,10 +102,21 @@ export class TelephonyCredentials extends APIResource {
    *   await client.telephonyCredentials.createToken('id');
    * ```
    */
-  createToken(id: string, options?: RequestOptions): APIPromise<string> {
+  createToken(
+    id: string,
+    params: TelephonyCredentialCreateTokenParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<string> {
+    const { 'Idempotency-Key': idempotencyKey } = params ?? {};
     return this._client.post(path`/telephony_credentials/${id}/token`, {
       ...options,
-      headers: buildHeaders([{ Accept: 'text/plain' }, options?.headers]),
+      headers: buildHeaders([
+        {
+          Accept: 'text/plain',
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+        },
+        options?.headers,
+      ]),
     });
   }
 }
@@ -263,6 +274,16 @@ export interface TelephonyCredentialUpdateParams {
   tag?: string;
 }
 
+export interface TelephonyCredentialCreateTokenParams {
+  /**
+   * Unique key for safely retrying the same logical request. Generate a UUID v4 for
+   * each operation and reuse it only when retrying that operation with the same
+   * request body. Valid characters: A-Z, a-z, 0-9, -, and \_. Length: 1-255
+   * characters. Do not include sensitive data in the key.
+   */
+  'Idempotency-Key'?: string;
+}
+
 export declare namespace TelephonyCredentials {
   export {
     type TelephonyCredential as TelephonyCredential,
@@ -275,5 +296,6 @@ export declare namespace TelephonyCredentials {
     type TelephonyCredentialListParams as TelephonyCredentialListParams,
     type TelephonyCredentialCreateParams as TelephonyCredentialCreateParams,
     type TelephonyCredentialUpdateParams as TelephonyCredentialUpdateParams,
+    type TelephonyCredentialCreateTokenParams as TelephonyCredentialCreateTokenParams,
   };
 }

package/src/resources/texml/accounts/accounts.ts

@@ -67,7 +67,7 @@ export class Accounts extends APIResource {
    * ```ts
    * const texmlGetCallRecordingsResponseBody =
    *   await client.texml.accounts.retrieveRecordingsJson(
-   *     'account_sid',
+   *     'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
    *   );
    * ```
    */
@@ -86,7 +86,7 @@ export class Accounts extends APIResource {
    * ```ts
    * const response =
    *   await client.texml.accounts.retrieveTranscriptionsJson(
-   *     'account_sid',
+   *     'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
    *   );
    * ```
    */

package/src/resources/texml/accounts/calls/calls.ts

@@ -39,7 +39,7 @@ export class Calls extends APIResource {
    * ```ts
    * const response =
    *   await client.texml.accounts.calls.retrieveCalls(
-   *     'account_sid',
+   *     'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
    *   );
    * ```
    */
@@ -63,12 +63,12 @@ export class Calls extends APIResource {
 
   /**
    * Initiate an outbound TeXML call. Telnyx will request TeXML from the XML Request
-   * URL configured for the connection in the Mission Control Portal.
+   * URL configured for the TeXML Application in the Mission Control Portal.
    *
    * @example
    * ```ts
    * const response = await client.texml.accounts.calls.calls(
-   *   'account_sid',
+   *   'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
    *   { body: { Url: 'https://www.example.com/texml.xml' } },
    * );
    * ```
@@ -90,7 +90,7 @@ export class Calls extends APIResource {
    * ```ts
    * const callResource =
    *   await client.texml.accounts.calls.retrieve('call_sid', {
-   *     account_sid: 'account_sid',
+   *     account_sid: 'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
    *   });
    * ```
    */
@@ -107,7 +107,7 @@ export class Calls extends APIResource {
    * ```ts
    * const callResource =
    *   await client.texml.accounts.calls.update('call_sid', {
-   *     account_sid: 'account_sid',
+   *     account_sid: 'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
    *   });
    * ```
    */
@@ -128,7 +128,7 @@ export class Calls extends APIResource {
    * ```ts
    * const response =
    *   await client.texml.accounts.calls.siprecJson('call_sid', {
-   *     account_sid: 'account_sid',
+   *     account_sid: 'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
    *   });
    * ```
    */
@@ -153,7 +153,7 @@ export class Calls extends APIResource {
    * const response =
    *   await client.texml.accounts.calls.streamsJson(
    *     'call_sid',
-   *     { account_sid: 'account_sid' },
+   *     { account_sid: 'f5586561-8ff0-4291-a51b-c7dfe4139ff9' },
    *   );
    * ```
    */
@@ -512,7 +512,12 @@ export namespace CallCallsParams {
     Url: string;
 
     /**
-     * The ID of the TeXML Application.
+     * The ID of the TeXML Application that will handle the call, for example
+     * `1293384261075731499`. The `ApplicationSid` name is kept for Twilio API
+     * compatibility, but the value is the numeric ID of one of your TeXML Applications
+     * (see the TeXML Applications API or the Mission Control Portal), not a Twilio
+     * `AP...` SID. If `Url` and `Texml` are omitted, Telnyx fetches instructions from
+     * the XML Request URL configured on this application.
      */
     ApplicationSid?: string;
 
@@ -842,7 +847,12 @@ export namespace CallCallsParams {
     Texml: string;
 
     /**
-     * The ID of the TeXML Application.
+     * The ID of the TeXML Application that will handle the call, for example
+     * `1293384261075731499`. The `ApplicationSid` name is kept for Twilio API
+     * compatibility, but the value is the numeric ID of one of your TeXML Applications
+     * (see the TeXML Applications API or the Mission Control Portal), not a Twilio
+     * `AP...` SID. If `Url` and `Texml` are omitted, Telnyx fetches instructions from
+     * the XML Request URL configured on this application.
      */
     ApplicationSid?: string;
 
@@ -1166,7 +1176,12 @@ export namespace CallCallsParams {
 
   export interface ApplicationDefault {
     /**
-     * The ID of the TeXML Application.
+     * The ID of the TeXML Application that will handle the call, for example
+     * `1293384261075731499`. The `ApplicationSid` name is kept for Twilio API
+     * compatibility, but the value is the numeric ID of one of your TeXML Applications
+     * (see the TeXML Applications API or the Mission Control Portal), not a Twilio
+     * `AP...` SID. If `Url` and `Texml` are omitted, Telnyx fetches instructions from
+     * the XML Request URL configured on this application.
      */
     ApplicationSid?: string;
 
@@ -1493,14 +1508,24 @@ export namespace CallCallsParams {
 
 export interface CallRetrieveParams {
   /**
-   * The id of the account the resource belongs to.
+   * The UUID of the Telnyx account that owns the resource, for example
+   * `f5586561-8ff0-4291-a51b-c7dfe4139ff9`. The `account_sid` path segment is kept
+   * for Twilio API compatibility, but the value is a Telnyx account UUID, not a
+   * Twilio `AC...` SID. It must match the account that owns the API key used to
+   * authenticate the request, otherwise the endpoint returns `404`. The same value
+   * is sent as `AccountSid` in TeXML webhooks.
    */
   account_sid: string;
 }
 
 export interface CallUpdateParams {
   /**
-   * Path param: The id of the account the resource belongs to.
+   * Path param: The UUID of the Telnyx account that owns the resource, for example
+   * `f5586561-8ff0-4291-a51b-c7dfe4139ff9`. The `account_sid` path segment is kept
+   * for Twilio API compatibility, but the value is a Telnyx account UUID, not a
+   * Twilio `AC...` SID. It must match the account that owns the API key used to
+   * authenticate the request, otherwise the endpoint returns `404`. The same value
+   * is sent as `AccountSid` in TeXML webhooks.
    */
   account_sid: string;
 
@@ -1551,7 +1576,12 @@ export interface CallUpdateParams {
 
 export interface CallSiprecJsonParams {
   /**
-   * Path param: The id of the account the resource belongs to.
+   * Path param: The UUID of the Telnyx account that owns the resource, for example
+   * `f5586561-8ff0-4291-a51b-c7dfe4139ff9`. The `account_sid` path segment is kept
+   * for Twilio API compatibility, but the value is a Telnyx account UUID, not a
+   * Twilio `AC...` SID. It must match the account that owns the API key used to
+   * authenticate the request, otherwise the endpoint returns `404`. The same value
+   * is sent as `AccountSid` in TeXML webhooks.
    */
   account_sid: string;
 
@@ -1611,7 +1641,12 @@ export interface CallSiprecJsonParams {
 
 export interface CallStreamsJsonParams {
   /**
-   * Path param: The id of the account the resource belongs to.
+   * Path param: The UUID of the Telnyx account that owns the resource, for example
+   * `f5586561-8ff0-4291-a51b-c7dfe4139ff9`. The `account_sid` path segment is kept
+   * for Twilio API compatibility, but the value is a Telnyx account UUID, not a
+   * Twilio `AC...` SID. It must match the account that owns the API key used to
+   * authenticate the request, otherwise the endpoint returns `404`. The same value
+   * is sent as `AccountSid` in TeXML webhooks.
    */
   account_sid: string;
 

package/src/resources/texml/accounts/calls/recordings-json.ts

@@ -19,7 +19,7 @@ export class RecordingsJson extends APIResource {
    * const texmlGetCallRecordingsResponseBody =
    *   await client.texml.accounts.calls.recordingsJson.retrieveRecordingsJson(
    *     'call_sid',
-   *     { account_sid: 'account_sid' },
+   *     { account_sid: 'f5586561-8ff0-4291-a51b-c7dfe4139ff9' },
    *   );
    * ```
    */
@@ -40,7 +40,7 @@ export class RecordingsJson extends APIResource {
    * const texmlCreateCallRecordingResponseBody =
    *   await client.texml.accounts.calls.recordingsJson.recordingsJson(
    *     'call_sid',
-   *     { account_sid: 'account_sid' },
+   *     { account_sid: 'f5586561-8ff0-4291-a51b-c7dfe4139ff9' },
    *   );
    * ```
    */
@@ -171,14 +171,24 @@ export type TwimlRecordingChannels = 1 | 2;
 
 export interface RecordingsJsonRetrieveRecordingsJsonParams {
   /**
-   * The id of the account the resource belongs to.
+   * The UUID of the Telnyx account that owns the resource, for example
+   * `f5586561-8ff0-4291-a51b-c7dfe4139ff9`. The `account_sid` path segment is kept
+   * for Twilio API compatibility, but the value is a Telnyx account UUID, not a
+   * Twilio `AC...` SID. It must match the account that owns the API key used to
+   * authenticate the request, otherwise the endpoint returns `404`. The same value
+   * is sent as `AccountSid` in TeXML webhooks.
    */
   account_sid: string;
 }
 
 export interface RecordingsJsonRecordingsJsonParams {
   /**
-   * Path param: The id of the account the resource belongs to.
+   * Path param: The UUID of the Telnyx account that owns the resource, for example
+   * `f5586561-8ff0-4291-a51b-c7dfe4139ff9`. The `account_sid` path segment is kept
+   * for Twilio API compatibility, but the value is a Telnyx account UUID, not a
+   * Twilio `AC...` SID. It must match the account that owns the API key used to
+   * authenticate the request, otherwise the endpoint returns `404`. The same value
+   * is sent as `AccountSid` in TeXML webhooks.
    */
   account_sid: string;
 

package/src/resources/texml/accounts/calls/recordings.ts

@@ -19,7 +19,10 @@ export class Recordings extends APIResource {
    * const texmlCreateCallRecordingResponseBody =
    *   await client.texml.accounts.calls.recordings.recordingSidJson(
    *     '6a09cdc3-8948-47f0-aa62-74ac943d6c58',
-   *     { account_sid: 'account_sid', call_sid: 'call_sid' },
+   *     {
+   *       account_sid: 'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
+   *       call_sid: 'call_sid',
+   *     },
    *   );
    * ```
    */
@@ -42,7 +45,12 @@ export class Recordings extends APIResource {
 
 export interface RecordingRecordingSidJsonParams {
   /**
-   * Path param: The id of the account the resource belongs to.
+   * Path param: The UUID of the Telnyx account that owns the resource, for example
+   * `f5586561-8ff0-4291-a51b-c7dfe4139ff9`. The `account_sid` path segment is kept
+   * for Twilio API compatibility, but the value is a Telnyx account UUID, not a
+   * Twilio `AC...` SID. It must match the account that owns the API key used to
+   * authenticate the request, otherwise the endpoint returns `404`. The same value
+   * is sent as `AccountSid` in TeXML webhooks.
    */
   account_sid: string;
 

package/src/resources/texml/accounts/calls/siprec.ts

@@ -18,7 +18,10 @@ export class Siprec extends APIResource {
    * const response =
    *   await client.texml.accounts.calls.siprec.siprecSidJson(
    *     'siprec_sid',
-   *     { account_sid: 'account_sid', call_sid: 'call_sid' },
+   *     {
+   *       account_sid: 'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
+   *       call_sid: 'call_sid',
+   *     },
    *   );
    * ```
    */
@@ -78,7 +81,12 @@ export interface SiprecSiprecSidJsonResponse {
 
 export interface SiprecSiprecSidJsonParams {
   /**
-   * Path param: The id of the account the resource belongs to.
+   * Path param: The UUID of the Telnyx account that owns the resource, for example
+   * `f5586561-8ff0-4291-a51b-c7dfe4139ff9`. The `account_sid` path segment is kept
+   * for Twilio API compatibility, but the value is a Telnyx account UUID, not a
+   * Twilio `AC...` SID. It must match the account that owns the API key used to
+   * authenticate the request, otherwise the endpoint returns `404`. The same value
+   * is sent as `AccountSid` in TeXML webhooks.
    */
   account_sid: string;
 

package/src/resources/texml/accounts/calls/streams.ts

@@ -18,7 +18,10 @@ export class Streams extends APIResource {
    * const response =
    *   await client.texml.accounts.calls.streams.streamingSidJson(
    *     '6a09cdc3-8948-47f0-aa62-74ac943d6c58',
-   *     { account_sid: 'account_sid', call_sid: 'call_sid' },
+   *     {
+   *       account_sid: 'f5586561-8ff0-4291-a51b-c7dfe4139ff9',
+   *       call_sid: 'call_sid',
+   *     },
    *   );
    * ```
    */
@@ -64,7 +67,12 @@ export interface StreamStreamingSidJsonResponse {
 
 export interface StreamStreamingSidJsonParams {
   /**
-   * Path param: The id of the account the resource belongs to.
+   * Path param: The UUID of the Telnyx account that owns the resource, for example
+   * `f5586561-8ff0-4291-a51b-c7dfe4139ff9`. The `account_sid` path segment is kept
+   * for Twilio API compatibility, but the value is a Telnyx account UUID, not a
+   * Twilio `AC...` SID. It must match the account that owns the API key used to
+   * authenticate the request, otherwise the endpoint returns `404`. The same value
+   * is sent as `AccountSid` in TeXML webhooks.
    */
   account_sid: string;