Package com.avaya.clientservices.messaging

## Interface Message

-     public interface Message

  Interface for all Message related tasks and properties.

  Message is a crucial part of the conversation. It can store not only text content or attachments, but is also used to inform about any event that occurred in the conversation, like a new participant or subject change. It is important to notice that the body cannot be empty for a usual message, unless an attachment is present.

  To create a new message, call the `Conversation.createMessage()` method, which will return a new object. After filling out the message and its other parameters, use the `send(MessagingCompletionHandler)` operation in order to send a message.

  An important part of the message is also attachments. In order to create a new attachment in a message object, use the `createAttachment()` method.

  Besides normal messages with text body there are also messages informing about events. `MessageType` is informing about an event type and these objects do not contain any text body. They can have some additional data about an event, i.e. `getAddedParticipants()`, `getRemovedParticipants()`, etc.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addListener​(MessageListener listener)` | Adds a new listener to the message.
    `Attachment` | `createAttachment()` | Creates an `Attachment` for this message.
    `java.util.List<MessagingParticipant>` | `getAddedParticipants()` | When the message type is `MessageType.JOINED`, this property returns the list of participants that were added to the conversation.
    `java.util.List<Attachment>` | `getAttachments()` | Gets the list of attachments for this message.
    `java.lang.String` | `getBody()` | Returns the body of the message.
    `java.lang.String` | `getConversationId()` | Returns the unique identifier of the conversation to which this message belongs.
    `Capability` | `getCreateAttachmentCapability()` | Returns a `Capability` object that indicates if an attachment can be added to the message.
    `void` | `getDeliveryDetails​(MessageDeliveryDetailsCompletionHandler completionHandler)` | Gets MessageDeliveryDetails or error.
    `Capability` | `getDeliveryDetailsCapability()` | Capability indicating whether the message can provide its delivery details.
    `MessageDeliveryState` | `getDeliveryState()` | The message delivery state describing whether this message is sent or delivered to one or more recipients.
    `MessagingParticipant` | `getFromParticipant()` | Returns the participant who was the sender of the message.
    `java.lang.String` | `getHtmlBody()` | Returns the HTML body of the message if the HTML body available, otherwise an empty string returned.
    `java.lang.String` | `getId()` | Returns the unique message identifier.
    `MessageImportance` | `getImportance()` | Returns the message importance.
    `MessagingParticipant` | `getInitiatorParticipant()` | Get initiator participant of an event message, such as LEFT message when a participant is removed from conversation by other participant(initiator)
    `void` | `getInReplyTo​(MessageCompletionHandler completionHandler)` | Gets InReplyToMessage or error if message is not in cache.
    `java.util.Date` | `getLastModifiedDate()` | Returns the date and time that the message was last modified.
    `Capability` | `getMarkAsReadCapability()` | Returns a `Capability` object that indicates if the message can be marked as read.
    `java.lang.String` | `getProviderMessageId()` | Returns the message ID from the underlying provider (e.g., the AMM server) as-is.
    `MessagingProviderType` | `getProviderType()` | Returns a provider type for the message.
    `MessageReadState` | `getReadState()` | The message read state describing whether this message is read, partially read or not read.
    `MessagingReasonType` | `getReason()` | Returns the message reason type.
    `java.util.Date` | `getReceivedDate()` | Returns the date and time that the message was received.
    `java.util.List<MessagingParticipant>` | `getRecipients()` | Returns the list of participants, including the sender, that the message was sent to.
    `Capability` | `getRemoveCapability()` | Returns a `Capability` object that indicates if the message can be removed.
    `java.util.List<MessagingParticipant>` | `getRemovedParticipants()` | When the message type is `MessageType.LEFT`, this property returns the list of participants that were removed from the conversation.
    `Capability` | `getSendCapability()` | Returns a `Capability` object that indicates if the message can be sent.
    `SensitivityLevel` | `getSensitivity()` | Returns the message sensitivity.
    `MessageStatus` | `getStatus()` | Returns the message status.
    `java.lang.String` | `getSubject()` | Returns the subject of the conversation at the time the message was sent.
    `MessageType` | `getType()` | Returns the message type.
    `Capability` | `getUpdateBodyCapability()` | Returns a `Capability` object that indicates if the body text or "is typing" status of the message can be updated.
    `Capability` | `getUpdateDoNotForwardCapability()` | Returns a `Capability` object that indicates if the DoNotForward attribute of the message can be updated.
    `Capability` | `getUpdateImportanceCapability()` | Returns a `Capability` object that indicates if the Importance attribute of the message can be updated.
    `Capability` | `getUpdateInReplyToCapability()` | Returns a `Capability` object that indicates if the InReplyTo attribute of the message can be updated.
    `boolean` | `hasAttachment()` | Returns true if the message has one or more attachments.
    `boolean` | `hasHtmlBody()` | Returns true if the message contains HTML body.
    `boolean` | `hasInReplyTo()` | Returns true if message has InReplyTo message (does not mean it is in cache).
    `boolean` | `hasUnreadAttachment()` | Returns true if the message has a least one attachment that has not been viewed.
    `boolean` | `isCoalesced()` | Deprecated. THIS METHOD WILL BE REMOVED IN RELEASE VERSION 3.3.
    `boolean` | `isDoNotForward()` | Returns the IsDoNotForward status of the message, which indicates if the sender of this message had disallowed forwarding of this particular message.
    `boolean` | `isFromMe()` | Returns true if the current user is the sender of the message.
    `boolean` | `isPrivate()` | Returns true if the message is marked as a private message.
    `boolean` | `isRead()` | Deprecated. use `getReadState()` method instead.
    `void` | `markAsRead()` | Marks the message as read.
    `void` | `removeAttachment​(Attachment attachment, MessagingCompletionHandler completionHandler)` | Remove a specified attachment from this message.
    `void` | `removeListener​(MessageListener listener)` | Removes a listener from the message.
    `void` | `reportTyping​(boolean isTyping)` | Set or clear the "is typing" chat state.
    `void` | `send​(MessagingCompletionHandler completionHandler)` | Invokes a send request for this message.
    `int` | `setBodyAndReportTyping​(java.lang.String body, MessagingCompletionHandler completionHandler)` | Sets the body of the draft message and the "is typing" chat state.
    `void` | `setDoNotForward​(boolean state, MessagingCompletionHandler completionHandler)` | Sets a new message "do not forward" state.
    `void` | `setImportance​(MessageImportance importance, MessagingCompletionHandler completionHandler)` | Sets a new message importance.
    `void` | `setInReplyTo​(Message message, MessagingCompletionHandler completionHandler)` | Sets the message that the current message is a direct reply to.

- - ### Method Detail

    - #### addListener

          void addListener​(MessageListener listener)

      Adds a new listener to the message.
      Parameters:
        `listener` - `MessageListener` to be added to the service.

    - #### removeListener

          void removeListener​(MessageListener listener)

      Removes a listener from the message.
      Parameters:
        `listener` - `MessageListener` instance that is removed from the service.

    - #### getId

          java.lang.String getId()

      Returns the unique message identifier.
      Returns:
        the unique message identifier.

    - #### getProviderMessageId

          java.lang.String getProviderMessageId()

      Returns the message ID from the underlying provider (e.g., the AMM server) as-is. It will be consistent across clients and application launches, but is only guaranteed to be unique for messages of that provider type.
      Returns:
        a protocol level identifier of the message. It will be empty for draft message.

    - #### getConversationId

          java.lang.String getConversationId()

      Returns the unique identifier of the conversation to which this message belongs.
      Returns:
        the unique identifier of the conversation to which this message belongs.
      See Also:
        `Conversation.getId()`

    - #### getSubject

          java.lang.String getSubject()

      Returns the subject of the conversation at the time the message was sent.
      Returns:
        the subject of the conversation at the time the message was sent.
      See Also:
        `Conversation.getSubject()`

    - #### getBody

          java.lang.String getBody()

      Returns the body of the message.
      Returns:
        the body of the message.
      See Also:
        `setBodyAndReportTyping(String, MessagingCompletionHandler)`, `getHtmlBody()`

    - #### getHtmlBody

          java.lang.String getHtmlBody()

      Returns the HTML body of the message if the HTML body available, otherwise an empty string returned.
      Returns:
        the HTML body of the message.
      See Also:
        `getBody()`, `hasHtmlBody()`, `setBodyAndReportTyping(String, MessagingCompletionHandler)`

    - #### hasHtmlBody

          boolean hasHtmlBody()

      Returns true if the message contains HTML body.
      Returns:
        true if the message contains HTML body.
      See Also:
        `getHtmlBody()`

    - #### getType

          MessageType getType()

      Returns the message type.
      Returns:
        `MessageType` the message type.

    - #### getProviderType

          MessagingProviderType getProviderType()

      Returns a provider type for the message.
      Returns:
        `MessagingProviderType` the message type.

    - #### getStatus

          MessageStatus getStatus()

      Returns the message status.
      Returns:
        the message status.

    - #### getLastModifiedDate

          java.util.Date getLastModifiedDate()

      Returns the date and time that the message was last modified.
      Returns:
        the date and time that the message was last modified.

    - #### getReceivedDate

          java.util.Date getReceivedDate()

      Returns the date and time that the message was received.
      Returns:
        the date and time that the message was received.

    - #### isCoalesced

          @Deprecated
          boolean isCoalesced()

      Deprecated.
      THIS METHOD WILL BE REMOVED IN RELEASE VERSION 3.3.
      Returns the isCoalesced status of the message which is defining if two consecutive messages can be merged.

      Message is coalesced if:

      - There is a previous message
      - This and the previous message have both been published
      - This and the previous message are from the same participant
      - This and the previous message have no attachments
      - This and the previous message have the same sensitivity setting
      - This message was sent no longer than 1 minute after the previous message
      Returns:
        the isCoalesced status of the message which is defining if two consecutive messages can be merged.

    - #### isFromMe

          boolean isFromMe()

      Returns true if the current user is the sender of the message.
      Returns:
        true if the current user is the sender of the message.

    - #### hasAttachment

          boolean hasAttachment()

      Returns true if the message has one or more attachments.
      Returns:
        true if the message has one or more attachments.
      See Also:
        `getAttachments()`, `createAttachment()`, `removeAttachment(Attachment, MessagingCompletionHandler)`

    - #### hasUnreadAttachment

          boolean hasUnreadAttachment()

      Returns true if the message has a least one attachment that has not been viewed.
      Returns:
        true if the message has a least one attachment that has not been viewed.
      See Also:
        `getAttachments()`

    - #### isPrivate

          boolean isPrivate()

      Returns true if the message is marked as a private message.
      Returns:
        true if the message is marked as a private message.
      See Also:
        `getSensitivity()`

    - #### isDoNotForward

          boolean isDoNotForward()

      Returns the IsDoNotForward status of the message, which indicates if the sender of this message had disallowed forwarding of this particular message.
      Returns:
        true if the sender of this message had disallowed forwarding of this particular message.

    - #### isRead

          boolean isRead()

      Deprecated.
      use `getReadState()` method instead.
      Returns true if the message has been read.
      Returns:
        true if the message has been read.
      See Also:
        `markAsRead()`, `Conversation.markAllContentAsRead(MessagingCompletionHandler)`

    - #### getReadState

          MessageReadState getReadState()

      The message read state describing whether this message is read, partially read or not read.
      Returns:
        the message Read state.
      See Also:
        `MessageReadState`, `Conversation.getMessageReadStateCapability()`

    - #### getDeliveryState

          MessageDeliveryState getDeliveryState()

      The message delivery state describing whether this message is sent or delivered to one or more recipients. Delivery state will not update from Sent to Delivered in case MessageDeliveryReadStateMonitoring is disabled or not supported by messaging server.
      Returns:
        delivery state (eg. Unsent, Sent, Delivered).
      See Also:
        `MessageDeliveryState`, `Conversation.getMessageDeliveryStateCapability()`

    - #### getFromParticipant

          MessagingParticipant getFromParticipant()

      Returns the participant who was the sender of the message.
      Returns:
        `MessagingParticipant` who was the sender of the message.
      See Also:
        `getRecipients()`

    - #### getRecipients

          java.util.List<MessagingParticipant> getRecipients()

      Returns the list of participants, including the sender, that the message was sent to.

      Property of incoming message only.

      Returns:
        the list of `MessagingParticipant`, including the sender, that the message was sent to.
      See Also:
        `getFromParticipant()`, `isFromMe()`

    - #### getAddedParticipants

          java.util.List<MessagingParticipant> getAddedParticipants()

      When the message type is `MessageType.JOINED`, this property returns the list of participants that were added to the conversation.

      Property of incoming message only.

      Returns:
        when the message type is `MessageType.JOINED`, this property returns the list of participants that were added to the conversation.
      See Also:
        `getType()`

    - #### getRemovedParticipants

          java.util.List<MessagingParticipant> getRemovedParticipants()

      When the message type is `MessageType.LEFT`, this property returns the list of participants that were removed from the conversation. Property of incoming message only.
      Returns:
        when the message type is `MessageType.LEFT`, this property returns the list of participants that were removed from the conversation.
      See Also:
        `getType()`

    - #### getImportance

          MessageImportance getImportance()

      Returns the message importance.
      Returns:
        the message importance.

    - #### getInReplyTo

          void getInReplyTo​(MessageCompletionHandler completionHandler)

      Gets InReplyToMessage or error if message is not in cache. Message is returned via completion handler.
      Parameters:
        `completionHandler` - `MessageCompletionHandler` for this operation.
      See Also:
        `hasInReplyTo()`

    - #### hasInReplyTo

          boolean hasInReplyTo()

      Returns true if message has InReplyTo message (does not mean it is in cache).
      Returns:
        true if message has InReplyTo message (does not mean it is in cache).

    - #### getReason

          MessagingReasonType getReason()

      Returns the message reason type.

      Specific to Closed and Left message types.

      Reason interpretation for various message types
      | Closed message type | Left message type
      --- | --- | ---
      Manual | The conversation was closed by a participant. | Participant left on his own.
      Auto | The conversation was closed by the system(e.g. auto-closed after 30 days of inactivity). | There was some problem communicating with external user(user does not exist, or unavailable, or some other error). Such a leave reason should display an error message, like "[username] is unreachable/unable to join" rather than the regular "[username] left the conversation".

      Returns:
        the message reason type.

    - #### getSensitivity

          SensitivityLevel getSensitivity()

      Returns the message sensitivity.
      Returns:
        the message sensitivity.

    - #### getUpdateBodyCapability

          Capability getUpdateBodyCapability()

      Returns a `Capability` object that indicates if the body text or "is typing" status of the message can be updated.

      This capability is Allowed when the Message has not yet been sent, or a send failure has occurred.

      Returns:
        a `Capability` object that indicates if the body text or "is typing" status of the message can be updated.
      See Also:
        `setBodyAndReportTyping(String, MessagingCompletionHandler)`, `reportTyping(boolean)`

    - #### getUpdateInReplyToCapability

          Capability getUpdateInReplyToCapability()

      Returns a `Capability` object that indicates if the InReplyTo attribute of the message can be updated.

      This capability is Allowed when the Message has not yet been sent, or a send failure has occurred.

      Returns:
        a `Capability` object that indicates if the InReplyTo attribute of the message can be updated.
      See Also:
        `setInReplyTo(Message, MessagingCompletionHandler)`

    - #### getUpdateDoNotForwardCapability

          Capability getUpdateDoNotForwardCapability()

      Returns a `Capability` object that indicates if the DoNotForward attribute of the message can be updated.

      This capability is Allowed when the Message has not yet been sent, or a send failure has occurred.

      Returns:
        a `Capability` object that indicates if the DoNotForward attribute of the message can be updated.
      See Also:
        `setDoNotForward(boolean, MessagingCompletionHandler)`

    - #### getUpdateImportanceCapability

          Capability getUpdateImportanceCapability()

      Returns a `Capability` object that indicates if the Importance attribute of the message can be updated.

      This capability is Allowed when the Message has not yet been sent, or a send failure has occurred.

      Returns:
        a `Capability` object that indicates if the Importance attribute of the message can be updated.
      See Also:
        `setImportance(MessageImportance, MessagingCompletionHandler)`

    - #### getCreateAttachmentCapability

          Capability getCreateAttachmentCapability()

      Returns a `Capability` object that indicates if an attachment can be added to the message.

      This capability is Allowed when the Message has not yet been sent, or a send failure has occurred.

      Returns:
        a `Capability` object that indicates if an attachment can be added to the message.
      See Also:
        `createAttachment()`

    - #### getSendCapability

          Capability getSendCapability()

      Returns a `Capability` object that indicates if the message can be sent.

      This capability is Allowed when all of the following conditions are true:

      - The messaging service is online (has an active connection to the server).
      - The Message has not yet been sent, or a send failure has occurred.
      - The Message has no body text or the messaging server supports the sending of messages containing text.
      - The Message has body text whose length does not exceed the maximum text length set on the messaging server.
      - The Message has no attachments or the messaging server supports the sending of messages having attachments.
      - The Message has no "thumbnail" attachments or the messaging server supports the sending of messages having "thumbnail" attachments.
      Returns:
        a `Capability` object that indicates if the message can be sent.
      See Also:
        `send(MessagingCompletionHandler)`

    - #### getMarkAsReadCapability

          Capability getMarkAsReadCapability()

      Returns a `Capability` object that indicates if the message can be marked as read.

      This capability is Allowed when all of the following conditions are true:

      - The messaging service is online (has an active connection to the server).
      - The messaging server supports marking messages as read.
      - The Message is in the published state.
      Returns:
        a `Capability` object that indicates if the message can be marked as read.
      See Also:
        `markAsRead()`

    - #### getRemoveCapability

          Capability getRemoveCapability()

      Returns a `Capability` object that indicates if the message can be removed.

      This capability is Allowed when the Message has not yet been sent, or a send failure has occurred.

      Returns:
        a `Capability` object that indicates if the message can be removed.
      See Also:
        `Conversation.removeMessage(Message, MessagingCompletionHandler)`

    - #### getDeliveryDetailsCapability

          Capability getDeliveryDetailsCapability()

      Capability indicating whether the message can provide its delivery details.
      Returns:
        a `Capability` object that indicates whether the message can provide its delivery details.

    - #### send

          void send​(MessagingCompletionHandler completionHandler)

      Invokes a send request for this message.
      Parameters:
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getSendCapability()`

    - #### createAttachment

          Attachment createAttachment()

      Creates an `Attachment` for this message.
      Returns:
        a new `Attachment` object for this message that is in the draft state.
      See Also:
        `getCreateAttachmentCapability()`, `getAttachments()`, `removeAttachment(Attachment, MessagingCompletionHandler)`

    - #### getAttachments

          java.util.List<Attachment> getAttachments()

      Gets the list of attachments for this message.
      Returns:
        the list of attachments for this message.
      See Also:
        `createAttachment()`, `removeAttachment(Attachment, MessagingCompletionHandler)`

    - #### removeAttachment

          void removeAttachment​(Attachment attachment,
                                MessagingCompletionHandler completionHandler)

      Remove a specified attachment from this message.
      Parameters:
        `attachment` - the `Attachment` to remove from the message.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getAttachments()`, `createAttachment()`

    - #### setBodyAndReportTyping

          int setBodyAndReportTyping​(java.lang.String body,
                                     MessagingCompletionHandler completionHandler)

      Sets the body of the draft message and the "is typing" chat state.

      Client application having HTML capability can set body with text in HTML format. If the application doesn't want to repeatedly call this method with new body text just to report that the user is typing, it can use the `reportTyping(boolean)` method to do so.

      Parameters:
        `body` - the new message body text to set. A client application that supports HTML message text can set body with text in HTML format.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      Returns:
        the remaining number of characters that can be added to the message body text (compared with the limit).
      See Also:
        `reportTyping(boolean)`, `getUpdateBodyCapability()`, `getBody()`, `MessageListener.onMessageBodyChanged(Message, String)`

    - #### reportTyping

          void reportTyping​(boolean isTyping)

      Set or clear the "is typing" chat state. This is a "fire and forget" operation.

      The application should call this method with a value of false when the "is typing" chat state should be cleared. For instance, when the user leaves the conversation window to do some other work.

      Parameters:
        `isTyping` - true to indicate that the user is typing, false if not.
      See Also:
        `setBodyAndReportTyping(String, MessagingCompletionHandler)`, `getUpdateBodyCapability()`

    - #### setImportance

          void setImportance​(MessageImportance importance,
                             MessagingCompletionHandler completionHandler)

      Sets a new message importance.
      Parameters:
        `importance` - the new message importance setting.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getUpdateImportanceCapability()`, `getImportance()`

    - #### setInReplyTo

          void setInReplyTo​(Message message,
                            MessagingCompletionHandler completionHandler)

      Sets the message that the current message is a direct reply to.
      Parameters:
        `message` - the message that is being replied to by the current message.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getUpdateInReplyToCapability()`, `hasInReplyTo()`, `getInReplyTo(MessageCompletionHandler)`

    - #### setDoNotForward

          void setDoNotForward​(boolean state,
                               MessagingCompletionHandler completionHandler)

      Sets a new message "do not forward" state.
      Parameters:
        `state` - the new "do not forward" state for the message.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getUpdateDoNotForwardCapability()`, `isDoNotForward()`

    - #### markAsRead

          void markAsRead()

      Marks the message as read.
      See Also:
        `getMarkAsReadCapability()`, `isRead()`

    - #### getDeliveryDetails

          void getDeliveryDetails​(MessageDeliveryDetailsCompletionHandler completionHandler)

      Gets MessageDeliveryDetails or error. Delivery details are returned via completion handler.
      Parameters:
        `completionHandler` - `MessageDeliveryDetailsCompletionHandler` for this operation.

    - #### getInitiatorParticipant

          MessagingParticipant getInitiatorParticipant()

      Get initiator participant of an event message, such as LEFT message when a participant is removed from conversation by other participant(initiator)
      Returns:
        `MessagingParticipant` the participant who was an initiator of the removing.