From 49c6e26271836482272db7efb56d68083605bec6 Mon Sep 17 00:00:00 2001
From: Naomi Carrigan <commits@nhcarrigan.com>
Date: Fri, 10 Oct 2025 11:41:17 -0700
Subject: [PATCH 1/2] feat: mention keep alive in migration guide

---
 docs/Migrating-v3-to-v5.md | 48 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 2 deletions(-)

diff --git a/docs/Migrating-v3-to-v5.md b/docs/Migrating-v3-to-v5.md
index a3cf2e9a..a13536d9 100644
--- a/docs/Migrating-v3-to-v5.md
+++ b/docs/Migrating-v3-to-v5.md
@@ -16,6 +16,7 @@ This guide helps you migrate from Deepgram Python SDK v3+ (versions 3.0.0 to 4.8
   - [Models V1](#models-v1)
   - [Manage V1](#manage-v1)
   - [Self-Hosted V1](#self-hosted-v1)
+- [Keep Alive Functionality](#websocket-keep-alive-functionality)
 - [Breaking Changes Summary](#breaking-changes-summary)
 
 ## Installation
@@ -857,6 +858,47 @@ response = client.self_hosted.v1.distribution_credentials.delete(
 )
 ```
 
+## WebSocket Keep Alive Functionality
+
+**v3+ (3.0.0 - 4.8.1)**
+
+```python
+# Keep alive was passed as a config option
+config = DeepgramClientOptions(
+    options={"keepalive": "true"}
+)
+deepgram = DeepgramClient(API_KEY, config)
+```
+
+**v5.0.0**
+
+```python
+# Keep alive is now manually managed via control messages.
+from deepgram.extensions.types.sockets import ListenV1ControlMessage, AgentV1ControlMessage
+
+# For Listen V1 connections
+with client.listen.v1.connect(model="nova-3") as connection:
+    # Send keep alive message
+    connection.send_control(ListenV1ControlMessage(type="KeepAlive"))
+
+# For Agent V1 connections  
+with client.agent.v1.connect() as agent:
+    # Send keep alive message
+    agent.send_control(AgentV1ControlMessage(type="KeepAlive"))
+```
+
+**Key Changes:**
+
+1. **WebSocket Library Upgrade**: The SDK upgraded to `websockets>=12.0`, which introduced some internal changes to connection handling.
+
+2. **Parameter Name Changes**: 
+   - **Sync connections**: Continue to use `additional_headers` parameter
+   - **Async connections**: Now use `extra_headers` parameter (changed from `additional_headers`)
+
+3. **Keep Alive Control Messages**: The keep alive functionality itself remains unchanged - you still send `KeepAlive` control messages using the `send_control()` method.
+
+4. **Connection Management**: The underlying WebSocket connection management has been updated to use the newer websockets library API, but the public interface for keep alive remains the same.
+
 ## Breaking Changes Summary
 
 ### Major Changes
@@ -864,8 +906,9 @@ response = client.self_hosted.v1.distribution_credentials.delete(
 1. **Authentication**: New access token support with environment variable `DEEPGRAM_TOKEN`
 2. **API structure**: Flattened method names and cleaner parameter passing
 3. **WebSocket API**: Complete redesign with context managers and typed message objects
-4. **Type safety**: Enhanced type annotations and response objects
-5. **Error handling**: Improved error types and handling
+4. **WebSocket Keep Alive**: Managed via control messages, no longer an automatic thing via config
+5. **Type safety**: Enhanced type annotations and response objects
+6. **Error handling**: Improved error types and handling
 
 ### Removed Features
 
@@ -890,5 +933,6 @@ response = client.self_hosted.v1.distribution_credentials.delete(
 - [ ] Replace API key configuration with new authentication methods
 - [ ] Update all API method calls to new structure
 - [ ] Migrate WebSocket connections to new context manager pattern
+- [ ] Update WebSocket keep alive implementation
 - [ ] Update error handling for new exception types
 - [ ] Test all functionality with new API structure

From e01d5a290c043a33ecdecc1cb8d470fe7cd34c4e Mon Sep 17 00:00:00 2001
From: Luke Oliff <luke@lukeoliff.com>
Date: Fri, 10 Oct 2025 19:44:10 +0100
Subject: [PATCH 2/2] Update Migrating-v3-to-v5.md

---
 docs/Migrating-v3-to-v5.md | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/docs/Migrating-v3-to-v5.md b/docs/Migrating-v3-to-v5.md
index a13536d9..dff3033c 100644
--- a/docs/Migrating-v3-to-v5.md
+++ b/docs/Migrating-v3-to-v5.md
@@ -887,18 +887,6 @@ with client.agent.v1.connect() as agent:
     agent.send_control(AgentV1ControlMessage(type="KeepAlive"))
 ```
 
-**Key Changes:**
-
-1. **WebSocket Library Upgrade**: The SDK upgraded to `websockets>=12.0`, which introduced some internal changes to connection handling.
-
-2. **Parameter Name Changes**: 
-   - **Sync connections**: Continue to use `additional_headers` parameter
-   - **Async connections**: Now use `extra_headers` parameter (changed from `additional_headers`)
-
-3. **Keep Alive Control Messages**: The keep alive functionality itself remains unchanged - you still send `KeepAlive` control messages using the `send_control()` method.
-
-4. **Connection Management**: The underlying WebSocket connection management has been updated to use the newer websockets library API, but the public interface for keep alive remains the same.
-
 ## Breaking Changes Summary
 
 ### Major Changes