Package org.linphone.core

# Interface ChatMessage

public interface ChatMessage
A `ChatMessage` represents an instant message that can be send or
received through a `ChatRoom`.
To create a `ChatMessage`, use `ChatRoom.createEmptyMessage()`, then
either add text using `addUtf8TextContent(java.lang.String)` or a `Content` with
file informations using `addFileContent(org.linphone.core.Content)`. A valid `Content` for
file transfer must contain a type and subtype, the name of the file and it's
size. Finally call `send()` to send it.
To send files through a `ChatMessage`, you need to have configured a file
transfer server URL with `Core.setFileTransferServer(java.lang.String)`. On the receiving
side, either use `downloadContent(org.linphone.core.Content)` to download received files or enable
auto-download in the `Core` using `Core.setMaxSizeForAutoDownloadIncomingFiles(int)`
, -1 disabling the feature and 0 always downloading files no matter it's size.
Keep in mind a `ChatMessage` created by a {@link ChatRoom#Backend#Basic}
`ChatRoom` can only contain one `Content`, either text or file.

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static enum`
`ChatMessage.Direction`
`static enum`
`ChatMessage.State`

## Method Summary

Modifier and Type
Method
Description
`void`
`addCallLogContent(CallLog callLog)`
Adds a call log content to the ChatMessage.
`void`
`addContent(Content content)`
Adds a content to the ChatMessage.
`void`
`addCustomHeader(String headerName, String headerValue)`
Adds custom headers to the message.
`void`
`addFileContent(Content content)`
Adds a file content to the ChatMessage.
`void`
`addListener(ChatMessageListener listener)`
`void`
`addTextContent(String text)`
Deprecated.
`void`
`addUtf8TextContent(String text)`
Creates a `Content` of type text/plain with the provided string, and
attach it to the message.
`void`
`cancelFileTransfer()`
Cancels an ongoing file transfer attached to this message (upload or download).
`ChatMessageReaction`
`createReaction(String utf8Reaction)`
Creates a emoji reaction for the given chat mesage.
`boolean`
`downloadContent(Content content)`
Starts the download of the `Content` referenced in the `ChatMessage`
from remote server.
`boolean`
`downloadContents()`
Starts the download of all the `Content` objects representing file
transfers included in the message (`Content.isFileTransfer()` method
returns true).
`String`
`getAppdata()`
Linphone message has an app-specific field that can store a text.
`String`
`getCallId()`
Gets the SIP call-id accociated with the message.
`ChatRoom`
`getChatRoom()`
Returns the chatroom this message belongs to.
`Content[]`
`getContents()`
Returns the list of contents in the message.
`String`
`getContentType()`
Gets the content type of a chat message.
`Core`
`getCore()`
Returns back pointer to `Core` object.
`String`
`getCustomHeader(String headerName)`
Retrieves a custom header value given its name.
`long`
`getEphemeralExpireTime()`
Returns the real time at which an ephemeral message expires and will be
deleted.
`long`
`getEphemeralLifetime()`
Returns lifetime of an ephemeral message.
`ErrorInfo`
`getErrorInfo()`
Gets full details about delivery error of a chat message.
`EventLog`
`getEventLog()`
Returns the event log associated to the chat message.
`String`
`getExternalBodyUrl()`
Messages can carry external body as defined by rfc2017.
`Content`
`getFileTransferInformation()`
Gets the file transfer information (used by callbacks to recover informations
during a rcs file transfer)
`String`
`getForwardInfo()`
Gets the forward info if available as a string.
`Address`
`getFromAddress()`
Gets origin of the message.
`Address`
`getLocalAddress()`
Returns the local address the message was sent or received with.
`String`
`getMessageId()`
Get the message identifier.
`long`
`getNativePointer()`
Gets the native pointer used by this class to make native method calls.
`ChatMessageReaction`
`getOwnReaction()`
Returns our own reaction for a given chat message, if any.
`ParticipantImdnState[]`
`getParticipantsByImdnState(ChatMessage.State state)`
Gets the list of participants for which the imdn state has reached the
specified state and the time at which they did.
`Address`
`getPeerAddress()`
Returns the peer (remote) address of the message.
`ChatMessageReaction[]`
`getReactions()`
Gets the list of reactions received for this chat message.
`ChatMessage`
`getReplyMessage()`
Returns the `ChatMessage` this message is a reply to.
`String`
`getReplyMessageId()`
Returns the ID of the message this is a reply to.
`Address`
`getReplyMessageSenderAddress()`
Returns the address of the sender of the message this is a reply to.
`ChatMessage.State`
`getState()`
Gets the state of the message.
`String`
`getTextContent()`
Deprecated.
`long`
`getTime()`
Gets the time the message was sent.
`Address`
`getToAddress()`
Gets destination of the message.
`boolean`
`getToBeStored()`
Gets if a chat message is to be stored.
`Object`
`getUserData()`
Gets the object stored in this object user's data
`String`
`getUtf8Text()`
Gets text part of this message.
`boolean`
`hasCallLogJsonContent()`
Indicates whether the chat message contains a call log in JSON format.
`boolean`
`hasConferenceInvitationContent()`
Returns whether the chat message has a conference invitation content or not.
`boolean`
`hasTextContent()`
Deprecated.
`boolean`
`isEditable()`
Returns whether this message can be edited (maximum allowed time to edit it was
reached or not).
`boolean`
`isEdited()`
Returns whether this message has been edited by it's sender after it was sent.
`boolean`
`isEphemeral()`
Returns whether the chat message is an ephemeral message or not.
`boolean`
`isFileTransfer()`
Deprecated.
`boolean`
`isFileTransferInProgress()`
Gets whether or not a file is currently being downloaded or uploaded.
`boolean`
`isForward()`
Returns whether the chat message is a forward message or not.
`boolean`
`isOutgoing()`
Returns wehther the message has been sent or received.
`boolean`
`isRead()`
Returns whether the message has been read or not.
`boolean`
`isReply()`
Returns whether the chat message is a reply message or not.
`boolean`
`isRetractable()`
Returns whether this message can be retracted (maximum allowed time to retract
it was reached or not).
`boolean`
`isRetracted()`
Returns whether this message has been retracted by it's sender after it was
sent.
`boolean`
`isSecured()`
Gets if the message was end-to-end encrypted when transferred.
`boolean`
`isText()`
Deprecated.
`void`
`markAsRead()`
Marks the message as read.
`int`
`putChar(int character)`
Fulfills a chat message character by character and send the character
immediately as real-time text (RFC4103 / T.140) or as Baudot tones.
`void`
`removeContent(Content content)`
Removes a content from the ChatMessage.
`void`
`removeCustomHeader(String headerName)`
Removes a custom header from the message.
`void`
`removeListener(ChatMessageListener listener)`
`void`
`send()`
Sends a chat message.
`void`
`setAppdata(String data)`
Linphone message has an app-specific field that can store a text.
`void`
`setContentType(String contentType)`
Sets the content type of a chat message.
`void`
`setExternalBodyUrl(String externalBodyUrl)`
Messages can carry external body as defined by rfc2017.
`void`
`setToBeStored(boolean toBeStored)`
Sets if a chat message is to be stored.
`void`
`setUserData(Object data)`
Sets the object to store in this object user's data
`int`
`setUtf8Text(String text)`
Sets a text to be sent, given as a string of UTF-8 characters.
`String`
`toString()`

## Method Details

### getAppdata

@Nullable String getAppdata()
Linphone message has an app-specific field that can store a text.
The application might want to use it for keeping data over restarts, like
thumbnail image path.

Returns:
  the application-specific data or null if none has been stored.

### setAppdata

void setAppdata(@Nullable String data)
Linphone message has an app-specific field that can store a text.
The application might want to use it for keeping data over restarts, like
thumbnail image path.
Invoking this function will attempt to update the message storage to reflect
the change if it is enabled.

Parameters:
  `data` - the data to store into the message.

### getCallId

@NonNull String getCallId()
Gets the SIP call-id accociated with the message.

Returns:
  the call-id

### getChatRoom

@NonNull ChatRoom getChatRoom()
Returns the chatroom this message belongs to.

Returns:
  the `ChatRoom` in which this message has been sent or received.

### getContentType

@NonNull String getContentType()
Gets the content type of a chat message.

Returns:
  The content type of the chat message

### setContentType

void setContentType(@NonNull String contentType)
Sets the content type of a chat message.
This content type must match a content that is text representable, such as
text/plain, text/html or image/svg+xml.

Parameters:
  `contentType` - The new content type of the chat message

### getContents

@NonNull Content[] getContents()
Returns the list of contents in the message.

Returns:
  The list of `Content`.

### getCore

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

Returns:
  the `Core` object associated with this message.

### getEphemeralExpireTime

long getEphemeralExpireTime()
Returns the real time at which an ephemeral message expires and will be
deleted.
see: `isEphemeral()`

Returns:
  the time at which an ephemeral message expires. 0 means the message has
  not been read.

### getEphemeralLifetime

long getEphemeralLifetime()
Returns lifetime of an ephemeral message.
The lifetime is the duration after which the ephemeral message will disappear
once viewed. see: `isEphemeral()`

Returns:
  the lifetime of an ephemeral message, by default 0 (disabled).

### getErrorInfo

@NonNull ErrorInfo getErrorInfo()
Gets full details about delivery error of a chat message.

Returns:
  a `ErrorInfo` describing the details.

### getEventLog

@Nullable EventLog getEventLog()
Returns the event log associated to the chat message.

Returns:
  The event log, if exists, null otherwise

### getExternalBodyUrl

@Nullable String getExternalBodyUrl()
Messages can carry external body as defined by rfc2017.

Returns:
  external body url or null if not present.

### setExternalBodyUrl

void setExternalBodyUrl(@Nullable String externalBodyUrl)
Messages can carry external body as defined by rfc2017.

Parameters:
  `externalBodyUrl` - ex: access-type=URL; URL="http://www.foo.com/file"

### getFileTransferInformation

@Nullable Content getFileTransferInformation()
Gets the file transfer information (used by callbacks to recover informations
during a rcs file transfer)

Returns:
  a pointer to the `Content` structure or null if not present.

### getForwardInfo

@Nullable String getForwardInfo()
Gets the forward info if available as a string.

Returns:
  the original sender of the message if it has been forwarded, null
  otherwise.

### getFromAddress

@NonNull Address getFromAddress()
Gets origin of the message.

Returns:
  the `Address` of the sender.

### isEditable

boolean isEditable()
Returns whether this message can be edited (maximum allowed time to edit it was
reached or not).

Returns:
  true if the message can be edited, false otherwise.

### isEdited

boolean isEdited()
Returns whether this message has been edited by it's sender after it was sent.

Returns:
  true if the message has been edited after it was sent, false otherwise.

### isEphemeral

boolean isEphemeral()
Returns whether the chat message is an ephemeral message or not.
An ephemeral message will automatically disappear from the recipient's screen
after the message has been viewed.

Returns:
  true if it is an ephemeral message, false otherwise

### isFileTransfer

@Deprecated boolean isFileTransfer()
Deprecated.
Return whether or not a chat message is a file transfer.

Returns:
  Whether or not the message is a file transfer
  deprecated: 06/07/2020 check if `getContents()` contains a `Content`
  for which `Content.isFileTransfer()` returns true.

### isFileTransferInProgress

boolean isFileTransferInProgress()
Gets whether or not a file is currently being downloaded or uploaded.

Returns:
  true if download or upload is in progress, false otherwise

### isForward

boolean isForward()
Returns whether the chat message is a forward message or not.

Returns:
  true if it is a forward message, false otherwise

### isOutgoing

boolean isOutgoing()
Returns wehther the message has been sent or received.

Returns:
  true if message has been sent, false if it has been received.

### isRead

boolean isRead()
Returns whether the message has been read or not.

Returns:
  true if message has been marked as read, false otherwise.

### isReply

boolean isReply()
Returns whether the chat message is a reply message or not.

Returns:
  true if it is a reply message, false otherwise

### isRetractable

boolean isRetractable()
Returns whether this message can be retracted (maximum allowed time to retract
it was reached or not).

Returns:
  true if the message can be retracted, false otherwise.

### isRetracted

boolean isRetracted()
Returns whether this message has been retracted by it's sender after it was
sent.

Returns:
  true if the message has been retracted after it was sent, false
  otherwise.

### isSecured

boolean isSecured()
Gets if the message was end-to-end encrypted when transferred.

Returns:
  true if the message was end-to-end encrypted when transferred, false
  otherwise.

### isText

@Deprecated boolean isText()
Deprecated.
Return whether or not a chat message is a text.

Returns:
  Whether or not the message is a text
  deprecated: 06/07/2020 check if `getContents()` contains a `Content`
  with a PlainText content type.

### getLocalAddress

@NonNull Address getLocalAddress()
Returns the local address the message was sent or received with.

Returns:
  the `Address` of the local address used to send/receive this
  message.

### getMessageId

@NonNull String getMessageId()
Get the message identifier.
It is used to identify a message so that it can be notified as delivered and/or
displayed.

Returns:
  The message identifier.

### getOwnReaction

@Nullable ChatMessageReaction getOwnReaction()
Returns our own reaction for a given chat message, if any.

Returns:
  Our own `ChatMessageReaction` for that message if any, null
  otherwise.

### getPeerAddress

@NonNull Address getPeerAddress()
Returns the peer (remote) address of the message.

Returns:
  the `Address` of the peer address used to send/receive this
  message.

### getReactions

@NonNull ChatMessageReaction[] getReactions()
Gets the list of reactions received for this chat message.
Warning: list is ordered by content of reaction message, not by received
timestamp!

Returns:
  The sorted list of reaction if any.

### getReplyMessage

@Nullable ChatMessage getReplyMessage()
Returns the `ChatMessage` this message is a reply to.

Returns:
  the original message `ChatMessage`.

### getReplyMessageId

@Nullable String getReplyMessageId()
Returns the ID of the message this is a reply to.

Returns:
  the original message id.

### getReplyMessageSenderAddress

@Nullable Address getReplyMessageSenderAddress()
Returns the address of the sender of the message this is a reply to.

Returns:
  the original message sender `Address`.

### getState

ChatMessage.State getState()
Gets the state of the message.

Returns:
  the current `ChatMessage.State` of the message.

### getTextContent

@Deprecated @Nullable String getTextContent()
Deprecated.
Gets the text content if available as a string.

Returns:
  the `Content` buffer if available in System Locale, null
  otherwise.
  deprecated: 01/07/2020. Use `getUtf8Text()` instead.

### getTime

long getTime()
Gets the time the message was sent.

Returns:
  the timestamp of when the message was sent.

### getToAddress

@NonNull Address getToAddress()
Gets destination of the message.

Returns:
  the `Address` of the recipient.

### getToBeStored

boolean getToBeStored()
Gets if a chat message is to be stored.

Returns:
  Whether or not the message is to be stored

### setToBeStored

void setToBeStored(boolean toBeStored)
Sets if a chat message is to be stored.
This content type must match a content that is text representable, such as
text/plain, text/html or image/svg+xml.

Parameters:
  `toBeStored` - Whether or not the chat message is to be stored

### getUtf8Text

@Nullable String getUtf8Text()
Gets text part of this message.

Returns:
  The text as UTF8 characters or null if no text.

### setUtf8Text

int setUtf8Text(@Nullable String text)
Sets a text to be sent, given as a string of UTF-8 characters.

Parameters:
  `text` - The text in UTF8 to set.
Returns:
  0 if succeed.

### addCallLogContent

void addCallLogContent(@NonNull CallLog callLog)
Adds a call log content to the ChatMessage.

Parameters:
  `callLog` - the `CallLog` object to add.

### addContent

void addContent(@NonNull Content content)
Adds a content to the ChatMessage.

Parameters:
  `content` - the `Content` object to add.

### addCustomHeader

void addCustomHeader(@NonNull String headerName, @Nullable String headerValue)
Adds custom headers to the message.

Parameters:
  `headerName` - name of the header
  `headerValue` - header value

### addFileContent

void addFileContent(@NonNull Content content)
Adds a file content to the ChatMessage.

Parameters:
  `content` - the `Content` object to add.

### addTextContent

@Deprecated void addTextContent(@NonNull String text)
Deprecated.
Creates a `Content` of type PlainText with the given text as body.

Parameters:
  `text` - The text in System Locale to add to the message.
  deprecated: 01/07/2020. Use `addUtf8TextContent(java.lang.String)` instead.

### addUtf8TextContent

void addUtf8TextContent(@NonNull String text)
Creates a `Content` of type text/plain with the provided string, and
attach it to the message.

Parameters:
  `text` - The text to add to the message.

### cancelFileTransfer

void cancelFileTransfer()
Cancels an ongoing file transfer attached to this message (upload or download).

### createReaction

@NonNull ChatMessageReaction createReaction(@NonNull String utf8Reaction)
Creates a emoji reaction for the given chat mesage.
To send it, use `ChatMessageReaction.send()`.

Parameters:
  `utf8Reaction` - the emoji character(s) as UTF-8.
Returns:
  a `ChatMessageReaction` object.

### downloadContent

boolean downloadContent(@NonNull Content content)
Starts the download of the `Content` referenced in the `ChatMessage`
from remote server.

Parameters:
  `content` - the `Content` object to download (must have the `Content.isFileTransfer()`
  method return true).
Returns:
  false if there is an error, true otherwise.

### downloadContents

boolean downloadContents()
Starts the download of all the `Content` objects representing file
transfers included in the message (`Content.isFileTransfer()` method
returns true).

Returns:
  false if there is an error, true otherwise.

### getCustomHeader

@Nullable String getCustomHeader(@NonNull String headerName)
Retrieves a custom header value given its name.

Parameters:
  `headerName` - header name searched
Returns:
  the custom header value or null if not found.

### getParticipantsByImdnState

@NonNull ParticipantImdnState[] getParticipantsByImdnState(ChatMessage.State state)
Gets the list of participants for which the imdn state has reached the
specified state and the time at which they did.

Parameters:
  `state` - The LinphoneChatMessageState the imdn have reached (only use
  LinphoneChatMessageStateDelivered, LinphoneChatMessageStateDeliveredToUser,
  LinphoneChatMessageStateDisplayed and LinphoneChatMessageStateNotDelivered)
Returns:
  The list of participants.

### hasCallLogJsonContent

boolean hasCallLogJsonContent()
Indicates whether the chat message contains a call log in JSON format.

Returns:
  true if it has one, false otherwise.

### hasConferenceInvitationContent

boolean hasConferenceInvitationContent()
Returns whether the chat message has a conference invitation content or not.

Returns:
  true if it has one, false otherwise.

### hasTextContent

@Deprecated boolean hasTextContent()
Deprecated.
Returns whether the chat message has a text content or not.

Returns:
  true if it has one, false otherwise.
  deprecated: 27/10/2020. Check if `getContents()` contains a `Content`
  for which it's content type is PlainText.

### markAsRead

void markAsRead()
Marks the message as read.
Only triggers LinphoneChatRoomCbsChatRoomReadCb if it was the last unread
message.

### putChar

int putChar(int character)
Fulfills a chat message character by character and send the character
immediately as real-time text (RFC4103 / T.140) or as Baudot tones.
The method used to send the character depends on if real-time text is enabled
or not. If it is, real-time text is of course used, otherwise Baudot will be
used if it is enabled in the `Core` (see `Core#enableBaudot`). If
real-time text is used, the `ChatRoom` the message was created from must
be a real-time text capable chat room: it must be obtained by placing or
receiving a call with real-time text capabilities (see `CallParams#enableRealtimeText`
), and getting the `ChatRoom` interface from the call with `Call.getChatRoom()`
. When the message is terminated (ie a new line needs to be started), use
`send()` in order to trigger the sending of the new line character and
have the full message (comprising all characters sent so far) stored in local
database.

Parameters:
  `character` - The character to send (T.140 char for real-time text).
Returns:
  0 if succeed.

### removeContent

void removeContent(@NonNull Content content)
Removes a content from the ChatMessage.

Parameters:
  `content` - the `Content` object to remove.

### removeCustomHeader

void removeCustomHeader(@NonNull String headerName)
Removes a custom header from the message.

Parameters:
  `headerName` - name of the header to remove

### send

void send()
Sends a chat message.

### addListener

void addListener(ChatMessageListener listener)

### removeListener

void removeListener(ChatMessageListener 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`