Properties

static

ReservedTag  string

The SparkCommunications.Messenger.ChatMessage tags that are reserved for use by the SDK.

Properties

Name Type Optional Description

Join

 

 

The message sender has joined the chat. A message with this tag has no content, data, or thumbData properties.

Leave

 

 

The message sender has left the chat. A message with this tag has no content, data, or thumbData properties.

Subject

 

 

The message sender has changed the chat's subject. The content property contains the new subject. A message with this tag has no data or thumbData properties.

Shred

 

 

The message sender has shredded all of their earlier contributions to the chat.

Gap

 

 

A gap in the message history has been detected. This tag will not appear in the message history but is reserved because it is used to represent gaps in the mobile SDKs.

Admin

 

 

A message type indicating that there is an update to a partcipant's chat admin status.

Remove

 

 

A message type indicating that a participant was removed from a chat.

static

StateValue  string

The possible state values that a SparkCommunications.Messenger.ChatMessage can have.

Properties

Name Type Optional Description

Sent

 

 

An outgoing message has been successfully received by the BlackBerry Infrastructure. This state can progress to Delivered or Read.

Failed

 

 

An outgoing message has failed to be sent to the BlackBerry Infrastructure. This state is final and cannot be progressed.

Delivered

 

 

For an outgoing message, this state indicates that the message has been delivered to at least one other participant in the chat. For an incoming message, this state indicates that the message has been delivered to the local user.

This state can be progressed to Read.

Read

 

 

For an outgoing message, this state indicates that the message has been read by at least one other participant in the chat. For an incoming message, this state indicates that the message has been read by the local user.

This state is final and cannot be progressed or regressed.

chatId  string

The unique identifier of the chat in which this message belongs.

optional

content  string

The text content of the message when the tag has such a concept; otherwise undefined.

optional

data  (Object, ChatMessage.AdminData, or ChatMessage.RemoveData)

When tag === ReservedTag.Admin the data will be an AdminData object.

When tag === ReservedTag.Remove the data will be a RemoveData object.

For any other reserved tag, the data object will be undefined.

For any unreserved tag the data object will be set according to the application usage and the SDK will not examine or modify the data.

When present, this will always be a JSON Object.

optional

fileName  string

The file name suggested by the sender, if known. This field is only meaningful when this message has a file attachment.

optional

fileSize  number

The advertised size of the file, in bytes, as indicated by the sender. This field is only meaningful when this message has a file attachment. The actual file size can differ from this advertised size.

When the sender did not indicate a size, or the size of the file could not otherwise be determined, this field will not be present. Otherwise, this value is available before any attempt is made to download a received attachment. Your application can use this value to decide whether or not to download the attachment.

This field is available for all outgoing messages with a file attachment.

gapDetected  boolean

This field indicates whether or not a gap has been detected following this message. One or more messages may be unavailable and missing from the chat. Gaps should be extremely rare and can only occur with long lived clients that have been disconnected from the BlackBerry Infrastructure for an extended period of time that reconnect after message history has been culled from the BlackBerry Infrastructure.

hasFile  boolean

Flag to indicate whether or not the message has a file linked to it which may be downloaded by calling download().

isControl  boolean

A flag to indicate that this message was flagged by the sending application as being for control purposes versus for display purposes. This flag is useful for introducing new custom message types (typically with a new tag value) that older endpoints do not understand.

Some applications, such as Instant Messaging applications, will want to inform the user that some message was received even when that type of message is unknown to the endpoint. For example, an Instant Messaging application might show "This item is not supported." when an unknown type of message is received in a chat. This lets users know they received something, but their client can't display it.

This flag is meant to allow a sender to prevent the display of such placeholders for messages that the receiver doesn't understand. When an endpoint receives a message that it does not understand and the message has this flag set, it should ignore the message and not even attempt to display a placeholder. The flag indicates that the receiving endpoint is safe to assume that the message was never meant to be displayed in any versions of the application. In this way, any older endpoint that knows about this flag and behaves accordingly can be told which messages are worth displaying placeholders for and which messages are "control" messages that it can completely ignore even when those messages (and their tag values) were not yet invented when the older endpoint was made.

There is a subtle distinction between understanding and supporting a message. Receivers that do understand a received message should ignore this flag and decide how to handle it based on what they do and don't want to support. Changes should be designed so that receivers that partially understand a received message, and, for example, know its tag and how to display its content but which don't know all of the data fields should be able to use what they can from the message and still behave properly. It is only receivers that do not even understand the message that should consider this flag.

When sending a newly introduced message type, consider whether receivers that are completely ignorant of the message should display a placeholder or not. If and only if they never should, then set this flag.

If your application has no concept of placeholders, this flag is irrelevant.

isDeleted  boolean

This flag indicates whether or not the message has been privately deleted for the local user. When true, the message has been deleted and the content, data, and thumbData will be removed.

isIncoming  boolean

The flag to indicate whether or not the message is incoming (i.e. sent by a participant other than the local user). When true the message is incoming. When false, the message is outgoing.

isRecalled  boolean

Flag to indicate whether or not the message has been recalled. When true, the message has been recalled by the sender and the content, data, and thumbData will be removed. When omitted/undefined or false, the message has not been recalled.

isUnverified  boolean

The flag to indicate whether or not the message signature was verified. When true, the message signature could not be verified. When false, the message signature was successfully verified.

messageId  string

The unique identifier for this message used within the SDK and the BlackBerry Infrastructure.

neverCountUnread  boolean

A flag to indicate that this message never contributes to the unread message count returned by SparkCommunications.Messenger#getUnreadCount and will never update lastActivity.

Your application can set this on messages it sends that are not displayed by other endpoints. Doing so helps the unread count reflect the number of messages that the user has not read.

This flag has no effect on the state of a chat message or the behaviour of SparkCommunications.Messenger#chatMessageRead. For example, messages with this flag will be Delivered when received and can be marked as Read.

optional

ref  Array of SparkCommunications.Messenger.ChatMessage.Ref

The array of references to other messages.

This will be undefined when no references to other messages exist. Otherwise, it will be a non-empty array.

Note that no validation of the array's contents is performed.

optional

refBy  Array of SparkCommunications.Messenger.ChatMessage.RefBy

The array of references to this message from other messages.

This will be undefined when no references from other messages exist. Otherwise, it will be a non-empty array.

Note that no validation of the array's contents is performed.

sender  string

The regId of the sender of this message. The sender is either a current or past participant of the chat.

state  SparkCommunications.Messenger.ChatMessage.State

The current delivery/read state of the message.

For incoming messages, the state reflects whether or not the local user has read the message. There are no partial states for incoming messages.

For outgoing messages, the state reflects whether or not the message was successfully sent. It also indicates whether or not other participants have declared the message as delivered or read. The delivered and read states may be flagged as partial for outgoing messages.

tag  string

The application defined tag that identifies the type of message. This may also be one of the reserved tag values defined in SparkCommunications.Messenger.ChatMessage.ReservedTag

optional

thumbData  Uint8Array

The raw bytes of a small file that were included in the message.

optional

thumbName  string

The suggested filename to store the thumbnail data.

timestamp  Date

The date and time the message was sent by the sender.

Method

optional

download(options) → Promise containing Uint8Array

Download the file associated with a ChatMessage. This function is only present when hasFile is set.

Parameters

Name Type Optional Description

options

Object

 

Options for the download procedure.

options.progress

function()

Yes

A callback which will receive events conforming to the ProgressEvent interface (even in node.js).

Returns

Promise containing Uint8Array 

Containing the file associated with this messages. The promise may be rejected with any SparkCommunications.Error error.

Abstract types

static

AdminData  object

The object used to encapsulate the data for a participant that had their admin status in a chat changed.

Properties

Name Type Optional Description

regId

string

 

The regId of the chat participant that had their admin status changed.

promotion

boolean

 

The promotion state of the chat participant. True if the participant was promoted to admin, false if the participant was demoted.

static

Ref  Object

A reference to another ChatMessage.

Properties

Name Type Optional Description

tag

string

 

An opaque string supplied by the application that indicates the type of reference.

messageId

SparkCommunications.Messenger.MessageId

 

The messageId of the message being referenced.

static

RefBy  Object

A summary of references from other ChatMessages.

Properties

Name Type Optional Description

tag

string

 

An opaque string supplied by the application that indicates the type of reference.

messageIds

Array of SparkCommunications.Messenger.MessageId

 

The list of messageIds that reference this message via the tag.

static

RemoveData  object

The object used to encapsulate the data for a participant that was removed from a chat.

Property

Name Type Optional Description

regId

string

 

The regId of the participant that was removed.

static

State  Object

The object used to encapsulate the current state of a SparkCommunications.Messenger.ChatMessage.

Properties

Name Type Optional Description

value

SparkCommunications.Messenger.ChatMessage.StateValue

 

The value of the current state.

isPartial

boolean

 

This indicates whether or not the state applies to some (true) or all (false) recipient. A partial state is only ever applied to outgoing messages that have progressed to the Delivered or Read states.