[client] add method to send interactive media carousel messages (suggested feature from discussion #197)

Author: david-lev

docs/source/content/client/client_reference.rst

@@ -17,6 +17,7 @@ Client Reference
 .. automethod:: WhatsApp.send_template
 .. automethod:: WhatsApp.send_product
 .. automethod:: WhatsApp.send_products
+.. automethod:: WhatsApp.send_carousel
 .. automethod:: WhatsApp.send_reaction
 .. automethod:: WhatsApp.remove_reaction
 .. automethod:: WhatsApp.mark_message_as_read

docs/source/content/client/overview.rst

@@ -86,6 +86,8 @@ The client allows you to send a wide variety of messages:
      - Send a single product
    * - :meth:`~WhatsApp.send_products`
      - Send multiple products
+   * - :meth:`~WhatsApp.send_carousel`
+     - Send a carousel message
    * - :meth:`~WhatsApp.send_reaction`
      - React to a message
    * - :meth:`~WhatsApp.remove_reaction`

docs/source/content/types/keyboard.rst

@@ -21,6 +21,10 @@ Keyboard
 
 .. autoclass:: ContactInfoRequestButton()
 
+.. autoclass:: ImageCarouselCard()
+
+.. autoclass:: VideoCarouselCard()
+
 .. autoclass:: CallbackData()
 
 ----------------

docs/source/content/updates/common_methods.rst

@@ -9,5 +9,5 @@ Common methods
 .. autoclass:: BaseUserUpdate()
     :members: sender, recipient, message_id_to_reply,
         reply_text, reply_image, reply_video, reply_audio, reply_voice, reply_document, reply_location, reply_location_request,
-        reply_contact, reply_sticker, reply_template, reply_catalog, reply_product, reply_products, react, unreact,
+        reply_contact, reply_sticker, reply_template, reply_catalog, reply_product, reply_products, reply_carousel, react, unreact,
         mark_as_read, indicate_typing, block_sender, unblock_sender, call

docs/source/content/updates/overview.rst

@@ -177,6 +177,8 @@ All updates share common methods and properties:
      - Reply with a product message
    * - :meth:`~BaseUserUpdate.reply_products`
      - Reply with a list of product messages
+   * - :meth:`~BaseUserUpdate.reply_carousel`
+     - Reply with a carousel message
    * - :meth:`~BaseUserUpdate.react`
      - React to the update with an emoji
    * - :meth:`~BaseUserUpdate.unreact`

pywa/client.py

@@ -86,6 +86,7 @@
     FlowRequest,
     GroupMessageStatuses,
     IdentityChange,
+    ImageCarouselCard,
     Industry,
     MediaURL,
     Message,
@@ -106,9 +107,11 @@
     URLButton,
     User,
     UserMarketingPreferences,
+    VideoCarouselCard,
     VoiceCallButton,
 )
 from .types.base_update import BaseUpdate
+from .types.callback import BaseCarouselCard
 from .types.calls import CallPermissions, SessionDescription
 from .types.flows import (
     CreatedFlow,
@@ -1819,6 +1822,63 @@ def send_products(
             interactive_type=InteractiveType.PRODUCT_LIST,
         )
 
+    def send_carousel(
+        self,
+        to: str | int,
+        *,
+        body: str,
+        cards: list[ImageCarouselCard | VideoCarouselCard | BaseCarouselCard],
+        reply_to_message_id: str | None = None,
+        tracker: str | CallbackData | None = None,
+        identity_key_hash: str | None = None,
+        sender: str | int | None = None,
+    ) -> SentMessage:
+        """
+        Interactive media carousel messages display a set of horizontally scrollable media cards.
+
+        - See `Carousel messages <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-media-carousel-messages>`_.
+
+        Args:
+            to: The user phone number, WhatsApp ID, BSUID or group ID to send the message to.
+            body: Text to appear in the message body (up to 1024 characters).
+            cards: The carousel cards to send (up to 10).
+            reply_to_message_id: The message ID to quote (optional).
+            tracker: The data to track the message with (optional, up to 512 characters, for complex data you can use :class:`~pywa.types.callback.CallbackData`).
+            identity_key_hash: The message would only be delivered if the hash value matches the customer's current hash (Optional, See `Identity Change Check <https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#identity-change-check>`_).
+            sender: The phone ID to send the message from (optional, overrides the client's phone ID).
+
+        Returns:
+            The sent carousel message.
+        """
+        sender = helpers.resolve_arg(
+            wa=self, value=sender, method_arg="sender", client_arg="phone_id"
+        )
+
+        recipient, recipient_type = helpers.resolve_recipient(to)
+        return SentMessage.from_sent_update(
+            client=self,
+            update=self.api.send_message(
+                sender=sender,
+                **recipient,
+                typ="interactive",
+                msg=helpers.get_interactive_msg(
+                    typ=InteractiveType.CAROUSEL,
+                    action={
+                        "cards": [
+                            card.to_dict(idx=idx) for idx, card in enumerate(cards)
+                        ]
+                    },
+                    body=body,
+                ),
+                reply_to_message_id=reply_to_message_id,
+                biz_opaque_callback_data=helpers.resolve_tracker_param(tracker),
+                recipient_identity_key_hash=identity_key_hash,
+            ),
+            from_phone_id=sender,
+            recipient_type=recipient_type,
+            interactive_type=InteractiveType.PRODUCT_LIST,
+        )
+
     def mark_message_as_read(
         self,
         message_id: str,

pywa/types/__init__.py

@@ -16,6 +16,8 @@
     SectionRow,
     FlowButton,
     ContactInfoRequestButton,
+    VideoCarouselCard,
+    ImageCarouselCard,
 )
 from .media import MediaURL, Audio, Document, Image, Sticker, Video
 from .message import Message, EditedMessage, DeletedMessage, OutgoingMessage, OutgoingEditedMessage, OutgoingDeletedMessage

pywa/types/base_update.py

@@ -31,12 +31,15 @@
 if TYPE_CHECKING:
     from ..client import WhatsApp
     from .callback import (
+        BaseCarouselCard,
         Button,
         CallbackData,
         CallPermissionRequestButton,
         FlowButton,
+        ImageCarouselCard,
         SectionList,
         URLButton,
+        VideoCarouselCard,
         VoiceCallButton,
     )
     from .calls import SessionDescription
@@ -1133,6 +1136,44 @@ def reply_template(
             tracker=tracker,
         )
 
+    def reply_carousel(
+        self,
+        *,
+        body: str,
+        cards: list[ImageCarouselCard | VideoCarouselCard | BaseCarouselCard],
+        quote: bool = False,
+        private: bool = False,
+        tracker: str | CallbackData | None = None,
+        identity_key_hash: str | None = None,
+        sender: str | int | None = None,
+    ) -> SentMessage:
+        """
+        Interactive media carousel messages display a set of horizontally scrollable media cards.
+
+        - See `Carousel messages <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-media-carousel-messages>`_.
+
+        Args:
+            body: Text to appear in the message body (up to 1024 characters).
+            cards: The list of carousel cards (up to 10 cards).
+            quote: Whether to quote the replied message (default: False).
+            private: Whether to send a private message instead of replying in the same chat (default: False, only applicable for group messages).
+            tracker: The data to track the message with (optional, up to 512 characters, for complex data you can use :class:`~pywa.types.callback.CallbackData`).
+            identity_key_hash: The message would only be delivered if the hash value matches the customer's current hash (Optional, See `Identity Change Check <https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#identity-change-check>`_).
+            sender: The sender of the message (optional, if not provided, ``recipient`` will be used).
+
+        Returns:
+            The sent carousel message.
+        """
+        return self._client.send_carousel(
+            sender=sender or self._internal_recipient,
+            to=self._get_reply_to(private),
+            body=body,
+            cards=cards,
+            reply_to_message_id=self.message_id_to_reply if quote else None,
+            identity_key_hash=identity_key_hash,
+            tracker=tracker,
+        )
+
     def mark_as_read(self) -> SuccessResult:
         """
         Mark the message as read.

pywa/types/callback.py

@@ -12,6 +12,8 @@
     "Section",
     "SectionList",
     "FlowButton",
+    "ImageCarouselCard",
+    "VideoCarouselCard",
     "CallbackData",
 ]
 
@@ -653,3 +655,86 @@ def to_dict(self) -> dict:
                 ),
             },
         }
+
+
+@dataclasses.dataclass(slots=True, kw_only=True)
+class BaseCarouselCard:
+    body: str | None = None
+    buttons: Iterable[Button] | URLButton
+
+    def to_dict(self, idx: int) -> dict:
+        if isinstance(self.buttons, URLButton):
+            action = {
+                "name": "cta_url",
+                "parameters": {
+                    "display_text": self.buttons.title,
+                    "url": self.buttons.url,
+                },
+            }
+        else:
+            action = {
+                "buttons": [
+                    {
+                        "type": "quick_reply",
+                        "quick_reply": {
+                            "id": helpers.resolve_callback_data(b.callback_data),
+                            "title": b.title,
+                        },
+                    }
+                    for b in self.buttons
+                ]
+            }
+        payload = {
+            "card_index": idx,
+            "type": "cta_url",
+            "action": action,
+        }
+        if self.body is not None:
+            payload["body"] = {
+                "text": self.body,
+            }
+        return payload
+
+
+class _BaseMediaCarouselCard(BaseCarouselCard):
+    _header_type: ClassVar[str]
+
+    def to_dict(self, idx: int) -> dict:
+        common = super().to_dict(idx)
+        common["header"] = {
+            "type": self._header_type,
+            self._header_type: {"link": getattr(self, self._header_type)},
+        }
+        return common
+
+
+@dataclasses.dataclass(slots=True, kw_only=True)
+class ImageCarouselCard(_BaseMediaCarouselCard):
+    """
+    Represents a card in a carousel message with an image header.
+
+    Attributes:
+        body: The body text of the card (optional, Max 160 characters, and up to 2 line breaks).
+        image: Publicly available media asset URL.
+        buttons: The buttons of the card (either a list of up to 3 :class:`Button` or a single :class:`URLButton`).
+    """
+
+    _header_type = "image"
+
+    image: str
+
+
+@dataclasses.dataclass(slots=True, kw_only=True)
+class VideoCarouselCard(_BaseMediaCarouselCard):
+    """
+    Represents a card in a carousel message with an video header.
+
+    Attributes:
+        body: The body text of the card (optional, Max 160 characters, and up to 2 line breaks).
+        video: Publicly available media asset URL.
+        buttons: The buttons of the card (either a list of up to 3 :class:`Button` or a single :class:`URLButton`).
+    """
+
+    _header_type = "video"
+
+    video: str

pywa/types/others.py

@@ -102,6 +102,7 @@ class InteractiveType(helpers.StrEnum):
     VOICE_CALL = "voice_call"
     CALL_PERMISSION_REQUEST = "call_permission_request"
     REQUEST_CONTACT_INFO = "request_contact_info"
+    CAROUSEL = "carousel"
 
     UNKNOWN = "UNKNOWN"