Interface ChatRoom


public interface ChatRoom
A chat room is the place where ChatMessage are exchanged.

To create (or find) a ChatRoom, you first need a ChatRoomParams
object. A chat room is uniquely identified by it's local and remote SIP
addresses, meaning you can only have one chat room between two accounts (unless
the backend is ChatRoom.Backend.FlexisipChat). Then you can call Core.searchChatRoom(org.linphone.core.ChatRoomParams, org.linphone.core.Address, org.linphone.core.Address, org.linphone.core.Address[])
or Core.createChatRoom(org.linphone.core.ChatRoomParams, org.linphone.core.Address, org.linphone.core.Address[]).
Be careful as a ChatRoom.Backend.FlexisipChat backend ChatRoom will be
created asynchronously, so make sure you add a ChatRoomListener to the
returned object to be notified when it will be in state ChatRoom.State.Created.
All chat rooms are loaded from database when the Core starts, and you
can get them using Core.getChatRooms(). This method doesn't return empty
chat rooms nor ones for which the local address doesn't match an existing
ProxyConfig identity, unless you specify otherwise in the [misc]
section of your configuration file by setting hide_empty_chat_rooms=0 and/or
hide_chat_rooms_from_removed_proxies=0.
  • Method Details

    • getCall

      @Nullable Call getCall()
      Gets the current call associated to this chatroom if any To commit a message,
      use ChatMessage.send()

      Returns:
      Call or null.
    • getCapabilities

      int getCapabilities()
      Get the capabilities of a chat room.

      Returns:
      The capabilities of the chat room (as a
      LinphoneChatRoomCapabilitiesMask)
    • getChar

      int getChar()
      When realtime text is enabled CallParams#realtimeTextEnabled,
      LinphoneCoreIsComposingReceivedCb is call everytime a char is received from
      peer.

      At the end of remote typing a regular ChatMessage is received with
      committed data from LinphoneCoreCbsMessageReceivedCb.
      Returns:
      RFC 4103/T.140 char
    • getComposingAddresses

      @NonNull Address[] getComposingAddresses()
      Gets the list of participants that are currently composing.

      Returns:
      List of addresses that are in the is_composing state.
    • getConferenceAddress

      @Nullable Address getConferenceAddress()
      Get the conference address of the chat room.

      Returns:
      The conference address of the chat room or null if this type of chat
      room is not conference based.
    • setConferenceAddress

      void setConferenceAddress(@Nullable Address conferenceAddress)
      Set the conference address of a group chat room.

      This function needs to be called from the
      LinphoneChatRoomCbsConferenceAddressGenerationCb callback and only there. This
      function is meaningful only for server implementation of chatroom, and shall
      not by used by client applications.
      Parameters:
      conferenceAddress - The conference Address to be used by the group
      chat room
    • getCore

      @NonNull Core getCore()
      Returns back pointer to Core object.

      Returns:
      the Core object this chat room is attached to.
    • getCreationTime

      long getCreationTime()
      Return the creation time for the chat room.

      Returns:
      the time at which the chat room was created
    • getCurrentParams

      @NonNull ChatRoomParams getCurrentParams()
      Returns current parameters associated with the chat room.

      This is typically the parameters passed at chat room chat_roomeation to
      linphone_core_chat_roomeate_chat_room() or some default parameters if no ChatRoomParams
      was explicitely passed during chat room chat_roomeation.
      Returns:
      the current ChatRoomParams parameters.
    • isEphemeralEnabled

      boolean isEphemeralEnabled()
      Returns whether or not the ephemeral message feature is enabled in the chat
      room.

      Returns:
      true if ephemeral is enabled, false otherwise.
    • setEphemeralEnabled

      void setEphemeralEnabled(boolean enable)
      Enable or disable the ephemeral message feature in the chat room.

      Works only for flexisip-based chat room. An ephemeral message will
      automatically disappear from the sender and recipient's chatrooms after a
      specified timeout configurable with setEphemeralLifetime(long). The timer
      starts when the message has been displayed at the recipent, which means:
      Parameters:
      enable - true if the ephemeral message feature is enabled, false
      otherwise.
    • getEphemeralLifetime

      long getEphemeralLifetime()
      Get lifetime (in seconds) for all new ephemeral messages in the chat room.

      After the message is read, it will be deleted after "time" seconds. see: #ephemeralEnabled
      Returns:
      the ephemeral lifetime (in secoonds)
    • setEphemeralLifetime

      void setEphemeralLifetime(long time)
      Set lifetime (in seconds) for all new ephemeral messages in the chat room.

      After the message is read, it will be deleted after "time" seconds. see: #ephemeralEnabled
      Parameters:
      time - The ephemeral lifetime, default is 0 (disabled)
      warning: A value of "time" equal to 0 disables ephemeral messages
    • getEphemeralMode

      ChatRoom.EphemeralMode getEphemeralMode()
      Get the ephemeral mode of the chat room.

      see: #ephemeralEnabled
      Returns:
      the ephemeral mode ChatRoom.EphemeralMode
    • setEphemeralMode

      void setEphemeralMode(ChatRoom.EphemeralMode mode)
      Set the ephemeral mode of the chat room.

      see: #ephemeralEnabled
      Parameters:
      mode - The ephemeral mode ChatRoom.EphemeralMode
      warning: This function only changes the mode of ephemeral messages ChatRoom.EphemeralMode
      . It is required to manually enable ephemeral messages after setting the mode
      by calling #enableEphemeral
    • getHistoryEventsSize

      int getHistoryEventsSize()
      Gets the number of events in a chat room.

      Returns:
      the number of events.
    • getHistorySize

      int getHistorySize()
      Gets the number of messages in a chat room.

      Returns:
      the number of messages.
    • isEmpty

      boolean isEmpty()
      Returns whether or not a ChatRoom has at least one ChatMessage
      or not.

      Returns:
      true if there are no ChatMessage, false otherwise.
    • isReadOnly

      boolean isReadOnly()
      Return whether or not a message can be sent using this chat room.

      A chat room may be read only until it's created, or when it's a group you have
      left.
      Returns:
      true if a chat message can't be sent in it, false otherwise.
    • isRemoteComposing

      boolean isRemoteComposing()
      Tells whether the remote is currently composing a message.

      Returns:
      true if the remote is currently composing a message, false otherwise.
    • getLastMessageInHistory

      @Nullable ChatMessage getLastMessageInHistory()
      Gets the last chat message sent or received in this chat room.

      Returns:
      the latest ChatMessage or null if no message.
    • getLastUpdateTime

      long getLastUpdateTime()
      Return the last updated time for the chat room.

      Returns:
      the last updated time
    • getLocalAddress

      @NonNull Address getLocalAddress()
      Get the local address associated to this chat room.

      Returns:
      The local address.
    • getMe

      @Nullable Participant getMe()
      Get the participant representing myself in the chat room.

      Returns:
      The participant representing myself in the conference or null if me is
      not set.
    • getMuted

      boolean getMuted()
      Gets if a chat room has been flagged as muted (not by default).

      A muted chat room isn't used to compute unread messages total count.
      Returns:
      true if the chat room is muted, false otherwise.
    • setMuted

      void setMuted(boolean muted)
      Sets if a chat room should be considered as muted or not.

      A muted chat room isn't used to compute unread messages total count.
      Parameters:
      muted - true to flag it as muted, false to un-mute it.
    • getNbParticipants

      int getNbParticipants()
      Get the number of participants in the chat room (that is without ourselves).

      Returns:
      The number of participants in the chat room
    • getParticipants

      @NonNull Participant[] getParticipants()
      Get the list of participants of a chat room.

      Returns:
      A of the participants
    • getPeerAddress

      @NonNull Address getPeerAddress()
      Get the peer address associated to this chat room.

      Returns:
      The peer address.
    • getSecurityLevel

      ChatRoom.SecurityLevel getSecurityLevel()
      Get the security level of a chat room.

      Returns:
      The current ChatRoom.SecurityLevel of the chat room
    • getState

      ChatRoom.State getState()
      Get the state of the chat room.

      Returns:
      The current ChatRoom.State of the chat room
    • getSubject

      @Nullable String getSubject()
      Get the subject of a chat room.

      Returns:
      The subject of the chat room.
    • setSubject

      void setSubject(@Nullable String subject)
      Set the subject of a chat room.

      Parameters:
      subject - The new subject to set for the chat room
    • getUnreadHistory

      @NonNull ChatMessage[] getUnreadHistory()
      Gets all unread messages for this chat room, sorted from oldest to most recent.

      Returns:
      A list of unread chat messages.
    • getUnreadMessagesCount

      int getUnreadMessagesCount()
      Gets the number of unread messages in the chatroom.

      Returns:
      the number of unread messages.
    • addParticipant

      void addParticipant(@NonNull Address addr)
      Add a participant to a chat room.

      This may fail if this type of chat room does not handle participants. Use
      canHandleParticipants() to know if this chat room handles participants.
      Parameters:
      addr - The address of the participant to add to the chat room
    • addParticipants

      boolean addParticipants(@NonNull Address[] addresses)
      Add several participants to a chat room at once.

      This may fail if this type of chat room does not handle participants. Use
      canHandleParticipants() to know if this chat room handles participants.
      Parameters:
      addresses - The participants to add.
      Returns:
      true if everything is OK, false otherwise
    • allowCpim

      void allowCpim()
      Allow cpim on a basic chat room .

    • allowMultipart

      void allowMultipart()
      Allow multipart on a basic chat room .

    • canHandleParticipants

      boolean canHandleParticipants()
      Tells whether a chat room is able to handle participants.

      Returns:
      true if the chat room can handle participants, false otherwise
    • compose

      void compose()
      Notifies the destination of the chat message being composed that the user is
      typing a new message.

    • createEmptyMessage

      @NonNull ChatMessage createEmptyMessage()
      Creates an empty message attached to the given chat room.

      Returns:
      a new ChatMessage
    • createFileTransferMessage

      @NonNull ChatMessage createFileTransferMessage(@NonNull Content initialContent)
      Creates a message attached to the given chat room with a particular content.

      Use ChatMessage.send() to initiate the transfer
      Parameters:
      initialContent - Content initial content.
      Returns:
      a new ChatMessage
    • createForwardMessage

      @NonNull ChatMessage createForwardMessage(@NonNull ChatMessage message)
      Creates a forward message attached to the given chat room with a particular
      message.

      Parameters:
      message - ChatMessage message to be forwarded.
      Returns:
      a new ChatMessage
    • createMessage

      @Deprecated @NonNull ChatMessage createMessage(@Nullable String message)
      Deprecated.
      01/07/2020. Use createMessageFromUtf8(java.lang.String) instead.
      Creates a message attached to the given chat room with a plain text content
      filled with the given message.

      Parameters:
      message - text message, null if absent.
      Returns:
      a new ChatMessage
    • createMessageFromUtf8

      @NonNull ChatMessage createMessageFromUtf8(@Nullable String message)
      Creates a message attached to the given chat room with a plain text content
      filled with the given message.

      Introduced in 01/07/2020
      Parameters:
      message - text message in UTF8, null if absent.
      Returns:
      a new ChatMessage
    • createReplyMessage

      @NonNull ChatMessage createReplyMessage(@NonNull ChatMessage message)
      Creates a reply message attached to the given chat room with a particular
      message.

      Parameters:
      message - ChatMessage message to reply to.
      Returns:
      a new ChatMessage
    • createVoiceRecordingMessage

      @NonNull ChatMessage createVoiceRecordingMessage(@NonNull Recorder recorder)
      Creates a chat message with a voice recording attached to the given chat room.

      warning: If the recorder isn't in Closed state, it will return an empty
      message!
      Parameters:
      recorder - the Recorder object used to record the voice message.
      Returns:
      a new ChatMessage
    • deleteHistory

      void deleteHistory()
      Delete all messages from the history.

    • deleteMessage

      void deleteMessage(@NonNull ChatMessage message)
      Delete a message from the chat room history.

      Parameters:
      message - The ChatMessage object to remove.
    • ephemeralSupportedByAllParticipants

      boolean ephemeralSupportedByAllParticipants()
      Uses linphone spec to check if all participants support ephemeral messages.

      It doesn't prevent to send ephemeral messages in the room but those who don't
      support it won't delete messages after lifetime has expired. see: #ephemeralEnabled
      Returns:
      true if all participants in the chat room support ephemeral messages,
      false otherwise
    • findMessage

      @Nullable ChatMessage findMessage(@NonNull String messageId)
      Gets the chat message sent or received in this chat room that matches the
      message_id.

      Parameters:
      messageId - The id of the message to find
      Returns:
      the ChatMessage if found or null.
    • findParticipant

      @Nullable Participant findParticipant(@NonNull Address address)
      Find a participant of a chat room from its address.

      Parameters:
      address - The Address to search in the list of participants of the
      chat room
      Returns:
      The participant if found, null otherwise.
    • getHistory

      @NonNull ChatMessage[] getHistory(int nbMessage)
      Gets nb_message most recent messages from chat_room chat room, sorted from
      oldest to most recent.

      Parameters:
      nbMessage - Number of message to retrieve. 0 means everything.
      Returns:
      A list of chat messages.
    • getHistoryEvents

      @NonNull EventLog[] getHistoryEvents(int nbEvents)
      Gets nb_events most recent events from chat_room chat room, sorted from oldest
      to most recent.

      Parameters:
      nbEvents - Number of events to retrieve. 0 means everything.
      Returns:
      The list of the most recent events.
    • getHistoryMessageEvents

      @NonNull EventLog[] getHistoryMessageEvents(int nbEvents)
      Gets nb_events most recent chat message events from chat_room chat room, sorted
      from oldest to most recent.

      Parameters:
      nbEvents - Number of events to retrieve. 0 means everything.
      Returns:
      A list
    • getHistoryRange

      @NonNull ChatMessage[] getHistoryRange(int begin, int end)
      Gets the partial list of messages in the given range, sorted from oldest to
      most recent.

      Parameters:
      begin - The first message of the range to be retrieved. History most
      recent message has index 0.
      end - The last message of the range to be retrieved. History oldest
      message has index of history size - 1 (use getHistorySize() to retrieve
      history size)
      Returns:
      A list of chat messages.
    • getHistoryRangeEvents

      @NonNull EventLog[] getHistoryRangeEvents(int begin, int end)
      Gets the partial list of events in the given range, sorted from oldest to most
      recent.

      Parameters:
      begin - The first event of the range to be retrieved. History most recent
      event has index 0.
      end - The last event of the range to be retrieved. History oldest event
      has index of history size - 1
      Returns:
      The list of the found events.
    • getHistoryRangeMessageEvents

      @NonNull EventLog[] getHistoryRangeMessageEvents(int begin, int end)
      Gets the partial list of chat message events in the given range, sorted from
      oldest to most recent.

      Parameters:
      begin - The first event of the range to be retrieved. History most recent
      event has index 0.
      end - The last event of the range to be retrieved. History oldest event
      has index of history size - 1
      Returns:
      The list of chat message events.
    • hasBeenLeft

      @Deprecated boolean hasBeenLeft()
      Deprecated.
      16/03/2022 use isReadOnly() instead.
      Return whether or not the chat room has been left.

      Returns:
      true if the chat room has been left, false otherwise.
    • hasCapability

      boolean hasCapability(int mask)
      Check if a chat room has given capabilities.

      Parameters:
      mask - a LinphoneChatRoomCapabilitiesMask mask
      Returns:
      true if the mask matches, false otherwise
    • leave

      void leave()
      Leave a chat room.

    • markAsRead

      void markAsRead()
      Mark all messages of the conversation as read.

    • notifyParticipantDeviceRegistration

      void notifyParticipantDeviceRegistration(@NonNull Address participantDevice)
      Notify the chatroom that a participant device has just registered.

      This function is meaningful only for server implementation of chatroom, and
      shall not by used by client applications.
      Parameters:
      participantDevice - list of the participant devices to be used by the
      group chat room
    • receiveChatMessage

      void receiveChatMessage(@NonNull ChatMessage message)
      Used to receive a chat message when using async mechanism with IM
      enchat_roomyption engine.

      Parameters:
      message - ChatMessage object
    • removeParticipant

      void removeParticipant(@NonNull Participant participant)
      Remove a participant of a chat room.

      Parameters:
      participant - The participant to remove from the chat room
    • removeParticipants

      void removeParticipants(@NonNull Participant[] participants)
      Remove several participants of a chat room at once.

      Parameters:
      participants - The participants to remove.
    • setParticipantAdminStatus

      void setParticipantAdminStatus(@NonNull Participant participant, boolean isAdmin)
      Change the admin status of a participant of a chat room (you need to be an
      admin yourself to do this).

      Parameters:
      participant - The Participant for which to change the admin status
      isAdmin - A boolean value telling whether the participant should now be an
      admin or not
    • setParticipantDevices

      void setParticipantDevices(@NonNull Address participantAddress, @NonNull ParticipantDeviceIdentity[] deviceIdentities)
      Set the list of participant devices in the form of SIP URIs with GRUUs for a
      given participant.

      This function is meaningful only for server implementation of chatroom, and
      shall not by used by client applications.
      Parameters:
      participantAddress - The participant address
      deviceIdentities - List of the participant devices to be used by the group
      chat room
    • stateToString

      @NonNull String stateToString(ChatRoom.State state)
      Converts a ChatRoom.State enum to a string.

      Parameters:
      state - a ChatRoom.State to convert to string
      Returns:
      the string representation of the ChatRoom.State
    • addListener

      void addListener(ChatRoomListener listener)
    • removeListener

      void removeListener(ChatRoomListener listener)
    • setUserData

      void setUserData(Object data)
      Sets the object to store in this object user's data
      Parameters:
      data - the object to store
    • getUserData

      Object getUserData()
      Gets the object stored in this object user's data
      Returns:
      the object store if any, null otherwise
    • getNativePointer

      long getNativePointer()
      Gets the native pointer used by this class to make native method calls.
      Returns:
      the nativer pointer, as long
    • toString

      String toString()
      Overrides:
      toString in class Object