Property

Classes

Property

read-only static

MaxFileSize

The maximum size, in bytes, of a chat message attachment allowed by the SDK. The limit is 128MB.

Methods

chatEventSend(chatId, tag[, data]) → Promise

Send a chat event to all participants of a chat. Chat events are not stored in the chat's mailbox, and will only be delivered to participants who are connected to the BlackBerry Infrastructure at the time the event is sent. If the sender has other connected endpoints, they will receive the event. The sending endpoint never receives the event.

All arguments are copied.

Parameters

Name Type Optional Description

chatId

string

 

The identifier of a chat in which to send the event.

tag

string

 

The app-specified tag that indicates the type of event.

data

Object

Yes

The app-specified opaque data to send with the event, or undefined if not supplied. The 'data', encoded as JSON in UTF-8, must not exceed 71680 bytes (70 KB).

Throws

SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chatId is not known to the SDK.
  • TypeError

  • When an invalid parameter is provided.

  • When the data given encodes to a size greater than 71680 bytes (70 KB).
  • Returns

    Promise

    A Promise that will resolve to undefined if the event is sent, and will be rejected with a SparkCommunications.Error.TemporaryFailure or SparkCommunications.Error.PermanentFailure if the event is not sent.

    chatInvite(chatId[, invitees]) → Promise containing (Promise or Array of Promise)

    Issue or re-issue invites to users for an existing chat.

    If the chat is a 1:1 chat, and the other participant is still 'Pending' , then their invite will be re-issued. The invitees argument must be omitted for 1:1 chats.

    If the chat is an MPC, then two actions are possible:

    1. If the invitees argument is omitted (or explicitly undefined), then all 'Pending' participants will have their invites re-issued.

    2. If the invitees argument is specified, then each invitee is issued an invite regardless of SparkCommunications.Messenger.Participant.State. New invitees will have a new participant created for them.

    Any changes to the chat's participant list will be reflected through chatUpdated events as the invitees progress through the invite process.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier for the chat for which invites are to be issued.

    invitees

    (string or Array of string)

    Yes

    Not allowed for 1:1 chats. When specified, this may either be a single regId or an array of regIds. Specifying an empty array is allowed, but will have no effect. Providing the local user's regId will return an associated Promise, but it will be rejected immediately. Any regIds that are empty or aren't a string will also result in a Promise that is immediately rejected.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chat state is Defunct.
  • TypeError

    When the chat is a 1:1 and the invitees argument was specified.

    SparkCommunications.Error.NotFoundError

    When the given chatId is not known to the SDK.

    Returns

    Promise containing (Promise or Array of Promise)

    This function returns a Promise that may be resolved in one of two ways:

    1. When the invitees argument is a scalar string, the returned Promise will be resolved to another Promise that tracks the invitation process of the single invitee.
    2. When the invitees argument is an array, the returned Promise will be resolved to an array of Promises, each element of which tracks the invitation process of a single invitee. All invitees in the invitees argument will have an entry in the array of Promises at the same index that their regId was specified in the invitees argument. Specifying an empty invitees array will result in an empty array of Promises.
    Each invitee Promise will be resolved to the regId of that invitee, or will be rejected with an error.

    The returned Promise may be rejected if an error occurs that prevents initiating any invitations. Invitations cannot be initiated when the chat is in the states Defunct, or NoKey.

    In all rejection cases the error will be a SparkCommunications.Error.Error instance or one of its derivatives.

    chatKeysRequest(chatIds)

    Request the chat keys for the given chats. This should be used when a chat is in the NoKey state and the application is planning to use the chat. If the chat key is retrieved, the chat's state will advance to Waiting.

    Parameter

    Name Type Optional Description

    chatIds

    Array of string

     

    The list of chats to request keys for. Any chatIds that are unknown, or for chats not in the NoKey state are ignored.

    chatLeave(chatId) → Promise containing SparkCommunications.Messenger.Chat

    Leave the identified chat. The local user will leave the chat within the BlackBerry Infrastructure and will no longer be a participant in the chat. The chat will be removed from the chats tracked by the SDK and a chatRemoved event will be triggered once the chat is no longer being tracked.

    Parameter

    Name Type Optional Description

    chatId

    string

     

    The chat from which to unsubscribe.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    SparkCommunications.Error.NotFoundError

    When the identified chat is not known to the SDK.

    Returns

    Promise containing SparkCommunications.Messenger.Chat

    A promise to leave the chat. The chat returned in the resolved promise will reflect the chat state immediately before it is removed from the SDK.

    chatMessageDelete(chatId, messageId) → Promise

    Delete a chat message. This will send a delete for the message. The recipient of this message will mark the specified message as deleted in their message cache, and the message will be marked as deleted in the local message cache.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier of the chat containing the message to delete.

    messageId

    SparkCommunications.Messenger.MessageId

     

    The message identifier of the message to delete.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chat state is Defunct.
  • SparkCommunications.Error.NotFoundError

    When the message is not found.

    Returns

    Promise

    An empty promise on success. The promise is rejected if an error occurs sending the message.

    chatMessageDestroy(chatId[, messageId]) → Promise

    Destroy one or all messages previously sent by the local user in the given chat.

    When a single messageId is specified, its contents are cleared locally, a message is sent instructing all participants to clear the message's contents, and the BlackBerry Infrastructure removes the message from the chat. When the message has been destroyed, a chatMessageUpdated event will be emitted.

    When destroying all messages, the affected messages are removed locally, a message is sent instructing all participants to also remove all of the affected messages, and the BlackBerry Infrastructure also removes all of the affected messages from the chat. When all of the affected messages have been destroyed, a chatMessageListUpdated event will be emitted.

    Synchronous errors are reported via an exception being thrown. Asynchronous errors are reported via the returned Promise being rejected.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier of the chat containing the message(s) to destroy.

    messageId

    SparkCommunications.Messenger.MessageId

    Yes

    If specified, the message identifier of the single message to destroy. When omitted, all messages previously sent by the local user will be destroyed.

    Fires
    SparkCommunications.Messenger#event:chatMessageUpdated
    SparkCommunications.Messenger#event:chatMessageListUpdated
    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chat state is Defunct.
  • When a messageId is specified, but it is not suitable for recall. Only messages previously sent by the local user's identity may be recalled.
  • SparkCommunications.Error.NotFoundError

    When the chat is not found, or when a messageId is specified but it is not found in the chat's local cache.

    Returns

    Promise

    A promise that will be resolved once the steps outlined above have completed successfully. The promise will be rejected if any steps fail to complete successfully.

    chatMessageRead(chatId, messageId) → Promise

    Send a notification to the participants of the identified chat that the messages up to and including the identified message have been read by the local user.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier of a chat to be notified that the local user has read all messages up to the identified message ID.

    messageId

    SparkCommunications.Messenger.MessageId

     

    The message identifier of the most recent message in the identified chat that has been read by the local user.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chat is not in the Ready state.
  • SparkCommunications.Error.NotFoundError

    If the chat is not found or if the local user is not a participant in the chat.

    TypeError

    When the messageId supplied is not a MessageId instance or is empty.

    Returns

    Promise

    An empty promise on success. The promise is rejected if an error occurs sending the read notification.

    chatMessageSend(chatId, options) → Promise containing SparkCommunications.Messenger.ChatMessage

    Send a message to a chat.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier of a chat.

    options

    SparkCommunications.Messenger.ChatMessageSendOptions

     

    The options to use to send a message to the identified chat.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chatId is not known to the SDK.
  • When the chat state is Defunct.
  • TypeError

  • When an invalid parameter is provided.

  • When the data given encodes to a size greater than 71680 bytes (70 KB).
  • Returns

    Promise containing SparkCommunications.Messenger.ChatMessage

    The promise of the ChatMessage object that has been successfully sent and inserted into the chat.

    When the SDK fails to deliver the message to the BlackBerry Infrastructure, the message is discarded and one of the following errors is used to reject the promise:

  • SparkCommunications.Error.PermanentFailure to indicate that the posting of the message failed and must not be retried.
  • SparkCommunications.Error.Forbidden to indicate that the local user does not have sufficient permissions to post to the specified mailbox. The request must not be retried and steps should be taken to prevent future interaction with this mailbox within the infrastructure.
  • chatMessageUnwatch(chatId, messageId, callback)

    Stop watching a message. This frees the resources allocated in a call to chatMessageWatch.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier of the chat containing the message.

    messageId

    SparkCommunications.Messenger.MessageId

     

    The identifier or the message in the chat.

    callback

    WatcherCallback

     

    A callback to run when the message first becomes known, or changes.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    SparkCommunications.Error.NotFoundError

    When the chat is not found, the message is not found, or the callback is not a watcher on the message.

    chatMessageWatch(chatId, messageId, callback)

    Register to receive notifications about a message. Any time the message is modified, the callback will be run to notify the interested party. If a message is known to the system, the callback will immediately be run with the message as it is currently known. If the message is not known to the system, then the callback will be called for the first time when it is.

    Each callback function may be registered for more than one message, but may only be registered once per message.

    Note that it is important to unwatch a message when you are done with it. The watcher will be tracked until it is explicitly unwatched, which may result in preformance degradation if care is not taken to unwatch for each watcher.

    For an easier-to-use method which doesn't experience these resource leaks, this same information can be obtained from the events emitted by this class. However the events must be filtered by the caller to find desired events and the caller must rescan the entire message list after receiving a bulk message update event. As such, the performance of this API will be higher than could be achieved by listening to events.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier of the chat containing the message.

    messageId

    SparkCommunications.Messenger.MessageId

     

    The identifier or the message in the chat.

    callback

    SparkCommunications.Messenger#WatcherCallback

     

    A callback to run when the message first becomes known, or changes.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    SparkCommunications.Error.NotFoundError

    When the chat is not found.

    chatParticipantTimesGet(chatId[, regIds]) → Array of ParticipantTimes

    Get the delivered and read time details for the participants of the identified chat.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The chat identifier for the chat whose participant time details are to be retrieved.

    regIds

    Array of string

    Yes

    The regIds of the participants whose times are to be retrieved.

    When undefined, all participant time details will be returned.

    When specified, it is expected to be an array of regIds with an entry for each of the participants whose time details are to be retrieved.

    Duplicate regIds are ignored.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    TypeError

    When the regIds parameter is not an array of strings.

    SparkCommunications.Error.NotFoundError

    When the identified chat is not found.

    Returns

    Array of ParticipantTimes

    Returns the array of participant times with an entry for each of the participants requested if their data is available. The entries are in no particular order.

    Participants explicitly requested in the regIds parameter that have left the chat or are not known to be participants of the chat are omitted from the result.

    Participants explicitly requested in the regIds parameter that are known to the chat will be returned. Their delivered and read times will be defined if known or will be set to undefined if they are not known.

    chatStart(options) → Promise containing SparkCommunications.Messenger.PendingChat

    Creates a chat and invites users by their regId.

    Parameter

    Name Type Optional Description

    options

    SparkCommunications.Messenger.ChatStartOptions

     

    The object defining the options to be applied while creating the chat.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    (ReferenceError or TypeError)

    When an invalid parameter is provided.

    Returns

    Promise containing SparkCommunications.Messenger.PendingChat

    The promise of a PendingChat object created to track the chat details. When a single invitee is provided and an existing viable 1:1 chat exists with that user, the existing chat will be returned.

    chatTyping(chatId[, tag][, messageId]) → Promise

    Indicate to subscribers of a chat that the local user is typing.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier of a chat.

    tag

    string

    Yes

    The application-specified tag that indicates what kind of typing action the local user is performing.

    messageId

    SparkCommunications.Messenger.MessageId

    Yes

    If supplied, this is the ID of the 'chatMessage' the local user is taking the action against as indicated by the 'tag' field. This field is ignored when the 'tag' isn't present.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chatId is not known to the SDK.
  • TypeError

    When an invalid parameter is provided.

    Returns

    Promise

    A empty promise. The promise may be rejected if the typing notification fails to be sent.

    chatUpdate(chatId, update) → Promise containing SparkCommunications.Messenger.Chat

    Update certain fields of a chat.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The ID of the chat to update.

    update

    SparkCommunications.Messenger.ChatUpdateOptions

     

    The fields to update in the chat. Any unknown fields in the update will be ignored.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chat state is Defunct.
  • When the chatId is unknown.
  • When the update argument isn't an object.
  • When the update's subject isn't a string.
  • When the update's invitePolicy field isn't a SparkCommunications.Messenger.Chat.InvitePolicy value.
  • Returns

    Promise containing SparkCommunications.Messenger.Chat

    Returns a promise of a chat with the updated chat details. If the update would not effect any changes, a resolved promise of the chat will be returned. The promise will be rejected if updating the chat fails.

    fetchChatMessages(chatId[, options]) → Promise containing Array of SparkCommunications.Messenger.ChatMessage

    Return the messages associated with a specified chatId, including both messages that are cached locally, and possibly more retrieved from the infrastructure. This may initiate download of messages and will resolve once all messages have been cached or the criteria, specified in options, have been met. A chatMessageListUpdated event will be emitted when newly retrieved messages have been added to the local cache.

    The first time this function is called for a chat, the chat will move to the Restoring state. When enough messages have been retrieved to meet the criteria specified in the options, the chat will move to the Ready state. If more messages can be retrieved, another call to SparkCommunications.Messenger#fetchChatMessages can be made without affecting the state of the chat.

    Examples

    // If the chat contains 1000 messages and this function has not yet been
    // called for the given chatId, it will download and cache messages
    // 950-1000 and return them. If it is called again with the same
    // parameters, it will download and cached messages 900-950 from the
    // server and return messages 900-1000 from the cache.
    fetchChatMessages(chatId, {minFetchCount: 50})
    // If the chat contains 1000 messages and this function has not yet been
    // called for the given chatId, 1 or more requests will be made to
    // download messages from the server. If messages 0-800 had previously
    // been delivered to any endpoint for this user and marked read, then
    // it will retrieve messages 800-1000 and return them. If it is called
    // again with the same parameters, no new messages will be fetched and
    // the same cached messages will be returned.
    fetchChatMessages(chatId, {untilFirstRead: true})

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The chat for which messages are required.

    options

    SparkCommunications.Messenger.FetchChatMessagesOptions

    Yes

    Options to control how many messages are fetched. If not provided, all available messages will be fetched from the server and returned.

    Fires
    SparkCommunications.Messenger#event:chatMessageListUpdated
    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chat is in the Defunct, or NoKey states which don't allow fetching chat messages.
  • When invalid options are provided.
  • NotFoundError

    If the chat doesn't exist or the local user is not a participant.

    Returns

    Promise containing Array of SparkCommunications.Messenger.ChatMessage

    Returns a promise of all cached messages after possibly fetching some additional messages from the infrastructure.

    The promise may be rejected with one of the following errors:

  • SparkCommunications.Error.PermanentFailure to indicate an unspecified permanent failure. The request should not be retried.
  • SparkCommunications.Error.TemporaryFailure to indicate an unspecified temporary failure. The request may be retried later.
  • filterAdd(chatId) → Promise containing SparkCommunications.Messenger.Chat

    Add a chat into the filtered set. The adding is asynchronous. Once the adding is complete, this chat can be used as if it were initially specified in the filter during setup.

    Parameter

    Name Type Optional Description

    chatId

    string

     

    The chat to add to the filter list.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When not in filtered mode.
  • Returns

    Promise containing SparkCommunications.Messenger.Chat

    A promise containing the chat metadata. It may be rejected if an error occurs in retrieving the metadata, or the chat does not exist, but it will be added to the filtered set even in these cases.

    If an error occurs and the chat is only in the filter list, not the chat list, then it will not be possible to send messages in the chat. The two possible ways to enable sending of messages when in this state are to receive a message for the chat, or to add the chat to the filter list again, and receiving a resolved promise. The chat need not be removed from the filter list before attempting to add it again.

    filterRemove(chatId)

    Remove chat from the filtered set synchronously. After this call, the chat metadata and messages can no longer be retrieved, and any incoming message for the chat will be dropped. Note, removing all chats from the filter list simply results in an empty filter list - it does not disable filter mode.

    Parameter

    Name Type Optional Description

    chatId

    string

     

    The chat to add to the filter list.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When not in filtered mode.
  • getChat(chatId) → SparkCommunications.Messenger.Chat

    Retrieve the metadata for a single chat to which the user is subscribed.

    Parameter

    Name Type Optional Description

    chatId

    string

     

    The chat identifier for which to retrieve information.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    SparkCommunications.Error.NotFoundError

  • When an invalid chat identifier is specified

  • When the chat is not known to the SDK.
  • Returns

    SparkCommunications.Messenger.Chat

    The chat object associated with the given chatId.

    getChatMessage(chatId, messageId) → Promise containing SparkCommunications.Messenger.ChatMessage

    Retrieve a particular message associated with a specified chat. This will initiate download of the specified message immediately and resolve once it becomes available. The message state is not guaranteed to be correct, as it may be impacted by later messages which have not been retrieved. To get the complete state, call SparkCommunications.Messenger#fetchChatMessages specifying this message as the target message first, which will retrieve all messages that may impact this message's state.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The chat for which messages are required.

    messageId

    SparkCommunications.Messenger.MessageId

     

    The message identifier to retrieve.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chat state is Defunct.
  • SparkCommunications.Error.NotFoundError

    When the chat identified is not known to the SDK.

    Returns

    Promise containing SparkCommunications.Messenger.ChatMessage

    A Promise of the specified ChatMessage. The promise may be rejected if an error retrieving the chat message from the BlackBerry Infrastructure occurs.

    getChatMessages(chatId) → any

    Retrieve the messages associated with a specified chat. This returns the messages that have already been cached for the chat. It does not attempt to fetch new messages. In order to fetch new messages, call SparkCommunications.Messenger#fetchChatMessages.

    Parameter

    Name Type Optional Description

    chatId

    string

     

    The chat for which messages are required.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    SparkCommunications.Error.NotFoundError

    If the identified chat is not known to the SDK.

    Returns

    any

    Returns the list of currently cached messages for a chat. By default, this is of type SparkCommunications.Messenger.ChatMessage[], but it may be changed by using a custom messageStorageFactory.

    getChatMessageState(chatId, messageId) → Promise containing Array of Messenger.ChatMessageState

    Get the detailed state information for the identified outgoing message within the identified chat. Only the state of the current participants in the chat is reported upon. Because the messages are outbound the local user's regId is omitted from the result states.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier of the chat in which the message whose detailed status is to be gotten.

    messageId

    SparkCommunications.Messenger.MessageId

     

    The identifier of the message within the chat whose detailed status is to be gotten.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    SparkCommunications.Error.NotFoundError

    When the identified chat is not known to the SDK.

    Returns

    Promise containing Array of Messenger.ChatMessageState

    The promise of the detailed status for the identified message.

    getChats() → Array of SparkCommunications.Messenger.Chat

    Retrieve the list of chats of which the SDK is aware.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    Returns

    Array of SparkCommunications.Messenger.Chat

    An array of chats of which the SDK is aware. The order of elements is not unspecified.

    getMessageStorageFactory() → SparkCommunications.MessageStorageFactory

    Retrieve the message storage factory currently in use.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    Returns

    SparkCommunications.MessageStorageFactory

    The message storage factory currently in use.

    getTypingUsers(chatId) → Array of SparkCommunications.Messenger.Participant

    Call to retrieve the list of users who are currently typing in the identified chat.

    Parameter

    Name Type Optional Description

    chatId

    string

     

    The chat identifier for which the typing user list should be retrieved.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the identified chat is not known to the SDK.
  • Returns

    Array of SparkCommunications.Messenger.Participant 

    getUnreadCount(chatId) → Promise containing number

    Return the count of unread messages in a chat. This may require downloading messages from the network. If any messages are retrieved from the BlackBerry Infrastructure to satisfy this request, a chatMessageListUpdated event will be emitted when the local cache of chat messages has been updated.

    This count does not include messages that have the SparkCommunications.Messenger.ChatMessage.NeverCountUnread flag set.

    Parameter

    Name Type Optional Description

    chatId

    string

     

    The identifier of a chat for which to retrieve the message count.

    Fires
    SparkCommunications.Messenger#event:chatMessageListUpdated
    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chat state is Defunct.
  • SparkCommunications.Error.NotFoundError

    When the chat is not found or if the local user is not a participant in the chat.

    Returns

    Promise containing number

    The number of unread messages.

    isAdmin(chatId, regId) → boolean

    Check if a user is an admin in a chat.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier for the chat.

    regId

    string

     

    The regId of the participant.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    SparkCommunications.Error.NotFoundError

    When the identified chat is not known to the SDK or the given regId is not a participant in the chat.

    Returns

    boolean

    True if the specified user is an admin in specified chat. False if the user is a participant but not an admin in that chat.

    participantDemote(chatId, regId) → Promise

    Revoke admin privileges from a participant within a chat. This is only permitted when the local user is an admin for the chat, and the chat is a conference.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier for the chat.

    regId

    string

     

    The regId of the participant to demote in the chat. This cannot be the regId of the local user.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    SparkCommunications.Error.NotFoundError

    When the identified chat is not known to the SDK.

    SparkCommunications.Error.Error

    When the chat state is Defunct.

    Returns

    Promise

    An empty promise on success. The promise may be rejected when a failure revoking the participant's admin privileges occurs. Possible failures include:

    • the chat is a 1:1 chat
    • the regId is for the local user
    • the local user is not an admin for the chat

    participantPromote(chatId, regId) → Promise

    Promote the participant in the chat to be an admin. This is only permitted when the local user is an admin for the chat, and the chat is a conference.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier for the chat.

    regId

    string

     

    The regId of the participant to promote in the chat. This cannot be the regId of the local user.

    Throws

    SparkCommunications.Error.Error

    When the SDK is not set up.

    SparkCommunications.Error.NotFoundError

    When the identified chat is not known to the SDK.

    SparkCommunications.Error.Error

    When the chat state is Defunct.

    Returns

    Promise

    An empty promise on success. The promise may be rejected when a failure granting the participant admin privileges occurs. Possible failures include:

    • the chat is a 1:1 chat
    • the regId is for the local user
    • the local user is not an admin for the chat

    participantRemove(chatId, regId) → Promise

    Remove the participant from the chat. This is only permitted when the local user is an admin for the chat, and the chat is a conference.

    Parameters

    Name Type Optional Description

    chatId

    string

     

    The identifier for the chat to remove the participant from.

    regId

    string

     

    The regId of the participant to remove from the chat. This cannot be the regId of the local user.

    Throws

    SparkCommunications.Error.Error

  • When the SDK is not set up.

  • When the chat is a 1:1 chat.
  • When the regId is for the local user.
  • When the chat state is Defunct.
  • When the local user is not an admin for the chat.
  • SparkCommunications.Error.NotFoundError

    When the identified chat is not known to the SDK.

    Returns

    Promise

    An empty promise on success. The promise may be rejected when a failure to remove the participant occurs.

    Abstract types

    static

    ChatMessageSendOptions  Object

    An object to encapsulate the options to use when sending a message via the SparkCommunications.Messenger#chatMessageSend function.

    Parameter

    Name Type Optional Description

    message.fileData.progress

    function()

    Yes

    A callback to provide status of the upload. If specified, it will be passed objects implementing the ProgressEvent interface.

    Properties

    Name Type Optional Description

    tag

    string

     

    Indicates the type of message to be sent. It is not permitted to use one of SparkCommunications.Messenger.ChatMessage.ReservedTag

    content

    string

    Yes

    Holds the plain text content of the message, when the 'tag' has such a concept; otherwise omitted.

    The total size of the 'content' in UTF-8 is subject to a cumulative size limit when combined with the size of the 'data' object (encoded as JSON in UTF-8) and the size of the 'thumbData' attachment. These three fields combined must not exceed 71680 bytes (70 KB).

    data

    Object

    Yes

    This field contains opaque data managed by the application that is sent with the message. Unless specifically noted, the SDK does not examine or modify this JSON object. This can contain a single JSON object, or it can not exist at all. It cannot contain any other JSON type.

    Many 'tag' values have a corresponding object defined as a child of the 'data' object with a key equal to the 'tag'. All 'tags' with such a corresponding child of 'data' require that child to be present. Other tags have no such requirement. The 'data' object can also contain other key-value pairs independently from the 'tag'.

    The total size of the 'data' object (encoded as JSON in UTF-8) is subject to a cumulative size limit when combined with the size of the 'thumbData' attachment and the 'content' (also in UTF-8). These three fields combined must not exceed 71680 bytes (70 KB).

    thumbData

    (Uint8Array or Blob)

    Yes

    The raw bytes of a small file. The thumb data may contain no more than 56320 bytes (55 KB).

    The total size of the thumb data is subject to a cumulative size limit when combined with the size of the 'data' object (encoded as JSON in UTF-8) and the size of the 'content' (in UTF-8). These three fields combined must not exceed 71680 bytes (70 KB).

    thumbName

    string

    Yes

    A filename to associate with the thumbnail when a recipient stores it. On recipient mobile devices, the thumbnail data will be stored in a file with as similar a name to this as possible, subject to system and security rules. On recipient web clients, the exact name will be offered as a suggested filename. Because of filename rules on different platforms, only the following characters are guaranteed to be preserved:

    • [0-9a-zA-Z-.,_] (a regex character class)
    • Unicode code points at or above U+00A1

    fileData

    Object

    Yes

    The data of a file to be sent out-of-band, with a reference to it included in the message. A file that is attached in this manner may be retrieved by calling download() on the message.

    fileData.data

    (Uint8Array or Blob)

     

    The raw bytes of the file to be sent. This must not exceed the limit of SparkCommunications.Messenger.MaxFileSize.

    fileData.name

    string

    Yes

    A filename to associate with the file when a recipient stores it. On recipient mobile devices, the file will be stored with as similar a name to this as possible, subject to system and security rules. On recipient web clients, the exact name will be offered as a suggested filename. Because of filename rules on different platforms, only the following characters are guaranteed to be preserved:

    • [0-9a-zA-Z-.,_] (a regex character class)
    • Unicode code points at or above U+00A1

    isControl

    boolean

    Yes

    If true, this message is for control purposes versus for display purposes.

    neverCountUnread

    boolean

    Yes

    If true, this message never contributes to the chat's unread count.

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

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

    ref

    Array of SparkCommunications.Messenger.ChatMessage.Ref

    Yes

    An optional array of references to other messages in the chat. When omitted, the message will not reference any other messages. When present, a 'tag' value must only appear once in the array. Each 'messageId' must refer to an existing message in the chat. Any violation of these rules will cause SparkCommunications.Messenger#chatMessageSend to throw. Please refer to the Chat Message References documentation for further details on how references work and how they may be used.

    static

    ChatMessageState  Object

    The state of a chat message associated with a specific chat participant. This describes a single element of the array returned by SparkCommunications.Messenger#getChatMessageState

    Properties

    Name Type Optional Description

    regId

    string

     

    The regId of the chat participant.

    state

    SparkCommunications.Messenger.ChatMessage.StateValue

    Yes

    The string indicating whether or not the participant has acknowledge the message as delivered or read. This attribute is undefined if there is no delivery state available for this message associated with the user.

    static

    ChatStartOptions  Object

    An object to encapsulate the options used to start a chat via SparkCommunications.Messenger#chatStart.

    Properties

    Name Type Optional Description

    subject

    string

    Yes

    The subject of the chat. This may be empty. When unspecified, it will default to an empty string. This field has a maximum size of 128 code points. Values larger than 128 code points will be truncated. If an existing 1:1 chat is chosen, and this subject differs, the existing chat's subject will be updated.

    isOneToOne

    boolean

    Yes

    When truthy, the chat is the singular 1:1 chat between the local user and the other party. The SDK ensures that only one such non-Defunct chat per remote party will exist at a time. Otherwise, the chat is a multi-party chat, even if there are fewer than two remote parties.

    invitees

    (Array of String or String)

    Yes

    The array of regIds of users being invited to join the chat once it has been created, or a single string to invite a single user. When isOneToOne is truthy, this list must contain a single regId, either in string form or as a single element array. Otherwise, it is optional or can be specified with 0 or more regId entries.

    When a single string is passed, a single Promise will be returned for the invite, rather than an array of promises.

    Creating a OneToOne chat with the regId of the local user is not supported. Creating a Conference where the regId of the local user is one of the invitees will result in the invite for this regId being rejected.

    invitePolicy

    SparkCommunications.Messenger.Chat.InvitePolicy

    Yes

    The policy that controls who may invite participants to the chat. This only applies when the 'isOneToOne' field is falsy. The default is 'ParticipantsOnly'

    data

    Object

    Yes

    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).

    When not defined, the chat data will default to an empty object.

    privateData

    Object

    Yes

    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).

    When not defined, the private data will default to an empty object.

    static

    ChatUpdateOptions  Object

    An object to encapsulate the fields of a chat that may be updated via SparkCommunications.Messenger#chatUpdate. Attempting to change any field to its existing value will be ignored.

    Properties

    Name Type Optional Description

    subject

    string

    Yes

    The subject for a chat is a textual description and must be limited to 128 codepoints. It will be truncated if it is longer. It may be set to null to remove the current subject. If undefined, the current subject will not be changed.

    invitePolicy

    SparkCommunications.Messenger.Chat.InvitePolicy

    Yes

    The policy that controls who may invite participants to the chat. This is ignored if the chat's isOneToOne field is true. If undefined, the current invite policy will not be changed.

    data

    Object

    Yes

    The application data object that is synchronized to all chat participants. If undefined, the current application data will not be changed.

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

    For a full description of this field and its intended use, please refer to SparkCommunications.Messenger.ChatStartOptions.

    privateData

    Object

    Yes

    The application data object that is synchronized to all the local user's endpoints. If undefined, the current private data will not be changed.

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

    For a full description of this field and its intended use, please refer to SparkCommunications.Messenger.ChatStartOptions.

    static

    FetchChatMessagesOptions  Object

    An object to encapsulate the options available for use when fetching chat messages via SparkCommunications.Messenger#fetchChatMessages. Only one option may be used in each request. Messages will be fetched until the specified condition has been met or all messages have been fetched and cached.

    Properties

    Name Type Optional Description

    minFetchCount

    number

    Yes

    The number of additional messages to retrieve from the infrastructure and add to the cache. May be 0 to retrieve no new messages.

    minMessageId

    SparkCommunications.Messenger.MessageId

    Yes

    Fetch messages from the infrastructure and add them to the cache until the identified message or earlier messages have been included.

    untilFirstDelivered

    Boolean

    Yes

    Fetch messages from the infrastructure and add them to the cache until the most recent message marked as delivered is included.

    untilFirstRead

    Boolean

    Yes

    Fetch messages from the infrastructure and add them to the cache until the most recent message marked as read is included.

    static

    ParticipantTimes  Object

    An object to encapsulate the time details for the last known date/time the participant has acknowledged delivery of messages or read a message within a chat.

    Properties

    Name Type Optional Description

    regId

    string

     

    The regId of the participant whose time details are being reported.

    delivered

    Date

    Yes

    The last date and time the participant has acknowledged delivery of a message within the chat. This the field will be present, but undefined if this value is not known.

    read

    Date

    Yes

    The last date and time the participant has indicated they have read messages within the chat. This will be undefined if this value is not known.

    static

    PendingChat  Object

    An object to provide the details of a chat that has been created via SparkCommunications.Messenger#chatStart and report on the result of any invites that were sent as part of the chat creation.

    Properties

    Name Type Optional Description

    chat

    SparkCommunications.Messenger.Chat

     

    This is the chat object, with chat details

    invites

    (Array of Promise or Promise)

     

    An array of promises for the outstanding invites for the invitees, in the case where an array of users are invited, or a single Promise, in the case where a single regId is invited, rather than an array. These promises will be resolved once the invites have been sent out and the grants have been issued.

    WatcherCallback(message)

    This callback is run in response to an update to a message which is watched by the application.

    Parameter

    Name Type Optional Description

    message

    any

     

    The new value of a message being watched.

    Events

    appMessageReceived  SparkCommunications.Event.AppMessageReceived

    The event used to relay an application message that has been received. For more information on application messages, please refer to the SparkCommunications.Messenger.AppMessage documentation.

    These messages are not retained by the SDK.

    chatAdded  SparkCommunications.Event.ChatAdded

    The event used to indicate that the local user is now a participant in the given chat. Consumption of messages may proceed.

    This event is emitted whenever a new chat becomes known to the SDK. For example, this event can be emitted when:

    chatEvent  SparkCommunications.Event.ChatEvent

    The API event used to indicate that a chat event has arrived. These events are emitted by the Spark Communications SDK as they occur and are not retained within the Spark Communications SDK in any way.

    chatMessageAdded  SparkCommunications.Event.ChatMessageAdded

    The event used to indicate that a chat message has been added to the identified chat. For example, this event can be emitted when:

    chatMessageListUpdated  SparkCommunications.Event.ChatMessageListUpdated

    The event used to indicate that a bulk change to the chat message list has been made. For example, this event can be emitted when:

    chatMessageUpdated  SparkCommunications.Event.ChatMessageUpdated

    The event used to indicate that a message within a chat has been updated. For example, this event can be emitted when:

    • a message's delivery or read state has changed, or
    • a message is deleted by the local user, or
    • a message is recalled, or
    • a message is referenced by a new message in the chat.

    chatRemoved  SparkCommunications.Event.ChatRemoved

    The event used to indicate that the SDK has removed all data associated with the given chat. The chat details and messages are no longer accessible to the local user via the SparkCommunications.Messenger interfaces. Only chats in which the user is no longer a participant will be removed.

    Once this event is emitted for a chat, no further events related to the chat will be emitted.

    chatTyping  SparkCommunications.Event.ChatTyping

    The event used to indicate that a chat participant has started or stopped typing in the identified chat. The list of typing users for a chat may be retrieved by calling SparkCommunications.Messenger#getTypingUsers.

    chatUpdated  SparkCommunications.Event.ChatUpdated

    The event used to indicate that one or more properties of a chat, including its participant list has changed.

    This event will be emitted whenever a change to a chat's properties becomes known to the SDK. For example, this event can be emitted when:

    • SparkCommunications.Messenger#chatUpdate completes successfully, or
    • another endpoint for the user has updated the chat, or
    • another user has update the chat, or
    • the participant list of the chat has changed because a participant has joined or left the chat or has been updated.

    userKeysChanged  SparkCommunications.Event.UserKeysChanged

    The event indicating that the keys for a user have changed. This is not sent when the user gains their initial set of keys.