release: 4.131.0 (#289)

* ci: pin GitHub Actions to commit SHAs

Pin all GitHub Actions referenced in generated workflows (both
first-party `actions/*` and third-party) to immutable commit SHAs.
Updating pinned actions is now a deliberate codegen-side bump rather
than implicit on every workflow run.

* feat: Document AI call status callback overrides

* release: 4.131.0

---------

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>

Author: stainless-app[bot]

.github/workflows/ci.yml

@@ -21,10 +21,10 @@ jobs:
     runs-on: ${{ github.repository == 'stainless-sdks/telnyx-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
         with:
           version: '0.10.2'
 
@@ -43,10 +43,10 @@ jobs:
       id-token: write
     runs-on: ${{ github.repository == 'stainless-sdks/telnyx-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
         with:
           version: '0.10.2'
 
@@ -61,7 +61,7 @@ jobs:
           github.repository == 'stainless-sdks/telnyx-python' &&
           !startsWith(github.ref, 'refs/heads/stl/')
         id: github-oidc
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: core.setOutput('github_token', await core.getIDToken());
 
@@ -81,10 +81,10 @@ jobs:
     runs-on: ${{ github.repository == 'stainless-sdks/telnyx-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
         with:
           version: '0.10.2'
 

.github/workflows/publish-pypi.yml

@@ -17,10 +17,10 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
         with:
           version: '0.9.13'
 

.github/workflows/release-doctor.yml

@@ -12,7 +12,7 @@ jobs:
     if: github.repository == 'team-telnyx/telnyx-python' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Check release environment
         run: |

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.130.0"
+  ".": "4.131.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 1039
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/telnyx/telnyx-d29d8b4b1cfd89d8feeaab4d5e950f49bb77c55ebb86c76ae1d797b974dc64f7.yml
-openapi_spec_hash: ccf682c997bdd7754fcfa8cf7bd924bc
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/telnyx/telnyx-ffde1e24535b84cba3dac4fdf2ef6df0fe07639f3429f606c5256c870fe5e062.yml
+openapi_spec_hash: 9d4326316d01d0bd0b1b4fcaa849b80c
 config_hash: bc071de39b424ea1ecf205d551ac87cc

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.131.0 (2026-05-13)
+
+Full Changelog: [v4.130.0...v4.131.0](https://github.com/team-telnyx/telnyx-python/compare/v4.130.0...v4.131.0)
+
+### Features
+
+* Document AI call status callback overrides ([87723f8](https://github.com/team-telnyx/telnyx-python/commit/87723f8a9160be89eaf88a209c621edb3fa27e0c))
+
 ## 4.130.0 (2026-05-11)
 
 Full Changelog: [v4.129.0...v4.130.0](https://github.com/team-telnyx/telnyx-python/compare/v4.129.0...v4.130.0)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "telnyx"
-version = "4.130.0"
+version = "4.131.0"
 description = "The official Python library for the telnyx API"
 dynamic = ["readme"]
 license = "MIT"

src/telnyx/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "telnyx"
-__version__ = "4.130.0"  # x-release-please-version
+__version__ = "4.131.0"  # x-release-please-version

src/telnyx/resources/texml/texml.py

@@ -117,6 +117,17 @@ def initiate_ai_call(
         client state, and calls the dial API. The Twiml, Texml, and Url parameters are
         not allowed and will result in a 422 error.
 
+        **Expected callback events:**
+
+        Status callbacks: `initiated`, `ringing`, `answered`, one terminal status
+        (`completed`, `no-answer`, `busy`, `canceled`, or `failed`), then `analyzed`
+        after post-call processing completes.
+
+        Conversation callbacks: `conversation_created` and `conversation_ended`.
+
+        Recording, AMD, transcription, and deepfake detection callbacks are only sent
+        when those features are enabled.
+
         Args:
           ai_assistant_id: The ID of the AI assistant to use for the call.
 
@@ -142,11 +153,13 @@ def initiate_ai_call(
               containing only letters, numbers, spaces, and `-_~!.+` special characters. If
               omitted, the display name will be the same as the number in the `From` field.
 
-          conversation_callback: URL destination for Telnyx to send conversation callback events to.
+          conversation_callback: URL destination for Telnyx to send AI conversation callback events for this
+              call. Events include `conversation_created` and `conversation_ended`.
 
-          conversation_callback_method: HTTP request type used for `ConversationCallback`.
+          conversation_callback_method: HTTP request type used for `ConversationCallback` and `ConversationCallbacks`.
 
-          conversation_callbacks: An array of URL destinations for conversation callback events.
+          conversation_callbacks: Array of URL destinations for AI conversation callback events for this call.
+              Events include `conversation_created` and `conversation_ended`.
 
           custom_headers: Custom HTTP headers to be sent with the call. Each header should be an object
               with 'name' and 'value' properties.
@@ -196,16 +209,23 @@ def initiate_ai_call(
 
           sip_region: Defines the SIP region to be used for the call.
 
-          status_callback: URL destination for Telnyx to send status callback events to for the call.
+          status_callback: URL destination for Telnyx to send status callback events for this AI call. When
+              provided, this per-call value overrides the status callback URL configured on
+              the TeXML application/connection.
 
-          status_callback_event: The call events for which Telnyx should send a webhook. Multiple events can be
-              defined when separated by a space. Valid values: initiated, ringing, answered,
-              completed.
+          status_callback_event: The status callback events for which Telnyx should send a webhook for this AI
+              call. Multiple events can be defined when separated by a space. Valid values:
+              initiated, ringing, answered, completed, no-answer, busy, canceled, failed,
+              analyzed. When provided, this per-call value overrides the status callback
+              events configured on the TeXML application/connection.
 
-          status_callback_method: HTTP request type used for `StatusCallback`.
+          status_callback_method: HTTP request type used for `StatusCallback` and `StatusCallbacks` for this AI
+              call. When provided, this per-call value overrides the status callback method
+              configured on the TeXML application/connection.
 
-          status_callbacks: An array of URL destinations for Telnyx to send status callback events to for
-              the call.
+          status_callbacks: Array of URL destinations for Telnyx to send status callback events for this AI
+              call. When provided, these per-call values override the status callback URL
+              configured on the TeXML application/connection.
 
           time_limit: The maximum duration of the call in seconds. The minimum value is 30 and the
               maximum value is 14400 (4 hours). Default is 14400 seconds.
@@ -412,6 +432,17 @@ async def initiate_ai_call(
         client state, and calls the dial API. The Twiml, Texml, and Url parameters are
         not allowed and will result in a 422 error.
 
+        **Expected callback events:**
+
+        Status callbacks: `initiated`, `ringing`, `answered`, one terminal status
+        (`completed`, `no-answer`, `busy`, `canceled`, or `failed`), then `analyzed`
+        after post-call processing completes.
+
+        Conversation callbacks: `conversation_created` and `conversation_ended`.
+
+        Recording, AMD, transcription, and deepfake detection callbacks are only sent
+        when those features are enabled.
+
         Args:
           ai_assistant_id: The ID of the AI assistant to use for the call.
 
@@ -437,11 +468,13 @@ async def initiate_ai_call(
               containing only letters, numbers, spaces, and `-_~!.+` special characters. If
               omitted, the display name will be the same as the number in the `From` field.
 
-          conversation_callback: URL destination for Telnyx to send conversation callback events to.
+          conversation_callback: URL destination for Telnyx to send AI conversation callback events for this
+              call. Events include `conversation_created` and `conversation_ended`.
 
-          conversation_callback_method: HTTP request type used for `ConversationCallback`.
+          conversation_callback_method: HTTP request type used for `ConversationCallback` and `ConversationCallbacks`.
 
-          conversation_callbacks: An array of URL destinations for conversation callback events.
+          conversation_callbacks: Array of URL destinations for AI conversation callback events for this call.
+              Events include `conversation_created` and `conversation_ended`.
 
           custom_headers: Custom HTTP headers to be sent with the call. Each header should be an object
               with 'name' and 'value' properties.
@@ -491,16 +524,23 @@ async def initiate_ai_call(
 
           sip_region: Defines the SIP region to be used for the call.
 
-          status_callback: URL destination for Telnyx to send status callback events to for the call.
+          status_callback: URL destination for Telnyx to send status callback events for this AI call. When
+              provided, this per-call value overrides the status callback URL configured on
+              the TeXML application/connection.
 
-          status_callback_event: The call events for which Telnyx should send a webhook. Multiple events can be
-              defined when separated by a space. Valid values: initiated, ringing, answered,
-              completed.
+          status_callback_event: The status callback events for which Telnyx should send a webhook for this AI
+              call. Multiple events can be defined when separated by a space. Valid values:
+              initiated, ringing, answered, completed, no-answer, busy, canceled, failed,
+              analyzed. When provided, this per-call value overrides the status callback
+              events configured on the TeXML application/connection.
 
-          status_callback_method: HTTP request type used for `StatusCallback`.
+          status_callback_method: HTTP request type used for `StatusCallback` and `StatusCallbacks` for this AI
+              call. When provided, this per-call value overrides the status callback method
+              configured on the TeXML application/connection.
 
-          status_callbacks: An array of URL destinations for Telnyx to send status callback events to for
-              the call.
+          status_callbacks: Array of URL destinations for Telnyx to send status callback events for this AI
+              call. When provided, these per-call values override the status callback URL
+              configured on the TeXML application/connection.
 
           time_limit: The maximum duration of the call in seconds. The minimum value is 30 and the
               maximum value is 14400 (4 hours). Default is 14400 seconds.

src/telnyx/types/texml_initiate_ai_call_params.py

@@ -56,13 +56,20 @@ class TexmlInitiateAICallParams(TypedDict, total=False):
     """
 
     conversation_callback: Annotated[str, PropertyInfo(alias="ConversationCallback")]
-    """URL destination for Telnyx to send conversation callback events to."""
+    """URL destination for Telnyx to send AI conversation callback events for this
+    call.
+
+    Events include `conversation_created` and `conversation_ended`.
+    """
 
     conversation_callback_method: Annotated[Literal["GET", "POST"], PropertyInfo(alias="ConversationCallbackMethod")]
-    """HTTP request type used for `ConversationCallback`."""
+    """HTTP request type used for `ConversationCallback` and `ConversationCallbacks`."""
 
     conversation_callbacks: Annotated[SequenceNotStr[str], PropertyInfo(alias="ConversationCallbacks")]
-    """An array of URL destinations for conversation callback events."""
+    """Array of URL destinations for AI conversation callback events for this call.
+
+    Events include `conversation_created` and `conversation_ended`.
+    """
 
     custom_headers: Annotated[Iterable[CustomHeader], PropertyInfo(alias="CustomHeaders")]
     """Custom HTTP headers to be sent with the call.
@@ -152,22 +159,33 @@ class TexmlInitiateAICallParams(TypedDict, total=False):
     """Defines the SIP region to be used for the call."""
 
     status_callback: Annotated[str, PropertyInfo(alias="StatusCallback")]
-    """URL destination for Telnyx to send status callback events to for the call."""
+    """URL destination for Telnyx to send status callback events for this AI call.
 
-    status_callback_event: Annotated[str, PropertyInfo(alias="StatusCallbackEvent")]
-    """The call events for which Telnyx should send a webhook.
+    When provided, this per-call value overrides the status callback URL configured
+    on the TeXML application/connection.
+    """
 
-    Multiple events can be defined when separated by a space. Valid values:
-    initiated, ringing, answered, completed.
+    status_callback_event: Annotated[str, PropertyInfo(alias="StatusCallbackEvent")]
+    """
+    The status callback events for which Telnyx should send a webhook for this AI
+    call. Multiple events can be defined when separated by a space. Valid values:
+    initiated, ringing, answered, completed, no-answer, busy, canceled, failed,
+    analyzed. When provided, this per-call value overrides the status callback
+    events configured on the TeXML application/connection.
     """
 
     status_callback_method: Annotated[Literal["GET", "POST"], PropertyInfo(alias="StatusCallbackMethod")]
-    """HTTP request type used for `StatusCallback`."""
+    """
+    HTTP request type used for `StatusCallback` and `StatusCallbacks` for this AI
+    call. When provided, this per-call value overrides the status callback method
+    configured on the TeXML application/connection.
+    """
 
     status_callbacks: Annotated[SequenceNotStr[str], PropertyInfo(alias="StatusCallbacks")]
     """
-    An array of URL destinations for Telnyx to send status callback events to for
-    the call.
+    Array of URL destinations for Telnyx to send status callback events for this AI
+    call. When provided, these per-call values override the status callback URL
+    configured on the TeXML application/connection.
     """
 
     time_limit: Annotated[int, PropertyInfo(alias="TimeLimit")]