Package org.linphone.core

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.ConferenceParams, 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
Account 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

    • getAccount

      @Nullable Account getAccount()
      Returns the local account to which this chat room is related.

      Returns:
      the related Account object if any, null otherwise.

    • 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()
      Gets the capabilities of a chat room.

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

    • getChar

      int getChar()
      When realtime text is enabled in a Call (see CallParams#realtimeTextEnabled
      ), LinphoneCoreIsComposingReceivedCb is called everytime a Real-Time Text
      character is received from peer.

      getChar() pops a character previously received from the receive queue,
      and returns it. When a new line character is received, a ChatMessage is
      automatically created with received characters and notified to the application
      through the CoreListener or ChatRoomListener interfaces.
      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()
      Gets 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)
      Sets 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

    • getConferenceInfo

      @Nullable ConferenceInfo getConferenceInfo()
      Gets the conference information associated to the chatroom.

      Returns:
      the ConferenceInfo.

    • getCore

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

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

    • getCreationTime

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

      Returns:
      the time at which the chat room was created

    • getCurrentParams

      @Deprecated @NonNull ChatRoomParams getCurrentParams()
      Deprecated.
      17/07/2025. Use getParams() instead.
      Returns current parameters associated with the chat room.

      This is typically the parameters passed during the ChatRoom creation
      process to linphone_core_chat_room_create_chat_room() or some default
      parameters if no ChatRoomParams was explicitely passed during ChatRoom
      creation.
      Returns:
      the current ChatRoomParams parameters.

    • getDocumentContents

      @NonNull Content[] getDocumentContents()
      Gets all contents for which content-type starts with either text/ or
      application/.

      Returns:
      A list of contents considered as "document".

    • 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()
      Gets 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)
      Sets 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()
      Gets the ephemeral mode of the chat room.

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

    • setEphemeralMode

      void setEphemeralMode(ChatRoom.EphemeralMode mode)
      Sets 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

      @Deprecated int getHistorySize()
      Deprecated.
      30/07/2024. Use getHistorySize() instead.
      Gets the number of messages in a chat room.

      Returns:
      the number of messages.

    • getIdentifier

      @Nullable String getIdentifier()
      Returns the chat room identifier.

      warning: This method returns a null pointer if the ChatRoom is in the
      Instantiated state
      Returns:
      the conference identifier.

    • 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()
      Returns 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()
      Returns 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.

      warning: This method returns a guessed address based on the me participant if
      the ChatRoom is in the Instantiated state
      Returns:
      The local address.

    • getMe

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

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

    • getMediaContents

      @NonNull Content[] getMediaContents()
      Gets all contents for which content-type starts with either video/, audio/ or
      image/.

      Returns:
      A list of contents considered as "media".

    • 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()
      Gets the number of participants in the chat room (that is without ourselves).

      Returns:
      The number of participants in the chat room

    • getParams

      @NonNull ConferenceParams getParams()
      Returns current parameters associated with the chat room.

      This is typically the parameters passed during the ChatRoom creation
      process to linphone_core_chat_room_create_chat_room() or some default
      parameters if no ChatRoomParams was explicitely passed during ChatRoom
      creation.
      Returns:
      the current ChatRoomParams parameters.

    • getParticipants

      @NonNull Participant[] getParticipants()
      Gets 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.

      warning: This method returns an invalid address if the ChatRoom is in the
      Instantiated state
      Returns:
      The peer address.

    • getSecurityLevel

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

      Returns:
      The current ChatRoom.SecurityLevel of the chat room

    • getState

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

      Returns:
      The current ChatRoom.State of the chat room

    • getSubject

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

      Returns:
      The subject of the chat room.

    • setSubject

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

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

    • getSubjectUtf8

      @Nullable String getSubjectUtf8()
      Gets the subject of a chat room (as an UTF8 string)

      Returns:
      The subject of the chat room.

    • setSubjectUtf8

      void setSubjectUtf8(@Nullable String subject)
      Sets the subject of a chat room (utf-8 string).

      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)
      Adds 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)
      Adds 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()
      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. The check is done
      by verifying the participant's advertised capabilities (+org.linphone.specs
      parameter). see: #ephemeralEnabled
      Returns:
      true if all participants in the chat room support ephemeral messages,
      false otherwise

    • findEventLog

      @Nullable EventLog findEventLog(@NonNull String messageId)
      Gets the event log sent or received in this chat room that matches a chat
      message with the given message_id.

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

    • 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)
      Finds 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 EventLog[] getHistory(int nbMessage, int filters)
      Gets nb_message most recent events from chat_room chat room, sorted from oldest
      to most recent.

      Parameters:
      nbMessage - Number of events to retrieve. 0 means everything.
      filters - The LinphoneChatRoomHistoryFilterMask mask to filter the results
      with ChatRoom.HistoryFilter
      Returns:
      A list of

    • getHistory

      @Deprecated @NonNull ChatMessage[] getHistory(int nbMessage)
      Deprecated.
      30/07/2024. Use getHistory(int, int) instead.
      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

    • 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 EventLog[] getHistoryRange(int begin, int end, int filters)
      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
      message has index 0.
      end - The last event 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

    • getHistoryRange

      @Deprecated @NonNull ChatMessage[] getHistoryRange(int begin, int end)
      Deprecated.
      30/07/2024. Use getHistoryRange(int, int, int) instead.
      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.

    • getHistoryRangeBetween

      @NonNull EventLog[] getHistoryRangeBetween(@Nullable EventLog firstEvent, @Nullable EventLog lastEvent, int filters)
      Gets the partial list of messages between two given EventLog, sorted
      from oldest to most recent.

      If either first_event or last_event is null, then nothing is returned.
      Parameters:
      firstEvent - The EventLog object corresponding to the event.
      lastEvent - The EventLog object corresponding to the event.
      filters - The LinphoneChatRoomHistoryFilterMask mask to filter the results
      with ChatRoom.HistoryFilter
      Returns:
      A list of between the two provided events, if any.

    • 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.

    • getHistoryRangeNear

      @NonNull EventLog[] getHistoryRangeNear(int before, int after, @Nullable EventLog event, int filters)
      Gets the partial list of messages in the given range near the EventLog
      provided, sorted from oldest to most recent.

      If before and after are both set to 0, the returned list is empty.
      Parameters:
      before - The number of messages to retrieve before the event provided.
      after - The number of messages to retrieve after the event provided.
      event - The EventLog object corresponding to the event.
      filters - The LinphoneChatRoomHistoryFilterMask mask to filter the results
      with ChatRoom.HistoryFilter
      Returns:
      A list of near the event provided included.

    • getHistorySize

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

      Parameters:
      filters - The LinphoneChatRoomHistoryFilterMask mask to filter the result
      with ChatRoom.HistoryFilter
      Returns:
      the number of messages.

    • hasBeenLeft

      @Deprecated boolean hasBeenLeft()
      Deprecated.
      16/03/2022 use isReadOnly() instead.
      Returns 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)
      Checks if a chat room has given capabilities.

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

    • leave

      void leave()
      Leaves a chat room.

    • markAsRead

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

    • notifyParticipantDeviceRegistration

      void notifyParticipantDeviceRegistration(@NonNull Address participantDevice)
      Notifies 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)
      Removes a participant of a chat room.

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

    • removeParticipants

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

      Parameters:
      participants - The participants to remove.

    • searchChatMessageByText

      @Nullable EventLog searchChatMessageByText(@NonNull String text, @Nullable EventLog from, SearchDirection direction)
      Searches chat messages by text.

      Parameters:
      text - The text to search in messages
      from - The EventLog object corresponding to the event where to
      start the search
      direction - The SearchDirection where to search,
      LinphoneSearchDirectionUp will search older messages while
      LinphoneSearchDirectionDown will search newer messages
      Returns:
      the EventLog corresponding to the message if found or null.

    • setParticipantAdminStatus

      void setParticipantAdminStatus(@NonNull Participant participant, boolean isAdmin)
      Changes 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)
      Sets 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