agentle 0.9.39__tar.gz → 0.9.40__tar.gz

{agentle-0.9.39 → agentle-0.9.40}/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v0.9.40
+feat(whatsapp): support for welcome images
+
 ## v0.9.39
 making pushname optional
 

{agentle-0.9.39 → agentle-0.9.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentle
-Version: 0.9.39
+Version: 0.9.40
 Summary: ...
 Author-email: Arthur Brenno <64020210+arthurbrenno@users.noreply.github.com>
 License-File: LICENSE

{agentle-0.9.39 → agentle-0.9.40}/agentle/agents/whatsapp/models/whatsapp_bot_config.py

@@ -98,7 +98,13 @@ class WhatsAppBotConfig(BaseModel):
         description="Default error message",
     )
     welcome_message: str | None = Field(
-        default=None, description="Message to send on first interaction"
+        default=None, description="Message to send on first interaction (or caption if welcome image is set)"
+    )
+    welcome_image_url: str | None = Field(
+        default=None, description="URL of welcome image to send on first interaction"
+    )
+    welcome_image_base64: str | None = Field(
+        default=None, description="Base64-encoded welcome image to send on first interaction (alternative to welcome_image_url)"
     )
 
     # === Message Batching (Simplified) ===
@@ -257,6 +263,8 @@ class WhatsAppBotConfig(BaseModel):
         max_split_messages: int | None = None,
         error_message: str | None = None,
         welcome_message: str | None = None,
+        welcome_image_url: str | None = None,
+        welcome_image_base64: str | None = None,
         # Message Batching
         enable_message_batching: bool | None = None,
         batch_delay_seconds: float | None = None,
@@ -366,6 +374,10 @@ class WhatsAppBotConfig(BaseModel):
             overrides["error_message"] = error_message
         if welcome_message is not None:
             overrides["welcome_message"] = welcome_message
+        if welcome_image_url is not None:
+            overrides["welcome_image_url"] = welcome_image_url
+        if welcome_image_base64 is not None:
+            overrides["welcome_image_base64"] = welcome_image_base64
 
         # Message Batching
         if enable_message_batching is not None:

{agentle-0.9.39 → agentle-0.9.40}/agentle/agents/whatsapp/providers/evolution/evolution_api_provider.py

@@ -1597,15 +1597,18 @@ class EvolutionAPIProvider(WhatsAppProvider):
         Normalize phone number to Evolution API format.
 
         Evolution API expects phone numbers in the format: countrycode+number@s.whatsapp.net
+        For Brazilian numbers, we now test with @lid format instead.
 
         Brazilian mobile format: 55 + DDD (2 digits) + 9 + 8 digits = 13 digits total
-        Example: 5534998137839@s.whatsapp.net
+        Example: 5534998137839@lid
         """
         original_phone = phone
 
-        # Remove @s.whatsapp.net suffix if present
+        # Remove @s.whatsapp.net or @lid suffix if present
         if "@s.whatsapp.net" in phone:
             phone = phone.split("@")[0]
+        elif "@lid" in phone:
+            phone = phone.split("@")[0]
 
         # Remove non-numeric characters
         phone = "".join(c for c in phone if c.isdigit())
@@ -1657,9 +1660,15 @@ class EvolutionAPIProvider(WhatsAppProvider):
                     f"Phone number may be invalid - 5th digit is not '9': {phone}"
                 )
 
-        # Add @s.whatsapp.net suffix if not present
-        if not phone.endswith("@s.whatsapp.net"):
-            phone = phone + "@s.whatsapp.net"
+        # TESTING: Use @lid for Brazilian numbers (country code 55) instead of @s.whatsapp.net
+        if not phone.endswith("@lid") and not phone.endswith("@s.whatsapp.net"):
+            if phone.startswith("55"):
+                # Brazilian number - use @lid
+                phone = phone + "@lid"
+                logger.info(f"🧪 TESTING: Using @lid for Brazilian number: {phone}")
+            else:
+                # Non-Brazilian number - use @s.whatsapp.net
+                phone = phone + "@s.whatsapp.net"
 
         if original_phone != phone:
             logger.info(f"Phone number normalized: {original_phone} -> {phone}")

{agentle-0.9.39 → agentle-0.9.40}/agentle/agents/whatsapp/whatsapp_bot.py

@@ -431,23 +431,117 @@ class WhatsAppBot[T_Schema: WhatsAppResponseBase = WhatsAppResponseBase](BaseMod
                 f"[MESSAGE_HANDLER] Effective chat_id para conversação: {effective_chat_id}"
             )
 
-            # Check welcome message for first interaction
+            # Check welcome message/image for first interaction
             if (
                 await cast(
                     ConversationStore, self.agent.conversation_store
                 ).get_conversation_history_length(effective_chat_id)
                 == 0
-                and self.config.welcome_message
+                and (
+                    self.config.welcome_message
+                    or self.config.welcome_image_url
+                    or self.config.welcome_image_base64
+                )
             ):
                 logger.info(
-                    f"[WELCOME] Sending welcome message to {message.from_number}"
+                    f"[WELCOME] Sending welcome message/image to {message.from_number}"
                 )
-                formatted_welcome = self._format_whatsapp_markdown(
-                    self.config.welcome_message
-                )
-                await self.provider.send_text_message(
-                    message.from_number, formatted_welcome
+
+                # Determine if we're sending an image or text
+                has_welcome_image = (
+                    self.config.welcome_image_url or self.config.welcome_image_base64
                 )
+
+                if has_welcome_image:
+                    # Prepare caption from welcome_message if available
+                    caption = None
+                    if self.config.welcome_message:
+                        caption = self._format_whatsapp_markdown(
+                            self.config.welcome_message
+                        )
+
+                    # Handle welcome image via URL
+                    if self.config.welcome_image_url:
+                        logger.info(
+                            f"[WELCOME] Sending welcome image from URL to {message.from_number}"
+                        )
+                        await self.provider.send_media_message(
+                            to=message.from_number,
+                            media_url=self.config.welcome_image_url,
+                            media_type="image",
+                            caption=caption,
+                        )
+                    # Handle welcome image via base64
+                    elif self.config.welcome_image_base64:
+                        # Try to upload base64 to file storage if available
+                        image_url = None
+                        if self.file_storage_manager:
+                            try:
+                                import base64
+                                import time
+
+                                logger.info(
+                                    "[WELCOME] Uploading base64 welcome image to file storage"
+                                )
+
+                                # Decode base64 to bytes
+                                image_bytes = base64.b64decode(
+                                    self.config.welcome_image_base64
+                                )
+
+                                # Generate unique filename
+                                timestamp = int(time.time())
+                                filename = f"welcome_image_{timestamp}.jpg"
+
+                                # Upload to storage
+                                image_url = await self.file_storage_manager.upload_file(
+                                    file_data=image_bytes,
+                                    filename=filename,
+                                    mime_type="image/jpeg",
+                                )
+
+                                logger.info(
+                                    f"[WELCOME] Welcome image uploaded to storage: {image_url}"
+                                )
+                            except Exception as e:
+                                logger.warning(
+                                    f"[WELCOME] Failed to upload welcome image to storage: {e}"
+                                )
+                                image_url = None
+
+                        # Send image via URL if upload succeeded, otherwise send text fallback
+                        if image_url:
+                            logger.info(
+                                f"[WELCOME] Sending uploaded welcome image to {message.from_number}"
+                            )
+                            await self.provider.send_media_message(
+                                to=message.from_number,
+                                media_url=image_url,
+                                media_type="image",
+                                caption=caption,
+                            )
+                        else:
+                            # Fallback to text if base64 upload failed and no URL available
+                            logger.warning(
+                                "[WELCOME] Could not send welcome image (base64 upload failed and no URL), falling back to text"
+                            )
+                            if caption:
+                                await self.provider.send_text_message(
+                                    message.from_number, caption
+                                )
+                            else:
+                                logger.warning(
+                                    "[WELCOME] No caption available, skipping welcome message"
+                                )
+                else:
+                    # Send text-only welcome message (backward compatible)
+                    formatted_welcome = self._format_whatsapp_markdown(
+                        self.config.welcome_message
+                    )
+                    await self.provider.send_text_message(
+                        message.from_number, formatted_welcome
+                    )
+
                 session.message_count += 1
                 await self.provider.update_session(session)
 

agentle-0.9.40/examples/whatsapp_welcome_image_example.py

@@ -0,0 +1,87 @@
+"""
+Example: WhatsApp Bot with Welcome Image
+
+This example demonstrates how to send an image as the first message
+in a WhatsApp conversation using the new welcome_image feature.
+"""
+
+from agentle.agents.whatsapp.whatsapp_bot import WhatsAppBot
+from agentle.agents.whatsapp.models.whatsapp_bot_config import WhatsAppBotConfig
+from agentle.agents.whatsapp.providers.evolution.evolution_api_provider import (
+    EvolutionAPIProvider,
+)
+from agentle.agents.whatsapp.providers.evolution.evolution_api_config import (
+    EvolutionAPIConfig,
+)
+
+# Example 1: Welcome image from URL
+config_with_url = WhatsAppBotConfig.production(
+    welcome_message="Welcome! 👋 How can I help you today?",
+    welcome_image_url="https://example.com/welcome-banner.jpg",
+)
+
+# Example 2: Welcome image from base64
+# Note: Base64 image requires file_storage_manager to be configured
+# Otherwise, it will fall back to sending the text caption only
+config_with_base64 = WhatsAppBotConfig.production(
+    welcome_message="Welcome to our service!",
+    welcome_image_base64="iVBORw0KGgoAAAANSUhEUgAAAAUA...",  # Your base64 image data
+)
+
+# Example 3: Welcome image without caption (image only)
+config_image_only = WhatsAppBotConfig.production(
+    welcome_image_url="https://example.com/banner.png",
+    # No welcome_message means the image will be sent without a caption
+)
+
+# Example 4: Traditional text-only welcome (backward compatible)
+config_text_only = WhatsAppBotConfig.production(
+    welcome_message="Hello! I'm your assistant.",
+    # No welcome_image_url or welcome_image_base64 means text-only
+)
+
+# Setup provider and bot
+evolution_config = EvolutionAPIConfig(
+    base_url="https://your-evolution-api.com",
+    api_key="your-api-key",
+    instance_name="your-instance",
+)
+
+provider = EvolutionAPIProvider(config=evolution_config)
+
+# Create bot with welcome image
+bot = WhatsAppBot(
+    agent=your_agent,  # Your configured agent
+    provider=provider,
+    config=config_with_url,  # Use any of the configs above
+    file_storage_manager=your_storage_manager,  # Required for base64 images
+)
+
+# The welcome image will be automatically sent when a user
+# sends their first message to the bot
+
+"""
+How it works:
+
+1. When a user sends their first message:
+   - Bot checks if it's the first interaction (conversation history length == 0)
+   - If welcome_image_url is set: Sends the image from the URL
+   - If welcome_image_base64 is set: Uploads to storage first, then sends
+   - welcome_message is used as the image caption (optional)
+   - If no image is configured, sends text-only message (backward compatible)
+
+2. Priority:
+   - welcome_image_url takes precedence over welcome_image_base64
+   - If both image and text are configured, text becomes the caption
+   - If only text is configured, sends text-only (backward compatible)
+
+3. Base64 handling:
+   - Requires file_storage_manager to be configured
+   - Automatically uploads base64 to storage and gets URL
+   - Falls back to text-only if upload fails
+
+4. Error handling:
+   - If image sending fails, falls back to text caption
+   - If no caption available, logs warning and skips
+   - All errors are logged for debugging
+"""

{agentle-0.9.39 → agentle-0.9.40}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentle"
-version = "v0.9.39"
+version = "v0.9.40"
 description = "..."
 readme = "README.md"
 requires-python = ">=3.13"