From 8a6d3020ffaf14ee27a8b37fb32f182958108213 Mon Sep 17 00:00:00 2001
From: Stefan Jacobi <stefan.jacobi@deepl.com>
Date: Fri, 14 Nov 2025 09:49:25 +0100
Subject: [PATCH] feat(voice): [ACL-2127] Add a sequence diagram to illustrate
 the Voice API flow

---
 api-reference/voice.mdx | 43 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/api-reference/voice.mdx b/api-reference/voice.mdx
index 8810fd1a..bf5ca017 100644
--- a/api-reference/voice.mdx
+++ b/api-reference/voice.mdx
@@ -113,6 +113,49 @@ Use the received URL to establish a WebSocket connection for:
 
 See the [WebSocket Streaming](/api-reference/voice/websocket-streaming) documentation for details.
 
+### Message Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Voice API
+
+    Note over Client,Voice API: Step 1: Request Session (POST)
+
+    Client->>Voice API: Configuration options
+    Voice API->>Client: Streaming URL
+
+    Note over Client,Voice API: Step 2: Start Streaming (WebSocket)
+
+    Client->>Voice API: Establish WebSocket connection<br>using the streaming URL
+
+    Note over Client,Voice API: WebSocket
+
+    par 
+      loop Send audio data
+        Client->>Voice API: SourceMediaChunk
+      end
+    and 
+      loop Receive updates
+        Voice API-->>Client: SourceTranscriptUpdate
+        Voice API-->>Client: TargetTranscriptUpdate
+      end
+    end
+
+    Client->>Voice API: EndOfSourceAudio
+
+    loop Final updates
+        Voice API-->>Client: SourceTranscriptUpdate
+        Voice API-->>Client: TargetTranscriptUpdate
+    end
+
+    Voice API-->>Client: EndOfSourceTranscript
+
+    Voice API-->>Client: EndOfTargetTranscript<br>(once per target language)
+
+    Note over Client,Voice API: Connection Closed
+```
+
 ## Limitations and Constraints
 
 * Maximum 5 target languages per stream