Merge pull request #3029 from pipecat-ai/filipi/heygen_keep_alive

Preventing HeyGenVideoService from disconnecting.

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to **Pipecat** will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Fixed
+
+- Prevented `HeyGenVideoService` from automatically disconnecting after 5 minutes.
+
 ## [0.0.94] - 2025-11-10
 
 ### Deprecated

src/pipecat/services/heygen/client.py

@@ -83,6 +83,7 @@ class HeyGenClient:
             version="v2",
         ),
         callbacks: HeyGenCallbacks,
+        connect_as_user: bool = False,
     ) -> None:
         """Initialize the HeyGen client.
 
@@ -92,6 +93,7 @@ class HeyGenClient:
             params: Transport configuration parameters
             session_request: Configuration for the HeyGen session (default: uses Shawn_Therapist_public avatar)
             callbacks: Callback handlers for HeyGen events
+            connect_as_user: Whether to connect using the user token or not (default: False)
         """
         self._api = HeyGenApi(api_key, session=session)
         self._heyGen_session: Optional[HeyGenSession] = None
@@ -119,6 +121,11 @@ class HeyGenClient:
         self._next_send_time = 0
         self._audio_seconds_sent = 0.0
         self._transport_ready = False
+        # HeyGen enforces a protection mechanism that will automatically disconnect the avatar if a user does not join within 5 minutes,
+        # regardless of whether the Pipecat agent remains present in the room.
+        # To prevent unexpected disconnections in HeyGenVideoService, we ensure that a user connection is established using the user's token.
+        # This keeps the avatar session active and avoids forced logouts due to inactivity from the user side.
+        self._connect_as_user = connect_as_user
 
     async def _initialize(self):
         self._heyGen_session = await self._api.new_session(self._session_request)
@@ -562,9 +569,12 @@ class HeyGenClient:
                     self._callbacks.on_participant_disconnected, participant.identity
                 )
 
-            await self._livekit_room.connect(
-                self._heyGen_session.url, self._heyGen_session.livekit_agent_token
+            access_token = (
+                self._heyGen_session.livekit_agent_token
+                if not self._connect_as_user
+                else self._heyGen_session.access_token
             )
+            await self._livekit_room.connect(self._heyGen_session.url, access_token)
             logger.debug(f"Successfully connected to LiveKit room: {self._livekit_room.name}")
             logger.debug(f"Local participant SID: {self._livekit_room.local_participant.sid}")
             logger.debug(

src/pipecat/services/heygen/video.py

@@ -121,6 +121,7 @@ class HeyGenVideoService(AIService):
                 on_participant_connected=self._on_participant_connected,
                 on_participant_disconnected=self._on_participant_disconnected,
             ),
+            connect_as_user=True,
         )
         await self._client.setup(setup)