Create message drafts

A MessageDraft object is an abstraction for composing a message that has not yet been published. You can use it to:

You can display user mentions, channel references, and links (collectively called "message elements") to the user on the front end of your application by adding a message draft change listener.

Message drafts consist of MessageElement objects, which can be either instances of PlainText or Link.

PlainText are simple strings, while Link elements are used for user mentions, channel references, and URLs. They contain a text and a reference to the linked element regardless if it's a user, a channel, or a URL.

Each Link implements a MentionTarget interface, which defines the type of mention. Available targets include:

  • MentionTarget.User(val userId: String)
  • MentionTarget.Channel(val channelId: String)
  • MentionTarget.Url(val url: String)
Store draft messages locally

Kotlin Chat SDK does not provide a method for storing the drafted message on the client, so whenever a user drafts a message in a chat app, changes a channel, and goes back to that channel, the drafted message gets lost.

To save drafted messages before they are published on channels, implement your own local storage mechanism suitable for the platform you use.

Create a draft message​

createMessageDraft() creates a message draft (MessageDraft object) that can consist of:

Method signature​

This method has the following signature:

channel.createMessageDraft(
  userSuggestionSource: UserSuggestionSource = UserSuggestionSource.CHANNEL,
  isTypingIndicatorTriggered: Boolean = true,
  userLimit: Int = 10,
  channelLimit: Int = 10
):

Input​

ParameterTypeRequiredDefaultDescription
userSuggestionSourceUserSuggestionSource.CHANNEL or UserSuggestionSource.GLOBALNoUserSuggestionSource.CHANNELThis parameter refers to the Mentions feature. Data source from which you want to retrieve users. You can choose either the list of channel members (.CHANNEL) or users on the app's Admin Portal keyset (.GLOBAL).
isTypingIndicatorTriggeredBooleanNotrueThis parameter refers to the Typing Indicator feature. Defines if the typing indicator should be enabled when writing the message.
userLimitIntNo10This parameter refers to the Mentions feature. Maximum number of usernames (name field from the User object) you can mention in one message (the default value is 10 and max is 100).
channelLimitIntNo10This parameter refers to the References feature. Maximum number of channel names (name field from the Channel object) you can reference in one message (the default value is 10 and max is 100).

Output​

TypeDescription
MessageDraftImplCreated MessageDraft object with the content of the message, all links, referenced channels, mentioned users and their names.

Basic usage​

Create a draft message containing just plain text.

val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)

Add message draft change listener​

Add a MessageDraftChangeListener to listen for changes to the contents of a message draft, as well as to retrieve the current message elements suggestions for user mentions, channel reference, and links. For example, when the message draft contains ... @name ... or ... #chann ....

Method signature​

This method has the following signature:

messageDraft.addChangeListener(listener: MessageDraftChangeListener)

// interface to implement
fun interface MessageDraftChangeListener {
  fun onChange(messageElements: List<MessageElement>, suggestedMentions: PNFuture<List<SuggestedMention>>)
}

Input​

ParameterTypeDescription
listenerMessageDraftChangeListenerThe listener that receives the most current message elements and suggestions list.
MessageDraftChangeListener​
ParameterTypeDescription
onChange(messageElements: List<MessageElement>, suggestedMentions: PNFuture<List<SuggestedMention>>)function
  • messageElements: List<MessageElement> - this parameter is a list of MessageElement objects, representing the current state of the message draft. This could contain a mix of plain text and links, channel references, or user mentions.
  • suggestedMentions: PNFuture<List<SuggestedMention>> - this parameter is a PNFuture containing a list of SuggestedMention objects. These are potential suggestions for message elements based on the current text in the draft.
SuggestedMention​

A SuggestedMention represents a potential mention suggestion received from MessageDraftChangeListener.

ParameterTypeDescription
offsetIntThe position from the start of the message draft where the message elements starts. It's counted from the beginning of the message (including spaces), with 0 as the first character.
replaceFromStringThe original text at the given offset in the message draft text.
replaceWithStringThe suggested replacement for the replaceFrom text.
targetMentionTargetThe message element type. Available types include:

  • MentionTarget.User(val userId: String)
  • MentionTarget.Channel(val channelId: String)
  • MentionTarget.Url(val url: String)

Output​

This method doesn't return any data.

Basic usage​

Add the listener to your message draft.

// create a message draft
val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)

// add the listener
val listener = { elements: List<MessageElement>, suggestedMentions: PNFuture<List<SuggestedMention>> ->
        updateUI(elements) // updateUI is your own function for updating UI
        suggestedMentions.async { result ->
            result.onSuccess { updateSuggestions(it) } // updateSuggestions is your own function for displaying suggestions
        }
    }
messageDraft.addChangeListener(listener)

Remove message draft change listener​

Remove a previously added MessageDraftChangeListener.

Method signature​

This method has the following signature:

messageDraft.removeChangeListener(listener: MessageDraftChangeListener)

Input​

ParameterTypeDescription
listenerMessageDraftChangeListenerThe listener to remove.

Output​

This method doesn't return any data.

Basic usage​

Remove a listener from your message draft.

// create a message draft
val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)

// add the listener
val listener = { elements: List<MessageElement>, suggestedMentions: PNFuture<List<SuggestedMention>> ->
        updateUI(elements) // updateUI is your own function for updating UI
        suggestedMentions.async { result ->
            result.onSuccess { updateSuggestions(it) } // updateSuggestions is your own function for displaying suggestions
        }
    }
messageDraft.addChangeListener(listener)

// remove the listener
messageDraft.removeChangeListener(listener)

Add message element​

addMention() adds a user mention, channel reference or a link specified by a mention target at a given offset.

Method signature​

This method has the following signature:

messageDraft.addMention(
  offset: Int, 
  length: Int, 
  target: MentionTarget
)

Input​

ParameterTypeRequiredDefaultDescription
offsetIntYesn/aPosition of a character in a message where the message element you want to insert starts. It's counted from the beginning of the message (including spaces), with 0 as the first character.
lengthIntYesn/aNumber of characters the message element should occupy in the draft message's text.
targetMentionTargetYesn/aMessage element type. Available types include:

  • MentionTarget.User(val userId: String)
  • MentionTarget.Channel(val channelId: String)
  • MentionTarget.Url(val url: String)

Output​

This method returns no output data.

Basic usage​

Create the Hello Alex! I have sent you this link on the #offtopic channel. message where Alex is a user mention, link is a URL, and #offtopic is a channel reference.

// create an empty message draft
val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)

// add a text
messageDraft.update(text = "Hello Alex!")

// add a user mention to the string 'Alex'
messageDraft.addMention(offset = 6, length = 4, target = MentionTarget.User(userId = "alex_d"))

// change the text
messageDraft.update(text = "Hello Alex! I have sent you this link on the #offtopic channel.")

// add a link to the string 'link'
messageDraft.addMention(offset = 28, length = 4, target = MentionTarget.Url(url = "www.pubnub.com"))

show all 17 lines

Remove message element​

removeMention() removes a user mention, channel reference, or a link at a given offset.

Method signature​

This method has the following signature:

messageDraft.removeMention(offset: Int)

Input​

ParameterTypeRequiredDefaultDescription
offsetIntYesn/aPosition of the first character of the message element you want to remove.
Offset value

If you don't provide the position of the first character of the message element to remove, it isn't removed.

Output​

This method returns no output data.

Basic usage​

Remove the URL element from the word link in the Hello Alex! I have sent you this link on the #offtopic channel. message.

// assume the message reads
// Hello Alex! I have sent you this link on the #offtopic channel.

// remove the link mention
messageDraft.removeMention(offset = 28)

Update message text​

update() lets you replace the text of a draft message with new content.

Removing message elements

As a best effort, the optimal set of insertions and removals that converts the current text to the provided text is calculated to preserve any message elements.

If any message element text is found to be modified in the updated text, the message element is removed.

Method signature​

This method has the following signature:

messageDraft.update(text: String)

Input​

ParameterTypeRequiredDefaultDescription
textstringYesn/aText of the message that you want to update.

Output​

This method returns no output data.

Basic usage​

Change the message I sent Alex this picture. to I did not send Alex this picture. where Alex is a user mention.

// the message reads:
// I sent [Alex] this picture.
// where [Alex] is a user mention
messageDraft.update(text = "I did not send Alex this picture.")
// the message now reads: 
// I did not send [Alex] this picture.
// the mention is preserved because its text wasn't changed
Mention text changes

If you decided to change the name Alex to some other name, the mention would be removed because your updated text's index coincided with an existing mention.

For more manual control over inserting and removing parts of a message, refer to Insert message text and Remove message text.

Insert suggested message element​

Inserts a message element returned by the MessageDraftChangeListener into the MessageDraft.

Text must match

The SuggestedMention must be up to date with the message text, that is, SuggestedMention.replaceFrom must match the message draft at position SuggestedMention.replaceFrom, otherwise an exception is thrown.

Method signature​

This method has the following signature:

messageDraft.insertSuggestedMention(
  mention: SuggestedMention, 
  text: String
)

Input​

ParameterTypeRequiredDefaultDescription
mentionSuggestedMentionYesn/aA user, channel, or URL suggestion obtained from MessageDraftChangeListener.
textstringYesn/aThe text you want the message element to display.

Output​

This method returns no output data.

Basic usage​

Register a listener and insert a suggested element.

// create a message draft
val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)

// add the listener
val listener = { elements: List<MessageElement>, suggestedMentions: PNFuture<List<SuggestedMention>> ->
        updateUI(elements) // updateUI is your own function for updating UI
        suggestedMentions.async { result ->
            result.onSuccess { updateSuggestions(it) } // updateSuggestions is your own function for displaying suggestions
        }
    }
messageDraft.addChangeListener(listener)

// when the user selects a suggestion in the UI:
messageDraft.insertSuggestedMention(suggestion, suggestion.replaceWith)

Insert message text​

insertText() lets you insert plain text in the draft message at a given offset from the beginning of the message.

Removing message elements

If the position of the text you want to insert corresponds to an existing message element, this element is removed.

Method signature​

This method has the following signature:

messageDraft.insertText(
    offset: Int, 
    text: String
)

Input​

ParameterTypeRequiredDefaultDescription
offsetIntYesn/aPosition of a character in a message where the text you want to insert starts. It's counted from the beginning of the message (including spaces), with 0 as the first character.
textstringYesn/aText that you want to insert.

Output​

This method returns no output data.

Basic usage​

In the message Check this support article https://www.support-article.com/., add the word out between the words Check and this.

// the message reads:
// Check this support article https://www.support-article.com/.
messageDraft.insertText(6, "out ")
// the message now reads: 
// Check out this support article https://www.support-article.com/.

Remove message text​

removeText() lets you remove plain text from the draft message at a given offset from the beginning of the message.

Removing message elements

If the position of the text you want to remove corresponds to an existing message element, this element is removed.

Method signature​

This method has the following signature:

messageDraft.removeText(
    offset: Int, 
    length: Int
)

Input​

ParameterTypeRequiredDefaultDescription
offsetIntYesn/aPosition of a character in a message where the text you want to insert starts. It's counted from the beginning of the message (including spaces), with 0 as the first character.
lengthIntYesn/aHow many characters to remove, starting at the given offset.

Output​

This method returns no output data.

Basic usage​

In the message Check out this support article https://www.support-article.com/., remove the word out.

// the message reads:
// Check out this support article https://www.support-article.com/..
messageDraft.remove(5, 4)
// the message now reads: 
// Check this support article https://www.support-article.com/.

Send a draft message​

send() publishes the draft text message with all mentioned users, links, and referenced channels.

Whenever you mention any users, send() also emits events of type mention.

Method signature​

This method has the following signature:

messageDraft.send(
  meta: Map<String, Any>? = null,
  shouldStore: Boolean = true,
  usePost: Boolean = false,
  ttl: Int? = null,
): PNFuture<PNPublishResult>

Input​

ParameterTypeRequiredDefaultDescription
metaMap<String, Any>?Non/aAdditional details of the request.
shouldStoreBooleanNotrueIf true, the messages are stored in Message Persistence (PubNub storage).
If shouldStore is not specified, the Message Persistence configuration specified on the Admin Portal keyset is used.
usePostBooleanNofalseWhen true, the SDK uses HTTP POST to publish the messages. The message is sent in the BODY of the request instead of the query string when HTTP GET is used. The messages are also compressed to reduce their size.
ttlInt?Non/aDefines if / how long (in hours) the message should be stored in Message Persistence.
  1. If shouldStore = true, and ttl = 0, the message is stored with no expiry time.
  2. If shouldStore = true and ttl = X, the message is stored with an expiry time of X hours.
  3. If shouldStore = false, the ttl parameter is ignored.
  4. If ttl is not specified, then the expiration of the message defaults back to the expiry value for the keyset.

Suppose a user adds elements to the message draft, such as links, quotes, other user mentions, or channel references. In that case, these are not explicitly passed in the send() method but get added to the MessageDraft object through the addMention() and addQuote() methods.

Output​

TypeDescription
Promise<{ timetoken: number }>Returned object that contains the timetoken of the message.

Basic usage​

Send a draft message containing just plain text.

// create a draft message
val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)

// add text
messageDraft.update(text = "Hello!")
// send the message
messageDraft.send()
Last updated on
On this page