feat(whatsapp): Add recording indicator for TTS audio synthesis

- Implement `send_recording_indicator` method in WhatsApp base provider
- Add recording indicator support for Evolution API provider
- Update WhatsApp bot to show recording indicator during TTS audio synthesis
- Enhance TTS audio response flow with async synthesis and recording indicator
- Improve logging and error handling for recording indicator functionality
Adds a visual cue for users during text-to-speech audio generation, providing a more interactive and responsive messaging experience.

Author: arthurbrenno

agentle/agents/whatsapp/providers/base/whatsapp_provider.py

@@ -112,6 +112,17 @@ async def send_typing_indicator(self, to: str, duration: int = 3) -> None:
         """
         pass
 
+    @abstractmethod
+    async def send_recording_indicator(self, to: str, duration: int = 3) -> None:
+        """
+        Send recording indicator to show the bot is recording audio.
+
+        Args:
+            to: Recipient phone number
+            duration: Duration in seconds to show recording
+        """
+        pass
+
     @abstractmethod
     async def mark_message_as_read(self, message_id: str) -> None:
         """Mark a message as read."""

agentle/agents/whatsapp/providers/evolution/evolution_api_provider.py

@@ -1088,6 +1088,68 @@ async def send_typing_indicator(self, to: str, duration: int = 3) -> None:
                 },
             )
 
+    async def send_recording_indicator(self, to: str, duration: int = 3) -> None:
+        """Send recording indicator via Evolution API."""
+        logger.debug(f"Sending recording indicator to {to} for {duration}s")
+
+        try:
+            # CRITICAL FIX: Check if there's a stored remoteJid for this contact
+            # This is essential for @lid numbers (Brazilian WhatsApp contacts)
+            session = await self.get_session(to)
+            remote_jid = session.context_data.get("remote_jid") if session else None
+
+            if remote_jid:
+                logger.debug(
+                    f"🔑 Using stored remoteJid for recording indicator to {to}: {remote_jid}"
+                )
+                normalized_to = remote_jid
+            else:
+                normalized_to = self._normalize_phone(to)
+
+            payload = {
+                "number": normalized_to,
+                "presence": "recording",
+                "delay": duration * 1000,
+                "options": {
+                    "delay": duration * 1000,
+                    "presence": "recording",
+                    "number": normalized_to,
+                },  # Evolution API expects milliseconds
+            }
+
+            url = self._build_url(
+                f"chat/sendPresence/{self.config.instance_name}",
+                use_message_prefix=False,
+            )
+            await self._make_request_with_resilience(
+                "POST", url, payload, expected_status=201
+            )
+
+            logger.debug(
+                f"Recording indicator sent successfully to {to} for {duration}s",
+                extra={
+                    "to_number": to,
+                    "normalized_to": normalized_to,
+                    "duration_seconds": duration,
+                },
+            )
+
+        except EvolutionAPIError as e:
+            # Recording indicator failures are non-critical
+            logger.warning(
+                f"Failed to send recording indicator to {to}: {e}",
+                extra={"to_number": to, "duration_seconds": duration, "error": str(e)},
+            )
+        except Exception as e:
+            logger.warning(
+                f"Failed to send recording indicator to {to}: {type(e).__name__}: {e}",
+                extra={
+                    "to_number": to,
+                    "duration_seconds": duration,
+                    "error_type": type(e).__name__,
+                },
+            )
+
     async def mark_message_as_read(self, message_id: str) -> None:
         """Mark a message as read via Evolution API."""
         logger.debug(f"Marking message as read: {message_id}")

agentle/agents/whatsapp/whatsapp_bot.py

@@ -2097,8 +2097,17 @@ async def _send_response(
                     f"[TTS] Attempting to send audio response to {to} (chance: {self.config.speech_play_chance * 100}%)"
                 )
                 try:
+                    # Show recording indicator while synthesizing
+                    if self.config.typing_indicator:
+                        logger.debug(
+                            f"[TTS] Sending recording indicator to {to} during synthesis"
+                        )
+                        await self.provider.send_recording_indicator(
+                            to, self.config.typing_duration
+                        )
+
                     # Synthesize speech
-                    speech_result = await self.tts_provider.synthesize(
+                    speech_result = await self.tts_provider.synthesize_async(
                         response_text, config=self.config.speech_config
                     )