Repository: line/line-bot-sdk-python
Pull request #223 (2019-11-11 16:03:56)

Define response object for broadcast api
`broadcast` returns response object which contains `X-Line-Request-Id`.

related: #215, #220


Patch:
diff --git a/README.rst b/README.rst
index d10bbdc..fe097a6 100644
--- a/README.rst
+++ b/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,10 +125,10 @@ 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
 
@@ -136,6 +136,17 @@ https://developers.line.biz/en/reference/messaging-api/#send-multicast-message
 
     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.
 
diff --git a/linebot/api.py b/linebot/api.py
index 111d844..6791a13 100644
--- a/linebot/api.py
+++ b/linebot/api.py
@@ -27,7 +27,7 @@ from .models import (
     MessageDeliveryBroadcastResponse, MessageDeliveryMulticastResponse,
     MessageDeliveryPushResponse, MessageDeliveryReplyResponse,
     InsightMessageDeliveryResponse, InsightFollowersResponse, InsightDemographicResponse,
-    InsightMessageEventResponse,
+    InsightMessageEventResponse, BroadcastResponse,
 )
 
 
@@ -145,7 +145,8 @@ class LineBotApi(object):
 
         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 @@ class LineBotApi(object):
 
         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 @@ class LineBotApi(object):
             '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 @@ class LineBotApi(object):
 
         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.
diff --git a/linebot/models/__init__.py b/linebot/models/__init__.py
index 3d24f44..84601b1 100644
--- a/linebot/models/__init__.py
+++ b/linebot/models/__init__.py
@@ -121,6 +121,7 @@ from .responses import (  # noqa
     InsightFollowersResponse,
     InsightDemographicResponse,
     InsightMessageEventResponse,
+    BroadcastResponse,
 )
 from .rich_menu import (  # noqa
     RichMenu,
diff --git a/linebot/models/responses.py b/linebot/models/responses.py
index c854202..7e69970 100644
--- a/linebot/models/responses.py
+++ b/linebot/models/responses.py
@@ -25,6 +25,20 @@ from .insight import (
 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.
 


Test patch:
diff --git a/tests/api/test_send_text_message.py b/tests/api/test_send_text_message.py
index 1256324..005d424 100644
--- a/tests/api/test_send_text_message.py
+++ b/tests/api/test_send_text_message.py
@@ -112,10 +112,10 @@ class TestSendTestMessage(unittest.TestCase):
         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 @@ class TestSendTestMessage(unittest.TestCase):
                 "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 @@ class TestSendTestMessage(unittest.TestCase):
                 "messages": self.message
             }
         )
+        self.assertEqual('request_id_test', response.request_id)
 
 
 if __name__ == '__main__':