feat: Document AI call status callback overrides

Author: stainless-app[bot]

.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

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")]