Create message drafts

MessageDraft represents an unpublished message. Use it to:

Display message elements (mentions, references, links) in your UI by adding a message draft change listener.

Message drafts consist of MessageElement objects, which can be either instances of plainText or link.

plainText elements are simple strings. link elements are used for user mentions, channel references, and URLs. Each link contains text and a reference to the linked element.

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

  • MentionTarget.user(userId: String)
  • MentionTarget.channel(channelId: String)
  • MentionTarget.url(url: String)
Store draft messages locally

Chat SDK does not persist drafts. Implement your own local storage to save drafts across channel switches.

Create a draft message​

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

Method signature​

This method has the following signature:

1channel.createMessageDraft(
2 userSuggestionSource: UserSuggestionSource = .channel,
3 isTypingIndicatorTriggered: Bool = true,
4 userLimit: Int = 10,
5 channelLimit: Int = 10
6) -> MessageDraftImpl

Input​

userSuggestionSource#
Type: UserSuggestionSource = .channel or UserSuggestionSource = .global
Default: UserSuggestionSource = .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).
isTypingIndicatorTriggered#
Type: Bool
Default: true
This parameter refers to the Typing Indicator feature. Defines if the typing indicator should be enabled when writing the message.
userLimit#
Type: Int
Default: 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, the min is 1, and max is 100.
channelLimit#
Type: Int
Default: 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, the min is 1, and max is 100.

Output​

MessageDraftType#
Instance of MessageDraftType, which represents a draft version of a message with the content, all links, referenced channels, mentioned users and their names.

Sample code​

Create a draft message containing just plain text.

1

Create a thread message draft​

createThreadMessageDraft() creates a MessageDraft for composing a reply inside a message thread. Call it on a Message or ThreadMessage object. The resulting draft targets the message's thread channel and supports the same features as a regular draft: mentions, channel references, links, and file attachments.

Method signature​

This method has the following signature:

1message.createThreadMessageDraft(
2 userSuggestionSource: UserSuggestionSource = .channel,
3 isTypingIndicatorTriggered: Bool = true,
4 userLimit: Int = 10,
5 channelLimit: Int = 10
6) -> MessageDraftImpl

Input​

userSuggestionSource#
Type: UserSuggestionSource = .channel or UserSuggestionSource = .global
Default: UserSuggestionSource = .channel
Data source from which you want to retrieve users for mention suggestions. Choose either the list of channel members (.channel) or all users on your Admin Portal keyset (.global).
isTypingIndicatorTriggered#
Type: Bool
Default: true
Defines if the typing indicator should be enabled while writing the message.
userLimit#
Type: Int
Default: 10
Maximum number of usernames (name field from the User object) you can mention in one message. The default value is 10, the min is 1, and max is 100.
channelLimit#
Type: Int
Default: 10
Maximum number of channel names (name field from the Channel object) you can reference in one message. The default value is 10, the min is 1, and max is 100.

Output​

MessageDraftType#
Instance of MessageDraftType targeting the message's thread channel.

Sample code​

Create a draft reply for a thread started by an existing message, then send it.

1

Add message draft change listener​

Add a MessageDraftChangeListener to receive draft content changes and suggestions for mentions, channel references, and links.

Method signature​

This method has the following signature:

1messageDraft.addChangeListener(_ listener: MessageDraftChangeListener)
2
3public protocol MessageDraftChangeListener: AnyObject {
4 /// Called when there is a change in the message elements or suggested mentions.
5 func onChange(messageElements: [MessageElement], suggestedMentions: any FutureObject<[SuggestedMention]>)
6}

Input​

_ listener#
The listener that receives the most current message elements and suggestions list.
MessageDraftChangeListener​
onChange(messageElements: [MessageElement], suggestedMentions: any FutureObject<[SuggestedMention]>)#
Type: function
  • messageElements: [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: any FutureObject<[SuggestedMention]> - this parameter is a FutureObject 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.

offset#
Type: Int
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#
Type: String
The original text at the given offset in the message draft text.
replaceWith#
Type: String
The suggested replacement for the replaceFrom text.
target#
Type: MentionTarget
The message element type. Available types include:

  • MentionTarget.user(userId: String)
  • MentionTarget.channel(channelId: String)
  • MentionTarget.url(url: String)

Output​

This method doesn't return any data.

Sample code​

Add the listener to your message draft.

1

Remove message draft change listener​

Remove a previously added MessageDraftChangeListener.

Method signature​

This method has the following signature:

1messageDraft.removeChangeListener(_ listener: MessageDraftChangeListener)

Input​

_ listener#
The listener to remove.

Output​

This method doesn't return any data.

Sample code​

Remove a listener from your message draft.

1

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:

1messageDraft.addMention(
2 offset: Int,
3 length: Int,
4 target: MentionTarget
5)

Input​

required
offset required#
Type: Int
Default: no default
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 required#
Type: Int
Default: no default
Number of characters the message element should occupy in the draft message's text.
target required#
Type: MentionTarget
Default: no default
Message element type. Available types include:

  • MentionTarget.user(userId: String)
  • MentionTarget.channel(channelId: String)
  • MentionTarget.url(url: String)

Output​

This method returns no output data.

Sample code​

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.

1

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:

1messageDraft.removeMention(offset: Int)

Input​

required
offset required#
Type: Int
Default: no default
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.

Sample code​

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

1

Update message text​

update() replaces the text of a draft message with new content.

Removing message elements

The SDK preserves message elements when possible. If element text is modified, that element is removed.

Method signature​

This method has the following signature:

1messageDraft.update(text: String)

Input​

required
text required#
Type: string
Default: no default
Text of the message that you want to update.

Output​

This method returns no output data.

Sample code​

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

1

Mention text changes

Changing mention text removes that mention. For finer control, use Insert message text and Remove message text.

Insert suggested message element​

Insert a message element from the MessageDraftChangeListener into the MessageDraft object.

Text must match

SuggestedMention.replaceFrom must match the draft text at the specified position, or an exception is thrown.

Method signature​

This method has the following signature:

1messageDraft.insertSuggestedMention(
2 mention: SuggestedMention,
3 text: String
4)

Input​

required
mention required#
Type: SuggestedMention
Default: no default
A user, channel, or URL suggestion obtained from MessageDraftChangeListener.
text required#
Type: string
Default: no default
The text you want the message element to display.

Output​

This method returns no output data.

Sample code​

Register a listener and insert a suggested element.

1

Insert message text​

insertText() inserts plain text in the draft message at the specified offset.

Removing message elements

Inserting text at an existing message element position removes that element.

Method signature​

This method has the following signature:

1messageDraft.insertText(
2 offset: Int,
3 text: String
4)

Input​

required
offset required#
Type: Int
Default: no default
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 required#
Type: string
Default: no default
Text that you want to insert.

Output​

This method returns no output data.

Sample code​

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

1

Remove message text​

removeText() removes plain text from the draft message at the specified offset.

Removing message elements

Removing text at an existing message element position removes that element.

Method signature​

This method has the following signature:

1messageDraft.removeText(
2 offset: Int,
3 length: Int
4)

Input​

required
offset required#
Type: Int
Default: no default
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 required#
Type: Int
Default: no default
How many characters to remove, starting at the given offset.

Output​

This method returns no output data.

Sample code​

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

1

Send a draft message​

send() publishes the draft message with all mentioned users, links, and referenced channels. Mentioning users also emits mention events.

Method signature​

This method has the following signature:

1messageDraft.send(
2 params: SendTextParams = SendTextParams()
3) async throws -> Timetoken

The SendTextParams struct groups common publishing options:

1public struct SendTextParams {
2 public var meta: [String: JSONCodable]?
3 public var shouldStore: Bool
4 public var usePost: Bool
5 public var ttl: Int?
6 public var customPushData: [String: String]?
7}

Input​

params#
Type: SendTextParams
Default: SendTextParams()
Publishing options grouped in a single struct. See sendText() for field descriptions.

Message elements (links, quotes, mentions, channel references) are not passed to send() directly. Add them to the MessageDraft object through addMention() and addQuote().

Output​

Timetoken#
Timetoken of the message.

Sample code​

Send a draft message containing just plain text.

1

Was this page useful?

Last updated on