Merge branch 'main' into docs-authoring-rules

Author: Devon-White

fern/apis/signalwire-rest/openapi.yaml

@@ -72,7 +72,11 @@ navigation:
       - section: Calling
         skip-slug: true
         contents:
-          - calls
+          - calls:
+              - section: Webhooks
+                slug: webhooks
+                contents:
+                  - subpackage_calls.transcribe_status_callback
           - queues
           - queueMembers
           - recordings

fern/products/apis/apis.yml

@@ -231,6 +231,11 @@ The `code` field above maps to one of the values below. Each entry describes the
 - The resource could not be purchased.
 </ParamField>
 
+<ParamField path="custom_variable_value_too_long" type="Error" toc={true}>
+
+- A `custom_variables` value exceeds the maximum size. Each value must be at most 1024 bytes.
+</ParamField>
+
 <ParamField path="destination_number_not_supported" type="Error" toc={true}>
 
 - The destination phone number is not supported.
@@ -336,6 +341,11 @@ The `code` field above maps to one of the values below. Each entry describes the
 - This account has an insufficient balance.
 </ParamField>
 
+<ParamField path="insufficient_balance_to_receive_message" type="Error" toc={true}>
+
+- The account has an insufficient balance to receive the message.
+</ParamField>
+
 <ParamField path="integration_test_verified_caller_required" type="Error" toc={true}>
 
 - The `to` number must be the verified caller ID for the trial campaign.
@@ -391,6 +401,16 @@ The `code` field above maps to one of the values below. Each entry describes the
 - Invalid content type.
 </ParamField>
 
+<ParamField path="invalid_custom_variable_name" type="Error" toc={true}>
+
+- A `custom_variables` key is invalid. Keys must start with a letter or underscore and contain only letters, numbers, and underscores.
+</ParamField>
+
+<ParamField path="invalid_custom_variable_value" type="Error" toc={true}>
+
+- A `custom_variables` value is invalid. Values must be non-empty strings.
+</ParamField>
+
 <ParamField path="invalid_destination_number" type="Error" toc={true}>
 
 - The destination phone number is invalid.
@@ -636,6 +656,11 @@ The `code` field above maps to one of the values below. Each entry describes the
 - Value must be an array of `{name, value}` objects.
 </ParamField>
 
+<ParamField path="must_be_object" type="Error" toc={true}>
+
+- The `custom_variables` parameter must be an object of string key/value pairs.
+</ParamField>
+
 <ParamField path="must_belong_to_project" type="Error" toc={true}>
 
 - The requested resource must belong to the project being used to authenticate the request.
@@ -871,6 +896,11 @@ The `code` field above maps to one of the values below. Each entry describes the
 - The rate limit has been exceeded.
 </ParamField>
 
+<ParamField path="reserved_custom_variable_name" type="Error" toc={true}>
+
+- A `custom_variables` key uses a reserved prefix. The prefixes `signalwire_`, `sw_`, `rtc_`, and `internal_` are reserved for internal use and cannot be used in your own keys.
+</ParamField>
+
 <ParamField path="reserved_header_name" type="Error" toc={true}>
 
 - The provided header name is reserved and cannot be set by the caller.
@@ -991,6 +1021,11 @@ The `code` field above maps to one of the values below. Each entry describes the
 - The provided token is not associated with a valid video room.
 </ParamField>
 
+<ParamField path="too_many_custom_variables" type="Error" toc={true}>
+
+- The request contains too many custom variables. A maximum of 20 keys is allowed.
+</ParamField>
+
 <ParamField path="too_many_headers" type="Error" toc={true}>
 
 - The number of headers exceeds the maximum allowed.

fern/products/apis/pages/core/error-codes.mdx

@@ -3,7 +3,6 @@ title: "TranscribeAction"
 slug: /reference/python/relay/actions/transcribe-action
 description: Action handle for an active transcription operation.
 max-toc-depth: 3
-hidden: true
 ---
 
 [call-transcribe]: /docs/server-sdks/reference/python/relay/call/transcribe

fern/products/server-sdks/pages/reference/python/relay/actions/transcribe-action/index.mdx

@@ -3,7 +3,6 @@ title: "stop"
 slug: /reference/python/relay/actions/transcribe-action/stop
 description: Stop transcription.
 max-toc-depth: 3
-hidden: true
 ---
 
 Stop transcription.

fern/products/server-sdks/pages/reference/python/relay/actions/transcribe-action/stop.mdx

@@ -3,22 +3,21 @@ title: "transcribe"
 slug: /reference/python/relay/call/transcribe
 description: "Start transcribing call audio."
 max-toc-depth: 3
-hidden: true
 ---
 
 [transcribeaction]: /docs/server-sdks/reference/python/relay/actions
 [live-transcribe]: /docs/server-sdks/reference/python/relay/call/live-transcribe
 [calling-call-transcribe]: /docs/server-sdks/reference/python/relay/call#events
 [call-events]: /docs/server-sdks/reference/python/relay/call#events
 
-Start transcribing call audio. Returns a
+Transcribe the entire call in the background. Returns a
 [`TranscribeAction`][transcribeaction] that you can use
 to stop the transcription or wait for it to complete.
 
 <Info>
-For real-time transcription with immediate text output, see
-[`live_transcribe()`][live-transcribe].
-The `transcribe()` method starts a background transcription that resolves when the operation finishes.
+The `transcribe()` method transcribes the whole call and resolves when it finishes.
+For real-time transcription delivered as the call happens, see
+[`live_transcribe()`][live-transcribe] instead.
 </Info>
 
 <Info>
@@ -36,8 +35,8 @@ This method emits [`calling.call.transcribe`][calling-call-transcribe] events. S
 </ParamField>
 
 <ParamField path="on_completed" type="Optional[Callable[[RelayEvent], Any]]" toc={true}>
-  Callback invoked when transcription completes. The event contains the
-  transcription `url`, `duration`, and `size`.
+  Callback invoked when transcription completes. The event carries the
+  recording's `url`, `duration`, and `size`.
 </ParamField>
 
 ## **Returns**
@@ -66,13 +65,8 @@ async def handle_call(call):
         status_url="https://example.com/transcription-status",
     )
 
-    # Let the call proceed...
+    # Transcription runs in the background until the call ends
     await call.wait_for_ended()
 
-    # The transcription result is available after the call ends
-    if action.result:
-        url = action.result.params.get("url", "")
-        print(f"Transcription available at: {url}")
-
 client.run()
 ```

fern/products/server-sdks/pages/reference/python/relay/call/transcribe.mdx

@@ -1086,6 +1086,10 @@ client.run()
 
 Emitted when a transcribe operation changes state.
 
+<Info>
+Background transcription is implemented as a recording with transcription enabled, so this event reports the underlying recording (its `url`, `recording_id`, `duration`, and `size`).
+</Info>
+
 #### TranscribeEvent
 
 Handlers for this event receive a `TranscribeEvent` with the following properties:
@@ -1097,25 +1101,32 @@ Handlers for this event receive a `TranscribeEvent` with the following propertie
 <ParamField path="state" type="str" default="" toc={true}>
   Transcription state.
 
-  - `"finished"` -- transcription completed successfully
+  - `"transcribing"` -- transcription has started
+  - `"finished"` -- transcription completed; `duration`, `size`, `start_time`, and `end_time` are included
 </ParamField>
 
 <ParamField path="url" type="str" default="" toc={true}>
-  URL of the transcription result.
+  URL where the recording is hosted. Present once available.
 </ParamField>
 
 <ParamField path="recording_id" type="str" default="" toc={true}>
-  Associated recording ID.
+  ID of the recording.
 </ParamField>
 
 <ParamField path="duration" type="float" default="0.0" toc={true}>
-  Duration of the transcribed audio in seconds.
+  Duration of the recording in seconds. Present on the `finished` event.
 </ParamField>
 
 <ParamField path="size" type="int" default="0" toc={true}>
-  Size of the transcription data in bytes.
+  Size of the recording in bytes. Present on the `finished` event.
 </ParamField>
 
+<Info>
+  The raw event payload (`event.params`) also carries `status_url` (when a status URL
+  was set) and, on the `finished` event, `start_time` and `end_time` (Unix epoch seconds).
+  These are not yet exposed as typed attributes on `TranscribeEvent`.
+</Info>
+
 #### Example
 
 ```python

fern/products/server-sdks/pages/reference/python/relay/events.mdx

@@ -11,7 +11,7 @@ Stop an active transcription.
 
 ## **Request**
 
-<Schema type="Calling.CallLiveTranscribeRequest" api="signalwire-rest" exclude={["command"]} />
+<Schema type="Calling.CallTranscribeStopRequest" api="signalwire-rest" exclude={["command"]} />
 
 ## **Response**
 

fern/products/server-sdks/pages/reference/python/rest/calling/transcribe-stop.mdx

@@ -5,12 +5,15 @@ description: Start transcribing speech on an active call via REST.
 max-toc-depth: 3
 ---
 
-Start transcribing speech on an active call. Transcription results are delivered
-via events. Returns a `control_id` for stopping the transcription.
+Start transcribing an active call in the background. The transcription covers the whole
+call and completes when the call ends. For real-time transcription, use live transcription.
+Status updates are delivered to the optional `status_url`. Supply a `control_id` so you
+can stop the transcription later with
+[`transcribe_stop`](/docs/server-sdks/reference/python/rest/calling/transcribe-stop).
 
 ## **Request**
 
-<Schema type="Calling.CallLiveTranscribeRequest" api="signalwire-rest" exclude={["command"]} />
+<Schema type="Calling.CallTranscribeRequest" api="signalwire-rest" exclude={["command"]} />
 
 ## **Response**
 
@@ -27,8 +30,9 @@ client = RestClient(
     host="your-space.signalwire.com",
 )
 
-result = client.calling.transcribe(
+client.calling.transcribe(
     call_id="call-id-xxx",
+    control_id="transcribe-1",
+    status_url="https://example.com/transcribe-status",
 )
-control_id = result.get("control_id")
 ```

fern/products/server-sdks/pages/reference/python/rest/calling/transcribe.mdx

@@ -3,7 +3,6 @@ title: "TranscribeAction"
 slug: /reference/typescript/relay/actions/transcribe-action
 description: Action handle for an active transcription operation.
 max-toc-depth: 3
-hidden: true
 ---
 
 [call-transcribe]: /docs/server-sdks/reference/typescript/relay/call/transcribe