Create message drafts (v2)
Message drafts v2
This document describes the usage of message drafts version 2. If you're looking for message drafts version 1 documentation, refer to Drafts v1.
A MessageDraftV2
object is an abstraction for composing a message that has not yet been published. You can use it to:
- Edit text before it is published
- Add channel references, user mentions, links
- Attach files
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.
- Basics
- Class diagram
- Example
- Internal mention format
Message drafts consist of simple strings and generic link element, which are used for user mentions, channel references, and URLs. Each link element contains a text and a reference to the linked element regardless if it's a user, a channel, or a URL.
Store draft messages locally
JavaScript 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.
Consider the message Hey, I sent Alex this link on the #offtopic channel.
where:
Alex
is a reference to the user with the ID ofalex_d
link
is a URL of thewww.pubnub.com
website#offtopic
is a reference to the channel with the ID ofgroup.offtopic
The list of MessageElement
objects returned by the MessageDraftV2ChangeListener
is as follows:
Part of Message | Element Type | Code Used to Create |
---|---|---|
Hey, I sent | MixedTextTypedElement | messageDraft.update("Hey, I sent Alex this link on the #offtopic channel.") |
Alex | mention | messageDraft.addMention(12, 4, "mention", "alex_d") |
this | MixedTextTypedElement | messageDraft.update("Hey, I sent Alex this link on the #offtopic channel.") |
link | textLink | messageDraft.addMention(22, 4, "textLink", "http://www.pubnub.com") |
on the | MixedTextTypedElement | messageDraft.update("Hey, I sent Alex this link on the #offtopic channel.") |
#offtopic | channelReference | messageDraft.addMention(34, 9, "channelReference", "group.offtopic") |
channel. | MixedTextTypedElement | messageDraft.update("Hey, I sent Alex this link on the #offtopic channel.") |
By internally leveraging a Markdown-like syntax, the message draft format integrates links directly into the message text using the pattern [link text](link target)
understood by the Chat SDK.
Mention Type | Example |
---|---|
user | [John Doe](pn-user://john_doe) |
channel | [General Chat](pn-channel://group.chat.123) |
url | [PubNub](https://www.pubnub.com) |
Custom schemas like pn-user://
and pn-channel://
are used to identify user and channel mentions, while traditional URLs are supported as-is.
Adding message elements
You don't use this Markdown-like syntax when adding message elements. It's only a representation of your message elements under the hood.
For more information, refer to Add message element.
Create a draft message
createMessageDraftV2()
creates a message draft (MessageDraftV2
object) that can consist of:
- Plain text
- Files
- Mentioned users
- Referenced channels
- Links
- Quoted messages
Method signature
This method has the following signature:
channel.createMessageDraftV2(config?: Partial<MessageDraftConfig>): MessageDraftV2;
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
config | Partial<MessageDraftConfig> | No | This object holds the configuration options. | |
config →userSuggestionSource | channel or global | No | channel | This 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 ). |
config →isTypingIndicatorTriggered | boolean | No | true | This parameter refers to the Typing Indicator feature. Defines if the typing indicator should be enabled when writing the message. |
config →userLimit | number | No | 10 | This 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 ). |
config →channelLimit | number | No | 10 | This 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
Type | Description |
---|---|
MessageDraftV2 | Instance of MessageDraftV2 , which represents a draft version of a message with the content, all links, referenced channels, mentioned users and their names. |
Basic usage
Create a draft message containing just plain text.
messageDraft = channel.createMessageDraftV2({ userSuggestionSource: "global" })
Add message draft change listener
Add a MessageDraftState
listener 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: (p0: MessageDraftState) => void): void;
Input
Parameter | Type | Description |
---|---|---|
listener | MessageDraftState | The listener that receives the most current message elements and suggestions list. |
MessageDraftState
Parameter | Type | Description |
---|---|---|
messageElements() | Array<MixedTextTypedElement> | Array of MixedTextTypedElement 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()) | Promise<Array<SuggestedMention>> | A Promise containing an array 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 MessageDraftState listener.
Parameter | Type | Description |
---|---|---|
offset | number | The 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. |
replaceFrom | String | The original text at the given offset in the message draft text. |
replaceWith | String | The suggested replacement for the replaceFrom text. |
type | TextTypes | The message element type. Available types include:
|
target | string | The actual mention element in string format:
|
Output
This method doesn't return any data.
Basic usage
Add the listener to your message draft.
// Create a message draft
messageDraft = channel.createMessageDraftV2({ userSuggestionSource: "global" })
// Add the listener
messageDraft.addChangeListener(async function(state) {
updateUI(state.messageElements) // where updateUI is your function for displaying the message content
updateSuggestedMentionsUI(mentions) // where updateSuggestedMentionsUI is your function for displaying mention suggestions
})
Remove message draft change listener
Remove a previously added MessageDraftState
listener.
Method signature
This method has the following signature:
removeChangeListener(listener: (p0: MessageDraftState) => void): void;
Input
Parameter | Type | Description |
---|---|---|
listener | MessageDraftState | The listener to remove. |
Output
This method doesn't return any data.
Basic usage
Remove a listener from your message draft.
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: number,
length: number,
mentionType: TextTypes,
mentionTarget: string
): void;
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
offset | Int | Yes | n/a | Position 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. |
length | Int | Yes | n/a | Number of characters the message element should occupy in the draft message's text. |
mentionType | TextTypes | Yes | n/a | The message element type. Available types include:
|
mentionTarget | string | Yes | n/a | The actual mention element in string format:
|
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 a message draft
messageDraft = channel.createMessageDraftV2({ userSuggestionSource: "global" })
// Add initial text
messageDraft.update("Hello Alex!")
// Add a user mention to the string "Alex"
messageDraft.addMention(6, 4, "mention", "alex_d"))
// Change the text
messageDraft.update("Hello Alex! I have sent you this link on the #offtopic channel.")
// Add a URL mention to the string "link"
messageDraft.addMention(33, 4, "textLink", "www.pubnub.com")
show all 17 linesRemove 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: number): void;
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
offset | number | Yes | n/a | Position 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(33)
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
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
text | string | Yes | n/a | Text 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( "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 MessageDraftState
listener into the MessageDraftV2
object.
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
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
mention | SuggestedMention | Yes | n/a | A user, channel, or URL suggestion obtained from MessageDraftState listener. |
text | string | Yes | n/a | The 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
messageDraft = channel.createMessageDraftV2({ userSuggestionSource: "global" })
// Add the listener
messageDraft.addChangeListener(async function(state) {
updateUI(state.messageElements) // where updateUI is your function for displaying the message content
let mentions = await state.suggestedMentions
messageDraft.insertSuggestedMention(mentions[0], mentions[0].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: number,
text: string
)
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
offset | number | Yes | n/a | Position 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. |
text | string | Yes | n/a | Text 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: number,
length: number
)
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
offset | number | Yes | n/a | Position 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. |
length | number | Yes | n/a | How 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.removeText(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(
params?: MessageDraftOptions
): Promise<PubNub.PublishResponse>;
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
params | MessageDraftOptions | No | This object holds the configuration options. | |
params →storeInHistory | boolean | No | true | If true , the messages are stored in Message Persistence (PubNub storage). If storeInHistory is not specified, the Message Persistence configuration specified on the Admin Portal keyset is used. |
params →sendByPost | boolean | No | false | When 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. |
params →meta | any | No | n/a | Publish additional details with the request. |
params →ttl | number | No | n/a | Defines if / how long (in hours) the message should be stored in Message Persistence.
|
Output
Type | Description |
---|---|
Timetoken | Timetoken of the message. |
Basic usage
Send a draft message containing just plain text.
// Create a message draft
messageDraft = channel.createMessageDraftV2({ userSuggestionSource: "global" })
// Add text
messageDraft.update("Hello!")
// Send the message
messageDraft.send()