Update Messages API

- Add the parentId parameter to the messages.list() method.
- Add the messages.list_direct() API endpoint.
- Update the message data model attributes.

Author: cmlccie

webexteamssdk/api/messages.py

@@ -73,8 +73,8 @@ def __init__(self, session, object_factory):
         self._object_factory = object_factory
 
     @generator_container
-    def list(self, roomId, mentionedPeople=None, before=None,
-             beforeMessage=None, max=None, **request_parameters):
+    def list(self, roomId, parentId=None, mentionedPeople=None, before=None,
+             beforeMessage=None, max=50, **request_parameters):
         """Lists messages in a room.
 
         Each message will include content attachments if present.
@@ -93,6 +93,7 @@ def list(self, roomId, mentionedPeople=None, before=None,
 
         Args:
             roomId(basestring): List messages for a room, by ID.
+            parentId(basestring): List messages with a parent, by ID.
             mentionedPeople(basestring): List messages where the caller is
                 mentioned by specifying "me" or the caller `personId`.
             before(basestring): List messages sent before a date and time, in
@@ -114,6 +115,7 @@ def list(self, roomId, mentionedPeople=None, before=None,
 
         """
         check_type(roomId, basestring)
+        check_type(parentId, basestring, optional=True)
         check_type(mentionedPeople, basestring, optional=True)
         check_type(before, basestring, optional=True)
         check_type(beforeMessage, basestring, optional=True)
@@ -122,6 +124,7 @@ def list(self, roomId, mentionedPeople=None, before=None,
         params = dict_from_items_with_values(
             request_parameters,
             roomId=roomId,
+            parentId=parentId,
             mentionedPeople=mentionedPeople,
             before=before,
             beforeMessage=beforeMessage,
@@ -135,9 +138,67 @@ def list(self, roomId, mentionedPeople=None, before=None,
         for item in items:
             yield self._object_factory(OBJECT_TYPE, item)
 
-    def create(self, roomId=None, toPersonId=None, toPersonEmail=None,
-               text=None, markdown=None, files=None, attachments=None,
-               parentId=None, **request_parameters):
+    @generator_container
+    def list_direct(self, personId=None, personEmail=None, parentId=None,
+                    **request_parameters):
+        """List all messages in a 1:1 (direct) room.
+
+        Use the `personId` or `personEmail` query parameter to specify the
+        room.
+
+        The list API sorts the messages in descending order by creation date.
+
+        This method supports Webex Teams's implementation of RFC5988 Web
+        Linking to provide pagination support.  It returns a generator
+        container that incrementally yields all messages returned by the
+        query.  The generator will automatically request additional 'pages' of
+        responses from Webex as needed until all responses have been returned.
+        The container makes the generator safe for reuse.  A new API call will
+        be made, using the same parameters that were specified when the
+        generator was created, every time a new iterator is requested from the
+        container.
+
+        Args:
+            personId(basestring): List messages in a 1:1 room, by person ID.
+            personEmail(basestring): List messages in a 1:1 room, by person
+                email.
+            parentId(basestring): List messages with a parent, by ID.
+            **request_parameters: Additional request parameters (provides
+                support for parameters that may be added in the future).
+
+        Returns:
+            GeneratorContainer: A GeneratorContainer which, when iterated,
+            yields the messages returned by the Webex Teams query.
+
+        Raises:
+            TypeError: If the parameter types are incorrect.
+            ApiError: If the Webex Teams cloud returns an error.
+
+        """
+        check_type(personId, basestring, optional=True)
+        check_type(personEmail, basestring, optional=True)
+        check_type(parentId, basestring, optional=True)
+
+        params = dict_from_items_with_values(
+            request_parameters,
+            personId=personId,
+            personEmail=personEmail,
+            parentId=parentId,
+        )
+
+        # API request - get items
+        items = self._session.get_items(
+            API_ENDPOINT + "/direct",
+            params=params,
+        )
+
+        # Yield message objects created from the returned items JSON objects
+        for item in items:
+            yield self._object_factory(OBJECT_TYPE, item)
+
+    def create(self, roomId=None, parentId=None, toPersonId=None,
+               toPersonEmail=None, text=None, markdown=None, files=None,
+               attachments=None, **request_parameters):
         """Post a message to a room.
 
         The files parameter is a list, which accepts multiple values to allow

webexteamssdk/models/mixins/message.py

@@ -41,12 +41,17 @@ class MessageBasicPropertiesMixin(object):
     @property
     def id(self):
         """The unique identifier for the message."""
-        return self._json_data.get('id')
+        return self._json_data.get("id")
+
+    @property
+    def parentId(self):
+        """The unique identifier for the parent message."""
+        return self._json_data.get("parentId")
 
     @property
     def roomId(self):
         """The room ID of the message."""
-        return self._json_data.get('roomId')
+        return self._json_data.get("roomId")
 
     @property
     def roomType(self):
@@ -56,57 +61,79 @@ def roomType(self):
             `direct`: 1:1 room
             `group`: Group room
         """
-        return self._json_data.get('roomType')
+        return self._json_data.get("roomType")
+
+    @property
+    def toPersonId(self):
+        """The person ID of the recipient when sending a 1:1 message."""
+        return self._json_data.get("toPersonId")
+
+    @property
+    def toPersonEmail(self):
+        """The email address of the recipient when sending a 1:1 message."""
+        return self._json_data.get("toPersonEmail")
 
     @property
     def text(self):
         """The message, in plain text."""
-        return self._json_data.get('text')
+        return self._json_data.get("text")
 
     @property
     def markdown(self):
         """The message, in Markdown format."""
-        return self._json_data.get('markdown')
+        return self._json_data.get("markdown")
 
     @property
     def html(self):
-        """The message, in HTML format."""
-        return self._json_data.get('html')
+        """The text content of the message, in HTML format.
+
+        This read-only property is used by the Webex Teams clients.
+        """
+        return self._json_data.get("html")
 
     @property
     def files(self):
         """Public URLs for files attached to the message."""
-        return self._json_data.get('files')
+        return self._json_data.get("files")
 
     @property
     def personId(self):
         """The person ID of the message author."""
-        return self._json_data.get('personId')
+        return self._json_data.get("personId")
 
     @property
     def personEmail(self):
         """The email address of the message author."""
-        return self._json_data.get('personEmail')
+        return self._json_data.get("personEmail")
 
     @property
     def mentionedPeople(self):
         """People IDs for anyone mentioned in the message."""
-        return self._json_data.get('mentionedPeople')
+        return self._json_data.get("mentionedPeople")
 
     @property
     def mentionedGroups(self):
         """Group names for the groups mentioned in the message."""
-        return self._json_data.get('mentionedGroups')
+        return self._json_data.get("mentionedGroups")
 
     @property
-    def parentId(self):
-        """The unique identifier for the parent message."""
-        return self._json_data.get('parentId')
+    def attachments(self):
+        """Message content attachments attached to the message."""
+        return self._json_data.get("attachments")
 
     @property
     def created(self):
         """The date and time the message was created."""
-        created = self._json_data.get('created')
+        created = self._json_data.get("created")
+        if created:
+            return WebexTeamsDateTime.strptime(created)
+        else:
+            return None
+
+    @property
+    def updated(self):
+        """The date and time the message was created."""
+        created = self._json_data.get("updated")
         if created:
             return WebexTeamsDateTime.strptime(created)
         else: