Properties

constant static

InvitePolicy  string

The possible invite policies that can be applied to a SparkCommunications.Messenger.Chat

Properties

Name Type Optional Description

AdminsOnly

 

 

Only chat admins may invite participants to the chat.

ParticipantsOnly

 

 

Only chat participants may invite participants to the chat. This is the default state.

constant static

State  string

The possible states of a SparkCommunications.Messenger.Chat.

Properties

Name Type Optional Description

NoKey

 

 

The chat has been created but the SDK failed to retrieve the chat key. To restore the key, a call to SparkCommunications.Messenger#chatKeysRequest must be made by the application. Your application may choose to leave the chat via SparkCommunications.Messenger#chatLeave.

A chat in this state cannot restore content from the BlackBerry Infrastructure or receive new messages while online until the chat key can be restored.

From the NoKey state, the chat will transition to the Waiting state to indicate that content can now be restored.

Waiting

 

 

The chat has been created and is waiting to be restored on demand. To restore the Chat, one or more calls to SparkCommunications.Messenger#fetchChatMessages must be made by the application.

A chat in this state can still receive new messages that were sent to the chat after the SDK was setup. These messages will be delivered to the application via the chatMessageAdded event.

When the application begins restoring content by calling SparkCommunications.Messenger#fetchChatMessages, the chat will transition to the Restoring state.

Restoring

 

 

The chat will enter the Restoring state after the first call to SparkCommunications.Messenger#fetchChatMessages. Multiple calls to SparkCommunications.Messenger#fetchChatMessages can be made while the chat is Restoring to add new restore criteria.

When all restore criteria are satisfied, the chat will transition to the Ready state.

When one or more of the calls to SparkCommunications.Messenger#fetchChatMessages fails, the chat will regress to the Waiting state to indicate that the restore criteria was not fully met.

If the SDK discovers that the user is no longer a member of the chat while restoring content, the chat will then enter the Defunct state.

Ready

 

 

When all promises returned by SparkCommunications.Messenger#fetchChatMessages while the chat is in the Waiting or Restoring state have been resolved, the chat will enter the Ready state.

From the Ready state, the chat can only move to the Defunct state.

Defunct

 

 

The BlackBerry Infrastructure has indicated this chat is no longer available. This state exists so the user knows why their previously functional chat is no longer functional, and gives the user a chance to consume the content of the chat until they remove it. The SDK will not send or receive any further messages for a chat in this state.

When a chat becomes defunct because the SDK learned that the chat is no longer available, it will be automatically removed only when the SDK has no chat messages cached for the chat. Chats that have messages will be retained by the SDK until they are explicitly removed by the application by calling SparkCommunications.Messenger#chatLeave.

Chats that are left as a result of a call to SparkCommunications.Messenger#chatLeave will enter the Defunct state, if they are not already Defunct, before being removed from the SDK.

chatId  string

The unique identifier of the chat. This is the chat identifier to use when identifying a chat to any of the Messenger functions. This value will never change.

creationTime  Date

The creation time of the chat.

This field can be temporarily set to the Unix epoch when a chat is created on a different endpoint or a chat is joined as the result of being invited by another participant. After the SDK has fetched the chat details from the BlackBerry Infrastructure, this field will be updated to reflect the chat's true creation time.

data  Object

This field contains opaque data managed by the application.

This data can be read or written by any participant. Concurrent writes are resolved in a way that all participants will eventually see the same steady-state outcome.

This field is suitable for shared chat metadata that changes infrequently such as the chat avatar URL, the identifiers of external resources associated with the chat, or a per-chat setting shared by all participants. Data that changes frequently should be sent to all participants via the SparkCommunications.Messenger#chatMessageSend function by setting the 'data' property of the SparkCommunications.Messenger.ChatMessageSendOptions.

The 'data', encoded as JSON in UTF-8, must not exceed 71680 bytes (70 KB).

invitePolicy  Chat.InvitePolicy

The policy that controls who can invite participants to the chat. This will only be defined when 'isOneToOne' is false because invites cannot be extended to others in a one-to-one chat.

isOneToOne  boolean

This will be set to true when the chat is a one-to-one chat between the local user and one other participant. This value will never change.

lastActivity  Date

The time of the most recent notable activity in the chat. Notable activity includes chat creation and new messages. Before the chat is restored, this will be the Unix epoch.

participants  Array of SparkCommunications.Messenger.Participant

The list of active and pending participants in the chat. Only pending participants invited by the local user from this endpoint will be included. A chat may contain messages from past participants which are no longer in this list.

privateData  Object

This field contains opaque data managed by the application.

This data can be read or written only by endpoints belonging to the local user's identity. Concurrent writes are resolved in a way that all endpoints will eventually see the same steady-state outcome.

This field is suitable for chat metadata that changes infrequently and is private to the local user's identity but needs to be known by all the local user's endpoints.

The 'privateData', encoded as JSON in UTF-8, must not exceed 71680 bytes (70 KB).

state  Chat.State

The current state of the chat.

A chat that is created in the current session by the local user will start in the Ready state.

A chat that is known to the SDK but has not yet been restored, will start in the Waiting state.

subject  string

The current subject of the chat. The local user may change the subject of a chat using the SparkCommunications.Messenger#chatUpdate method.

When a subject change has been made by either the application or by another participant in the chat, a SparkCommunications.Messenger#event:chatUpdated event will be issued.