Define response object for broadcast api (#223)

Author: okue

README.rst

@@ -102,8 +102,8 @@ Create a new LineBotApi instance.
 
 You can override the ``timeout`` value for each method.
 
-reply\_message(self, reply\_token, messages, timeout=None)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+reply\_message(self, reply\_token, messages, notification_disabled=False, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Respond to events from users, groups, and rooms. You can get a
 reply\_token from a webhook event object.
@@ -114,8 +114,8 @@ https://developers.line.biz/en/reference/messaging-api/#send-reply-message
 
     line_bot_api.reply_message(reply_token, TextSendMessage(text='Hello World!'))
 
-push\_message(self, to, messages, timeout=None)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+push\_message(self, to, messages, notification_disabled=False, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Send messages to users, groups, and rooms at any time.
 
@@ -125,17 +125,28 @@ https://developers.line.biz/en/reference/messaging-api/#send-push-message
 
     line_bot_api.push_message(to, TextSendMessage(text='Hello World!'))
 
-multicast(self, to, messages, timeout=None)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+multicast(self, to, messages, notification_disabled=False, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Send messages to multiple users at any time.
+Send push messages to multiple users at any time. Messages cannot be sent to groups or rooms.
 
 https://developers.line.biz/en/reference/messaging-api/#send-multicast-message
 
 .. code:: python
 
     line_bot_api.multicast(['to1', 'to2'], TextSendMessage(text='Hello World!'))
 
+broadcast(self, messages, notification_disabled=False, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Send push messages to multiple users at any time.
+
+https://developers.line.biz/en/reference/messaging-api/#send-broadcast-message
+
+.. code:: python
+
+    line_bot_api.broadcast(TextSendMessage(text='Hello World!'))
+
 get\_profile(self, user\_id, timeout=None)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -461,7 +472,7 @@ https://developers.line.biz/en/reference/messaging-api/#revoke-channel-access-to
     line_bot_api.revoke_channel_token(<access_token>)
 
 get\_insight\_message\_delivery(self, date, timeout=None)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Get the number of messages sent on a specified day.
 
@@ -473,7 +484,7 @@ https://developers.line.biz/en/reference/messaging-api/#get-number-of-delivery-m
     print(insight.api_broadcast)
 
 get\_insight\_followers(self, date, timeout=None)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Get the number of users who have added the bot on or before a specified date.
 
@@ -485,7 +496,7 @@ https://developers.line.biz/en/reference/messaging-api/#get-number-of-followers
     print(insight.followers)
 
 get\_insight\_demographic(self, timeout=None)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Retrieve the demographic attributes for a bot's friends.
 
@@ -505,11 +516,12 @@ https://developers.line.biz/en/reference/messaging-api/#get-message-event
 
 .. code:: python
 
-    insight = line_bot_api.get_insight_message_event()
+    broadcast_response = line_bot_api.broadcast(TextSendMessage(text='Hello World!'))
+    insight = line_bot_api.get_insight_message_event(broadcast_response.request_id)
     print(insight.overview)
 
 ※ Error handling
-^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^
 
 If the LINE API server returns an error, LineBotApi raises LineBotApiError.
 

linebot/api.py

@@ -27,7 +27,7 @@
     MessageDeliveryBroadcastResponse, MessageDeliveryMulticastResponse,
     MessageDeliveryPushResponse, MessageDeliveryReplyResponse,
     InsightMessageDeliveryResponse, InsightFollowersResponse, InsightDemographicResponse,
-    InsightMessageEventResponse,
+    InsightMessageEventResponse, BroadcastResponse,
 )
 
 
@@ -145,7 +145,8 @@ def multicast(self, to, messages, notification_disabled=False, timeout=None):
 
         https://developers.line.biz/en/reference/messaging-api/#send-multicast-message
 
-        Send messages to multiple users at any time.
+        Sends push messages to multiple users at any time.
+        Messages cannot be sent to groups or rooms.
 
         :param to: IDs of the receivers
             Max: 150 users
@@ -180,7 +181,7 @@ def broadcast(self, messages, notification_disabled=False, timeout=None):
 
         https://developers.line.biz/en/reference/messaging-api/#send-broadcast-message
 
-        Send messages to multiple users at any time.
+        Sends push messages to multiple users at any time.
 
         :param messages: Messages.
             Max: 5
@@ -202,10 +203,12 @@ def broadcast(self, messages, notification_disabled=False, timeout=None):
             'notificationDisabled': notification_disabled,
         }
 
-        self._post(
+        response = self._post(
             '/v2/bot/message/broadcast', data=json.dumps(data), timeout=timeout
         )
 
+        return BroadcastResponse(request_id=response.headers.get('X-Line-Request-Id'))
+
     def get_message_delivery_broadcast(self, date, timeout=None):
         """Get number of sent broadcast messages.
 
@@ -931,7 +934,6 @@ def get_insight_demographic(self, timeout=None):
 
         https://developers.line.biz/en/reference/messaging-api/#get-demographic
 
-        :param str date: Date for which to retrieve the number of followers.
         :param timeout: (optional) How long to wait for the server
             to send data before giving up, as a float,
             or a (connect timeout, read timeout) float tuple.

linebot/models/__init__.py

@@ -121,6 +121,7 @@
     InsightFollowersResponse,
     InsightDemographicResponse,
     InsightMessageEventResponse,
+    BroadcastResponse,
 )
 from .rich_menu import (  # noqa
     RichMenu,

linebot/models/responses.py

@@ -25,6 +25,20 @@
 from .rich_menu import RichMenuSize, RichMenuArea
 
 
+class BroadcastResponse(object):
+    """BroadcastResponse.
+
+    https://developers.line.biz/en/reference/messaging-api/#send-broadcast-message
+    """
+
+    def __init__(self, request_id=None):
+        """__init__ method.
+
+        :param str request_id: Request ID. A unique ID is generated for each request
+        """
+        self.request_id = request_id
+
+
 class Profile(Base):
     """Profile.
 

tests/api/test_send_text_message.py

@@ -112,10 +112,10 @@ def test_broadcast_text_message(self):
         responses.add(
             responses.POST,
             LineBotApi.DEFAULT_API_ENDPOINT + '/v2/bot/message/broadcast',
-            json={}, status=200
+            json={}, status=200, headers={'X-Line-Request-Id': 'request_id_test'}
         )
 
-        self.tested.broadcast(self.text_message)
+        response = self.tested.broadcast(self.text_message)
 
         request = responses.calls[0].request
         self.assertEqual(
@@ -129,9 +129,10 @@ def test_broadcast_text_message(self):
                 "messages": self.message
             }
         )
+        self.assertEqual('request_id_test', response.request_id)
 
         # call with notification_disable=True
-        self.tested.broadcast(self.text_message, notification_disabled=True)
+        response = self.tested.broadcast(self.text_message, notification_disabled=True)
 
         request = responses.calls[1].request
         self.assertEqual(
@@ -145,6 +146,7 @@ def test_broadcast_text_message(self):
                 "messages": self.message
             }
         )
+        self.assertEqual('request_id_test', response.request_id)
 
 
 if __name__ == '__main__':