[ACL-2250] Voice reconnection documentation

api-reference/openapi.yaml

@@ -2012,6 +2012,46 @@ paths:
           $ref: '#/components/responses/ServiceUnavailable'
       security:
         - auth_header: []
+    get:
+      tags:
+        - VoiceAPI
+      summary: Request Reconnection
+      operationId: requestReconnection
+      parameters:
+        - name: token
+          in: query
+          required: true
+          description: The latest ephemeral token obtained for the stream.
+          schema:
+            type: string
+          example: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K'
+      responses:
+        200:
+          description: Successfully obtained streaming URL and reconnection token.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VoiceStreamingResponse'
+              example:
+                streaming_url: 'wss://api.deepl.com/v3/voice/realtime/connect'
+                token: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K'
+                session_id: '4f911080-cfe2-41d4-8269-0e6ec15a0354'
+        400:
+          $ref: '#/components/responses/BadRequest'
+        401:
+          $ref: '#/components/responses/Unauthorized'
+        403:
+          $ref: '#/components/responses/Forbidden'
+        429:
+          $ref: '#/components/responses/TooManyRequests'
+        456:
+          $ref: '#/components/responses/QuotaExceeded'
+        500:
+          $ref: '#/components/responses/InternalServerError'
+        503:
+          $ref: '#/components/responses/ServiceUnavailable'
+      security:
+        - auth_header: []
 components:
   parameters:
     DocumentID:

api-reference/voice.mdx

@@ -132,7 +132,7 @@ The Voice API uses a two-step flow to initiate streaming.
     ```json
     {
       "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect",
-      "token": <secure access token>,
+      "token": <authentication token>,
     }
     ```
 
@@ -147,7 +147,7 @@ The Voice API uses a two-step flow to initiate streaming.
     See the [Request Stream](/api-reference/voice/request-stream) documentation for details.
   </Step>
   <Step title="Streaming Audio and Text (WebSocket)">
-    Use the received URL to establish a WebSocket connection to `wss://api.deepl.com/v3/voice/realtime/connect?token=<secure access token>`.
+    Use the received URL to establish a WebSocket connection to `wss://api.deepl.com/v3/voice/realtime/connect?token=<authentication token>`.
     This step handles exchanging JSON messages on the WebSocket connection:
     * Sending audio data
     * Receiving transcriptions and translations in real-time
@@ -215,6 +215,36 @@ sequenceDiagram
 `par` means parallel execution and `loop` means looped execution.
 </Accordion>
 
+## Reconnecting
+
+Network connections are inherently unreliable.
+Disconnections are unavoidable and must be planned for.
+In case your stream gets disconnected, request a new authentication token to pick up where you left off.
+Make a GET request `v3/voice/realtime?token=<your last authentication token>`.
+The response will look like this:
+
+```json
+{
+  "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect",
+  "token": <new authentication token>,
+}
+```
+
+Use the received URL and token to establish a new WebSocket connection.
+Should another reconnection become necessary, repeat the procedure.
+
+See the [Reconnect Stream](/api-reference/voice/reconnect-stream) documentation for details.
+
+<Note>
+Always use the latest authentication token to request a new authentication token.
+The use of outdated tokens will invalidate your session for security reasons.
+</Note>
+
+<Note>
+If you still have an active connection, requesting a reconnection token will disconnect you.
+</Note>
+
+
 ## Usage Examples
 
 You can find a reference usage example for python at our
@@ -230,3 +260,4 @@ to interact with the API.
 * Recommended chunk duration: 50-250 milliseconds for low latency
 * Audio stream speed: maximum 2x real-time
 * Timeout: If no data is received for 30 seconds, the session will be terminated
+* Using any given token more than once to establish a WebSocket connection will terminate associated the session immediately for security reasons.

api-reference/voice/reconnect-stream.mdx

@@ -0,0 +1,4 @@
+---
+openapi: get /v3/voice/realtime
+title: "Reconnect Stream"
+---

docs.json

@@ -214,7 +214,8 @@
                 "pages": [
                   "api-reference/voice",
                   "api-reference/voice/request-stream",
-                  "api-reference/voice/websocket-streaming"
+                  "api-reference/voice/websocket-streaming",
+                  "api-reference/voice/reconnect-stream"
                 ]
               }
             ]