BBM Data Service Core (BBMDS-Core) - bbmcore to application protocol

Contents

Introduction

Copyright 2018 BlackBerry. All rights reserved.

The entity connected to bbmcore as a client of the BBMDS protocol is known within this documentation as "your application".

"Incoming" messages refer to messages from bbmcore to your application. "Outgoing" messages refer to messages from your application to bbmcore. Lists are always managed by bbmcore, with potential changes sometimes requested by your application via general-purpose and/or case-specific messages, and actual changes reflected in "incoming" messages from bbmcore via List Management Messages.

There is no incoming flow control. bbmcore will send data to your application as fast as it can and will continue sending even if your application is not able to read it.

Your application must resynchronize all BBMDS-sourced data when the connection between itself and bbmcore is re-established, such as when bbmcore starts or restarts. Such re-establishment events will also be used by bbmcore to explicitly notify your application that its entire state may have changed, such as during a device switch or when the setup state changes.

When resynchronization is triggered, it indicates that an unknown number of messages from bbmcore may have been lost. Your application is required to re-request any cached mutable state that was obtained from bbmcore. The application is not required to re-request the entire state of bbmcore. It only needs to re-request information that is currently cached.

Elsewhere in this document, we will describe the responses from bbmcore as being unconditional, with statements like "When your application sends X, bbmcore will respond with Y". This document does not explicitly state the qualification "unless resynchronization occurs" since it always applies. Although these cases are supposed to be infrequent, it is possible that any incoming message may be dropped at any time, in which case a resynchronization will always be triggered afterward. Your application must be capable of dealing with these situations.

Strict validation of input against the schema is not recommended because bbmcore reserves the right to pass deprecated, removed, or otherwise undocumented fields in any messages to your application for its own purposes. Your application must not use or examine fields not documented here.

Notation

In this document, the term "iff" is used as a shorthand for "if and only if".

BlackBerry Spark Communications Services Documentation

This documentation only covers the API constructs supported by BlackBerry Spark Communications Services.

Versions

Version information in the 'since' fields in various schema objects is a rough human-readable indicator of when that object was added to the protocol. The versioning is really informational only and isn't part of the protocol's semantics.

Protocol versions are expressed as strings of the form "Rn" where n is a positive integer. These release version codes correspond to the values in the BlackBerry Spark Communications Services Developer Guide release notes.

URIs

This section describes the URIs used in this protocol. All URIs used by Spark are case-sensitive and have a lower-case prefix identifying the entity type.

Format Description Generated By
bbmpim://user/id/value A locally identified "user" record, known to the device. These URIs are usable by BBMDS-Core wherever a "user" URI is specified. bbmcore

All Messages

authToken

NameauthToken
Since2016.03
DirectionOutgoing

Your application uses this message to provide bbmcore with an updated authToken value. See the 'authTokenState' global for more information on when to use this message.

This message also will trigger setup when it has not yet been started within bbmcore and bbmcore is waiting for the initial (or subsequent) authToken value. See the documentation for the 'setupState' 'NotRequested' enumeration for more information on how setup proceeds after being started by 'authToken'.

Attributes:
NameTypeRequiredSinceLoggableDescription
authTokenstringRequired2016.03NoThe token that can be used by the BlackBerry Infrastructure to authenticate and authorize use of the BlackBerry Infrastructure to the identified user. This value will be passed transparently through the BlackBerry Infrastructure.
userIdstringRequired2016.03NoThe user's id within the ecosystem. This value will be passed transparently through the BlackBerry Infrastructure. This value must not change after it has been passed to bbmcore. Passing a different value will cause bbmcore to forget all information associated with the current Spark Communications identity by deleting all data and stopping.
Examples:
[
    {
        "authToken": {
            "authToken": "WW91J3JlIHRob3JvdWdoIQ==", 
            "userId": "BlackBerryUser"
        }
    }, 
    {
        "authToken": {
            "authToken": "    why?   ", 
            "userId": "\u0000Very\nstrange\t user #id"
        }
    }
]

chatEvent

NamechatEvent
SinceR7
DirectionIncoming

This message is sent to your application by bbmcore when a chat event is received for a chat in which the local user is a current participant. See 'chatEventSend' for more information about chat events.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR7YesThe id of the chat in which the chat event was received.
dataobjectOptionalR7Yes

This field contains opaque data managed by your application that was received with the chat event. Bbmcore 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.

flagsstringOptional (Default=)R7YesCompact read-only flags about the chat event. Each flag that is 'true' has its corresponding letter present in the string. Each flag that is 'false' has its corresponding letter omitted from the string. The letters will always be provided in alphabetical order.
Flag NameLetterSinceDescription
unverified U R7 The event's signature was not verified as being from the claimed sender. Despite this, the content of the event is made available to be processed or ignored as your application sees fit.
senderUriuser keyRequiredR7Yes

Holds the user URI of the sender of this chat event. See the URIs section for information on the URI format.

The local user can receive a chat event from one of its other other endpoints, so this can refer to the local user.

tagstringRequiredR7YesYour application-specified tag that indicates what kind of chat event has been received.
Examples:
[
    {
        "chatEvent": {
            "senderUri": "bbmpim://user/id/12", 
            "tag": "Heartbeat", 
            "flags": "", 
            "chatId": "2824"
        }
    }, 
    {
        "chatEvent": {
            "flags": "U", 
            "senderUri": "bbmpim://user/id/0", 
            "tag": "Location", 
            "data": {
                "Location": {
                    "lat": 0, 
                    "place": "Home", 
                    "long": 0
                }
            }, 
            "chatId": "7"
        }
    }
]

chatEventSend

NamechatEventSend
SinceR7
DirectionOutgoing

With this request, your application asks bbmcore to send a chat event to all participants of an existing chat. The chat event will not be stored persistently in the chat mailbox for later delivery and will be sent only to the endpoints of chat participants that are currently connected to the BlackBerry Infrastructure. Chat events are either sent immediately or they fail immediately, and they do not interact with the flow or queue of other outgoing messages within a chat. Endpoints that are not connected when this message is sent will never receive a copy of this message. There is no mechanism to tell if a chat event is delivered to any or all chat participants.

These properties make chat events cheaper in terms of storage and network usage than messages sent with 'chatMessageSend'.

The local user's other connected endpoints can and will receive their own identity's chat events. This endpoint will never receive its own chat events.

This mechanism is useful in cases where applications want to send frequent, timely information to all participants that has no value other than in the moment. For example, an application might want to send live location information from one or more participants to all other participants.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR7YesThe id of the chat in which the chat event is to be posted.
dataobjectOptionalR7Yes

This field contains opaque data managed by your application that is sent with the chat event. Bbmcore 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.

The total size of the 'data' object (encoded as JSON in UTF-8) must not exceed 71680 bytes (70 KB).

tagstringRequiredR7YesYour application-specified tag that indicates what kind of chat event is being sent.
Examples:
[
    {
        "chatEventSend": {
            "tag": "Heartbeat", 
            "chatId": "2824"
        }
    }, 
    {
        "chatEventSend": {
            "tag": "Location", 
            "data": {
                "Location": {
                    "lat": 0, 
                    "place": "Home", 
                    "long": 0
                }
            }, 
            "chatId": "7"
        }
    }
]

chatHide

NamechatHide
SinceR4
DirectionOutgoing

Your application sends this message to bbmcore to mark a chat as hidden. bbmcore will automatically un-hide the chat the next time a message is added to its history.

For a chat that can never become unhidden (such as some chats in the 'Defunct' state), bbmcore will treat a 'chatHide' action as if it were 'chatLeave' to ensure the chat does not linger, forever invisible to the user.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdsarrayRequiredR4YesAn array of ids of the chats that are to be hidden.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
chat keyRequiredR4YesThe id of a chat that is to be hidden.
Examples:
[
    {
        "chatHide": {
            "chatIds": [
                "6"
            ]
        }
    }, 
    {
        "chatHide": {
            "chatIds": [
                "2824", 
                "12"
            ]
        }
    }
]

chatInvite

NamechatInvite
SinceR3
DirectionOutgoing

Send this message to bbmcore to invite one or more participants to an existing chat or resend existing chat invitations to invitees that have not yet joined.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdstringRequiredR3YesThe id of the existing chat to invite the invitees to.
inviteesarrayRequiredR3Yes

The list of invitees to invite to the chat. If any of the specified invitees are already in the process of being invited by this endpoint, invitations are reissued to them (and only them).

Specify an empty list to reissue all of this endpoint's unfulfilled invitations for the chat. When 'chatInvite' is sent for a 1:1 chat, the invitees list must be empty (since the only viable action for a 1:1 chat is to reissue an unfulfilled invitation).

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectRequiredR3NoEach invitee may be identified by a user URI or regId. Entries without one of these identifiers will be ignored.
NameTypeRequiredSinceLoggableDescription
regIdnumber (signed 64-bit int)OptionalR3Yes

The regId of a Spark Communications user to invite to the chat. This will create a new user if the regId isn't already known to bbmcore.

Ignored iff 'userUri' is specified.

userUriuser keyOptionalR3YesThe URI of an existing user to invite to the chat. When present, the 'regId' is ignored.
Examples:
[
    {
        "chatInvite": {
            "invitees": [
                {
                    "userUri": "bbmpim://user/id/4736"
                }
            ], 
            "chatId": "7"
        }
    }, 
    {
        "chatInvite": {
            "invitees": [
                {
                    "userUri": "bbmpim://user/id/4736"
                }, 
                {
                    "regId": 2783476
                }
            ], 
            "chatId": "2347"
        }
    }, 
    {
        "chatInvite": {
            "invitees": [
                {
                    "regId": 123456789, 
                    "pin": "abcd1234"
                }, 
                {
                    "regId": 5583673, 
                    "displayName": "Sue Smith", 
                    "pin": "11111111"
                }, 
                {
                    "userUri": "bbmpim://user/id/4736"
                }
            ], 
            "chatId": "887"
        }
    }, 
    {
        "chatInvite": {
            "invitees": [], 
            "chatId": "1"
        }
    }
]

chatKey

NamechatKey
SinceR3
DirectionIncoming

Sent by bbmcore in response to a 'chatKeyExport' request.

This message will not be sent by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequiredR3YesThe cookie used to track this response to its 'chatKeyExport' request.
keystringRequiredR3NoThe unpadded base64url-encoded chat key.
mailboxIdstringRequiredR3YesThe mailboxId of the chat key for use in external storage.
Examples:
[
    {
        "chatKey": {
            "cookie": "823gudb3d2qwe", 
            "key": "Y2hhdEtleTEyMw", 
            "mailboxId": "123"
        }
    }
]

chatKeyExport

NamechatKeyExport
SinceR3
DirectionOutgoing

Request that bbmcore return the locally stored chat key for a chat. Iff the 'chatId' exists, this will trigger a 'chatKey' response.

To avoid event loops, your application must only react with 'chatKeyExport' to changes of the chat's 'keyState' to 'Export'. Your application must not react to updates from bbmcore that indicate the chat's 'keyState' is 'Export' when the chat's 'keyState' was already known to your application to be 'Export'. In other words, your application must not export keys unless the chat's 'keyState' is actually changing or being learned for the first time. By following this rule, failed exports will not result in tight event loops and will allow retries (at a minimum on application restart, but also whenever bbmcore decides to toggle the state).

The chat's 'keyState' is not updated in response to this message, and thus must be set to 'Synced' via a 'requestListChange' once the key is successfully stored externally.

This message will be ignored by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR3YesThe id of the chat to get the key for.
cookiestringRequiredR3YesThe cookie used to track this request to a 'chatKey' response.
Examples:
[
    {
        "chatKeyExport": {
            "cookie": "823gudb3d2qwe", 
            "chatId": "123"
        }
    }
]

chatKeysImport

NamechatKeysImport
SinceR3
DirectionOutgoing

Request that bbmcore set one or more chat keys.

Your application should try to include keys for as many chats as possible in a single 'chatKeysImport' request (within BBMDS message size limits) for greater efficiency.

If no chat with a given 'mailboxId' exists, or the chat is not waiting for a key, the request is ignored.

If a chat's key is imported successfully, the chat's 'keyState' will be updated to 'Synced', and if the chat's 'state' was 'Waiting' (for the key) it will be updated to 'Ready'. If the import fails, the chat's 'keyState' and 'state' will remain unchanged.

To avoid event loops, your application must only react with 'chatKeysImport' to changes of a chat's 'keyState' to 'Import'. Your application must not react to updates from bbmcore that indicate the 'keyState' is 'Import' when the 'keyState' was already known to your application to be 'Import'. When your application first learns of a chat (such as after starting up) and its 'keyState' is 'Import', your application should consider that a change and can react to it with 'chatKeysImport'. In other words, your application must not import keys unless the 'keyState' is actually changing or being learned for the first time. By following this rule, failed imports will not result in tight event loops and will allow retries (at a minimum on application restart, but also whenever bbmcore decides to toggle the state).

This message will be ignored by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
keysarrayRequiredR3YesThe list of chat keys to set.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectRequiredR3YesThe key for the chat.
NameTypeRequiredSinceLoggableDescription
keystringRequiredR3NoThe unpadded base64url-encoded chat key.
mailboxIdstringRequiredR3YesThe mailboxId of the chat key for use in external storage.
Examples:
[
    {
        "chatKeysImport": {
            "keys": [
                {
                    "key": "Y2hhdEtleW1ieDEyMw==", 
                    "mailboxId": "mbx123"
                }, 
                {
                    "key": "Y2hhdEtleW1ieDMyMQ==", 
                    "mailboxId": "mbx321"
                }
            ]
        }
    }
]

chatKeysImportFailure

NamechatKeysImportFailure
SinceR4
DirectionIncoming

Indicates that one or more chat keys received in 'chatKeysImport' failed to import.

This message will not be sent by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
mailboxIdsarrayRequiredR4YesThe list of mailboxIds that failed to import.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
stringRequiredR4YesThe mailboxId that failed to import.
Examples:
[
    {
        "chatKeysImportFailure": {
            "mailboxIds": [
                "mbx1", 
                "mbx3"
            ]
        }
    }
]

chatLeave

NamechatLeave
SinceR4
DirectionOutgoing

This will first hide the chat (see 'chatHide'), and then begin the process of leaving the chat, eventually resulting in bbmcore deleting all local data related to the chat, notifying the other participants of our departure, and removal of the chat from the 'chat' list. A chat that is being left will not gain any additional incoming or outgoing messages.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdsarrayRequiredR4YesAn array of ids of the chats that are to be left.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
chat keyRequiredR4YesThe id of a chat that is to be left.
Examples:
[
    {
        "chatLeave": {
            "chatIds": [
                "6"
            ]
        }
    }, 
    {
        "chatLeave": {
            "chatIds": [
                "2824", 
                "12"
            ]
        }
    }
]

chatMessageDelete

NamechatMessageDelete
SinceR4
DirectionOutgoing

Your application sends this message to bbmcore to request that a chat message be deleted for all the endpoints of the user's identity. Any content or foreign keys for the deleted message are removed. Both incoming and outgoing messages may be deleted. If a message that matches the given chatId and message id is found, bbmcore will respond with an update for the message.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR4YesThe identifier of the chat containing the message to be deleted.
idstring (unsigned 64-bit int in base 10)RequiredR4YesThe unique identifier for the message to be deleted within the provided chat.
Examples:
[
    {
        "chatMessageDelete": {
            "id": "256789", 
            "chatId": "64"
        }
    }
]

chatMessageDestroy

NamechatMessageDestroy
SinceR6
DirectionOutgoing

Request that one or many 'chatMessage' entries previously sent by the local user's identity be recalled and destroyed from:

An outgoing message can be destroyed regardless of its delivery state, except that requests to destroy a 'chatMessage' in 'state' 'Failed' will be ignored.

The 'chatMessage' 'recall' state will be updated to reflect the state of the process on the sender endpoint and all recipients' endpoints. There is no guarantee that the recipients have not read the message prior to it being destroyed.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR6YesThe id of the chat containing the message to be recalled and destroyed.
messageIdchatMessage keyOptionalR6Yes

When present, this is the id of an individual 'chatMessage' that is to be recalled and destroyed within the indicated chat. Only "content" messages can be identified with a 'messageId'. Thus, 'chatMessage' entries with 'tag' values such as 'Admin', 'Gap', 'Join', 'Leave', 'Remove', 'Shred', and 'Subject' cannot be destroyed by indiciating their individual 'messageId'.

When not present, all 'chatMessage' entries that have been previously sent by the local user's identity will be recalled and destroyed. Plus, all non-"content" messages (including control messages with the 'tag' values listed above) that have been sent by the local user's identity within the indicated chat will be destroyed from the BlackBerry Infrastructure. Thus, endpoints that have not yet received those control messages shall never receive them or make them available to your application.

Examples:
[
    {
        "chatMessageDestroy": {
            "messageId": "256789", 
            "chatId": "765"
        }
    }
]

chatMessageDetach

NamechatMessageDetach
Since2017.02
DirectionOutgoing

Request that bbmcore remove the 'file' and/or 'thumb' attachments locally for a single 'chatMessage'. This message does not change the 'chatMessage' for any other endpoints or identities.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequired2017.02YesThe identifier of the chat containing the 'chatMessage'.
detachFilebooleanOptional (Default=False)2017.02Yes

Iff present and true, any 'file' attachment will be deleted from the 'chatMessage' iff the 'fileState' of that message is 'Done'. If the 'fileState' is anything else, no 'file' detachment is performed.

After detachment, the 'file' field will no longer be present on the 'chatMessage', and the 'fileState' will be set to 'Available'. Thus, in the case of a completed download or upload, the file attachment can be subsequently downloaded by issuing 'chatMessageFileDownload'.

The primary reason to detach an upload is to free storage space for old completed uploads that used a 'filePolicy' of 'Move'.

The 'chatMessage' 'tag' does not matter and will not change.

detachThumbbooleanOptional (Default=False)2017.02Yes

Iff present and true, any 'thumb' attachment will be deleted from the 'chatMessage'. The 'thumb' field will no longer be present on the 'chatMessage'.

The 'chatMessage' 'tag' does not matter and will not change.

messageIdstring (unsigned 64-bit int in base 10)Required2017.02YesThe identifier of the 'chatMessage' within the chat identified by 'chatId'.
Examples:
[
    {
        "chatMessageDetach": {
            "detachFile": false, 
            "messageId": "6510", 
            "detachThumb": true, 
            "chatId": "64"
        }
    }, 
    {
        "chatMessageDetach": {
            "detachFile": true, 
            "messageId": "1541", 
            "detachThumb": false, 
            "chatId": "64"
        }
    }, 
    {
        "chatMessageDetach": {
            "detachFile": true, 
            "messageId": "6581", 
            "detachThumb": true, 
            "chatId": "64"
        }
    }
]

chatMessageFileDownload

NamechatMessageFileDownload
Since2017.02
DirectionOutgoing

Request that bbmcore start downloading a file attachment for a single 'chatMessage'.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequired2017.02YesThe identifier of the chat containing the 'chatMessage'.
messageIdstring (unsigned 64-bit int in base 10)Required2017.02Yes

The identifier of the 'chatMessage' within the chat identified by 'chatId'.

This 'chatMessage' must have a 'fileState' of either 'Available' or 'FailedAvailable' or this request will be ignored by bbmcore.

The 'chatMessage' 'tag' does not matter.

Examples:
[
    {
        "chatMessageFileDownload": {
            "messageId": "6510", 
            "chatId": "64"
        }
    }
]

chatMessageRead

NamechatMessageRead
SinceR4
DirectionOutgoing

Your application sends this message to bbmcore to notify it that incoming messages have been read by the local user. All unread incoming messages in the chat with a 'messageId' less than or equal to that of the specified 'messageId' will be marked as read.

Note that when a chat's 'numUnread' field is zero, then 'chatMessageRead' will have no effect on that chat because that means the chat has no unread incoming messages.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR4YesThe id of the chat containing the message referred to by 'messageId'.
messageIdchatMessage keyRequiredR4YesThe largest 'messageId' (within the chat referred to by 'chatId') of the messages that are to be marked as read by the local user.
Examples:
[
    {
        "chatMessageRead": {
            "messageId": "786", 
            "chatId": "2824"
        }
    }
]

chatMessageSend

NamechatMessageSend
Since2017.02
DirectionOutgoing

Send a new message within an existing chat. This will result in a 'listAdd' on the 'listChatMessage' list, and the message will be sent to the BlackBerry Infrastructure and forwarded to the other endpoints that are participating in the chat.

Sending a new message within a 1:1 chat before the invited party has joined can trigger the invitation to be reissued when other conditions are also met. This mechanism achieves a partially automatic user-speed retry of 1:1 chat invitations. There is no automatic mechanism for non-1:1 chats, but invitations for all types of chats can be reissued upon request via 'chatInvite'.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequired2017.02YesThe identifier of the chat in which to send the message.
contentstringOptional2017.02No

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

This field may not contain more than 2000 Unicode code points.

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 'thumb' attachment. These three fields combined must not exceed 71680 bytes (70 KB).

dataobjectOptional2017.02Yes

This field contains opaque data managed by your application that is sent with the message. Unless specifically noted, bbmcore 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 'thumb' attachment and the 'content' (also in UTF-8). These three fields combined must not exceed 71680 bytes (70 KB).

NameTypeRequiredSinceLoggableDescription
filestringOptional2017.02No

A path to a large file that is not carried in the message. This file is uploaded by bbmcore automatically.

A maximum file size limit of 128 MB is imposed by bbmcore. If your application attempts to attach a file that exceeds this limit, the 'message' will be added to the chat in the 'Failed' state. The size limit may change in future versions. Receiving clients that encounter files that are larger than their maximums will not download them.

filePolicystringOptional2017.02YesThis enumeration tells bbmcore what to do with the file referenced by 'file'. For all other documentation, please see 'thumbPolicy'.

This field is an enumeration.

MemberDescription
Copy See 'thumbPolicy'.
Delete See 'thumbPolicy'.
Move See 'thumbPolicy'.
refarrayOptionalR5Yes

A 'chatMessage' can reference other messages or be referenced by other messages.

All references are directional and known to both messages involved. If message A references message B, then A has an entry in its 'ref' array with the 'messageId' of B, and B has an entry in its 'refBy' array that counts the reference from A.

Each reference in the 'ref' array has an application-specified 'tag' that indicates what kind of reference it is. A single message can only have one 'ref' for each tag string. Your application uses 'tag' strings to allow multiple different kinds of references between messages. For example, a message could both 'Quote' one message and 'Edit' another.

Each reference in the 'refBy' array has the same application-specified tag. A single message can have multiple references to it with the same 'tag'. To find all messages that refer to a given message, use 'requestListMatching' with the 'tag' and the 'messageId' of the referred-to message. Because the number of incoming references to a message can be large, only the most recent referring message is identified by 'newestRef' in 'refBy', along with a count of the total number of referring messages.

When there are no references to any other messages, the 'ref' field is omitted.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectRequiredR5YesEach element of the 'ref' array represents a single reference to another 'chatMessage'.
NameTypeRequiredSinceLoggableDescription
messageIdchatMessage keyRequiredR5YesThe messageId being referenced. If this contains the id of an element that does not currently exist in the 'chatMessage' list, then this 'ref' element will be ignored.
tagstringRequiredR5YesYour application-specified tag that indicates what kind of reference it is. A single 'chatMessage' can only have one 'ref' for each tag string. If a tag string appears more than once, subsequent instances are ignored.

This field is an enumeration.

MemberDescription
Edit This message edits the referenced message.
Quote This message quotes the referenced message.
Thread This message belongs to a thread that has the referenced message as its parent.
tagstringRequired2017.02Yes

Indicates the type of message. Your application may include any arbitrary value in the 'tag' field that is meaningful to it, with one exception: bbmcore will ignore any 'chatMessageSend' from your application that uses one of the reserved tags: 'Join', 'Leave', 'Subject', 'Gap', 'Shred', 'Clear', 'Admin', or 'Remove'.

This field is an enumeration.

MemberDescription
Text The message contains plain text content. This tag requires 'content'
thumbstringOptional2017.02No

A path to a small file that is carried in the message.

The thumb file may contain no more than 56320 bytes (55 KB).

The total size of the thumb file 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).

thumbPolicystringOptional2017.02YesThis enumeration tells bbmcore what to do with the file referenced by 'thumb'. If not provided a default of Copy is used. Note that in the case of Delete and Move, bbmcore _will_ _not_ delete the source file if the request was invalid to the point of being indecipherable, or if bbmcore lacks permissions to delete the file (including when the source file is open and the OS doesn't permit open files to be deleted).

This field is an enumeration.

MemberDescription
Copy Leave the source file unmodified (and don't delete it). Your application retains ownership of the file. The path in a resulting chatMessage record will refer to the original source file.
Delete Delete the source file when bbmcore no longer requires it in order to complete the operation. The path in a resulting chatMessage record will point to the moved file (which is owned by bbmcore and will be deleted).
Move Move the source file to an internal location and retain it for the life of the associated chatMessage entry. The path in a resulting chatMessage record will point to the moved file (which is owned by bbmcore).
Examples:
[
    {
        "chatMessageSend": {
            "content": "Hello, folks. This is a test.", 
            "tag": "Text", 
            "chatId": "436"
        }
    }, 
    {
        "chatMessageSend": {
            "thumb": "/picture/funny_cat_small.jpg", 
            "content": "Cats are funny!", 
            "filePolicy": "Delete", 
            "tag": "File", 
            "thumbPolicy": "Delete", 
            "file": "/picture/funny_cat.jpg", 
            "data": {
                "priority": "None", 
                "File": {
                    "suggestedFilename": "funny_cat.jpg", 
                    "contentType": "suggestedFilename"
                }
            }, 
            "chatId": "436"
        }
    }, 
    {
        "chatMessageSend": {
            "content": "Follow me on Glympse: www.glympse.com", 
            "tag": "Glympse", 
            "data": {
                "priority": "None", 
                "Glympse": {
                    "id": "123234232"
                }
            }, 
            "chatId": "3"
        }
    }, 
    {
        "chatMessageSend": {
            "content": "Follow me on Glympse: www.glympse.com", 
            "tag": "GlympseRequest", 
            "data": {
                "priority": "None", 
                "GlympseRequest": {
                    "duration": 300
                }
            }, 
            "chatId": "4"
        }
    }, 
    {
        "chatMessageSend": {
            "content": "The answer is 2.", 
            "tag": "Quote", 
            "data": {
                "priority": "None", 
                "Quote": {
                    "text": "What is 1+1?", 
                    "timestamp": 562737600, 
                    "source": "John Doe"
                }
            }, 
            "chatId": "5"
        }
    }, 
    {
        "chatMessageSend": {
            "content": "Me too!", 
            "tag": "ReferencedUpdate", 
            "data": {
                "priority": "None", 
                "ReferencedUpdate": {
                    "type": "PersonalMessage", 
                    "update": "Looking forward to this weekend."
                }
            }, 
            "chatId": "6"
        }
    }, 
    {
        "chatMessageSend": {
            "tag": "Screencap", 
            "chatId": "7"
        }
    }, 
    {
        "chatMessageSend": {
            "content": "Important Message", 
            "ref": [
                {
                    "tag": "Quote", 
                    "messageId": "634"
                }, 
                {
                    "tag": "Thread", 
                    "messageId": "6"
                }
            ], 
            "tag": "Text", 
            "data": {
                "priority": "High"
            }, 
            "chatId": "8"
        }
    }, 
    {
        "chatMessageSend": {
            "content": "My Location", 
            "tag": "Location", 
            "data": {
                "priority": "None", 
                "Location": {
                    "city": "Halifax", 
                    "name": "Halifax, NS, Canada", 
                    "country": "Canada", 
                    "altitude": "3", 
                    "longitude": "-63.57822", 
                    "postalCode": "", 
                    "state": "NS", 
                    "street": "", 
                    "horizontalAccuracy": "90", 
                    "latitude": "44.64692"
                }
            }, 
            "chatId": "9"
        }
    }, 
    {
        "chatMessageSend": {
            "content": "Let's discuss this with the others.", 
            "tag": "MediaConf", 
            "data": {
                "priority": "None", 
                "MediaConf": {
                    "url": "https://conf.bbm.bbmenterprise.com/join?appId=example", 
                    "requireAuth": true
                }
            }, 
            "chatId": "1000"
        }
    }, 
    {
        "chatMessageSend": {
            "tag": "Call", 
            "data": {
                "priority": "None", 
                "Call": {
                    "callType": "Video", 
                    "eventType": "Ended", 
                    "duration": 326
                }
            }, 
            "chatId": "10"
        }
    }, 
    {
        "chatMessageSend": {
            "content": "https://www.blackberry.com/us/en/products/blackberry-spark-platform", 
            "tag": "Link", 
            "data": {
                "priority": "None", 
                "Link": {
                    "url": "https://www.blackberry.com/us/en/products/blackberry-spark-platform", 
                    "image": "https://rimblogs.files.wordpress.com/2017/06/business-man-secure.png", 
                    "name": "BlackBerry Spark", 
                    "descr": "BlackBerry Spark is the only Enterprise of Things (EoT) platform designed and built for ultra-secure hyperconnectivity from the kernel to the edge.", 
                    "title": "BlackBerry Spark: The EoT Platform for Ultra-secure Hyperconnectivity"
                }
            }, 
            "chatId": "11"
        }
    }
]

chatMessageState

NamechatMessageState
SinceR4
DirectionIncoming

bbmcore sends this message in response to a 'chatMessageStateGet' request.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringOptionalR4YesAn opaque value that is echoed back to your application if it was specified in the request.
statesarrayRequiredR4YesThe list of per-recipient message delivery states. This will be empty if the message does not exist or if no detailed delivery state is known for the message.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptionalR4NoThe individual delivery state for the message for a single recipient.
NameTypeRequiredSinceLoggableDescription
statestringRequiredR4YesThe delivery state of the message for the individual recipient.

This field is an enumeration.

MemberDescription
Delivered The message has been delivered.
Read The message has been read.
userUristringRequiredR4YesThe URI of the recipient.
Examples:
[
    {
        "chatMessageState": {
            "states": [], 
            "cookie": "asdgjh2095hga984598hg"
        }
    }, 
    {
        "chatMessageState": {
            "states": [
                {
                    "state": "Read", 
                    "userUri": "bbmpim://user/id/23576"
                }
            ], 
            "cookie": "asdgjh2095hga984598hg"
        }
    }, 
    {
        "chatMessageState": {
            "states": [
                {
                    "state": "Delivered", 
                    "userUri": "bbmpim://user/id/5"
                }, 
                {
                    "state": "Read", 
                    "userUri": "bbmpim://user/id/6"
                }
            ]
        }
    }
]

chatMessageStateGet

NamechatMessageStateGet
SinceR4
DirectionOutgoing

Your application sends this request to ask for the per-recipient message delivery state details for a particular message in a chat. If bbmcore accepts the request, it will respond with a 'chatMessageState' response.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR4YesThe id of the chat containing the message referred to by 'messageId'.
cookiestringOptionalR4YesAn opaque value supplied by your application that will be echoed back in the response.
messageIdchatMessage keyRequiredR4YesThe id of the message (within the chat referred to by 'chatId') for which information is to be returned.
Examples:
[
    {
        "chatMessageStateGet": {
            "messageId": "256789", 
            "chatId": "12"
        }
    }, 
    {
        "chatMessageStateGet": {
            "messageId": "8", 
            "cookie": "slggjq3240987g0987", 
            "chatId": "234754"
        }
    }
]

chatParticipantTimes

NamechatParticipantTimes
SinceR5
DirectionIncoming

bbmcore sends this message in response to a 'chatParticipantTimesGet' request.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringOptionalR5YesAn opaque value that is echoed back to your application if it was specified in the request.
timesarrayRequiredR5YesThe list of per-participant message delivery times. This will be empty if the specified chat or participant does not exist.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptionalR5NoThe individual delivery times for a single participant.
NameTypeRequiredSinceLoggableDescription
deliverednumber (unsigned 64-bit int)OptionalR5YesThe timestamp, in seconds since the POSIX epoch, of the most recent message delivery confirmation automatically sent by this participant in this chat. If omitted, no such timestamp is known for this participant.
readnumber (unsigned 64-bit int)OptionalR5YesThe timestamp, in seconds since the POSIX epoch, of the most recent message read confirmation that this participant has sent in this chat. If omitted, no such timestamp is known for this participant.
userUristringRequiredR5YesThe URI of the participant.
Examples:
[
    {
        "chatParticipantTimes": {
            "cookie": "asdgjh2095hga984598hg", 
            "times": []
        }
    }, 
    {
        "chatParticipantTimes": {
            "cookie": "asdgjh2095hga984598hg", 
            "times": [
                {
                    "delivered": 12345, 
                    "userUri": "bbmpim://user/id/23576"
                }
            ]
        }
    }, 
    {
        "chatParticipantTimes": {
            "times": [
                {
                    "read": 12346, 
                    "delivered": 12345, 
                    "userUri": "bbmpim://user/id/5"
                }, 
                {
                    "read": 7124, 
                    "userUri": "bbmpim://user/id/6"
                }, 
                {
                    "userUri": "bbmpim://user/id/7"
                }
            ]
        }
    }
]

chatParticipantTimesGet

NamechatParticipantTimesGet
SinceR5
DirectionOutgoing

Your application sends this request to ask for the message delivery time details for a particular participant in a chat. If bbmcore accepts the request, it will respond with a 'chatParticipantTimes' response.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR5YesThe id of the chat whose participants are being queried.
cookiestringOptionalR5YesAn opaque value supplied by your application that will be echoed back in the response.
userUriuser keyOptionalR5YesIff present, then only the information for the one participant with this 'user' URI will be returned. Otherwise, information about all of the chat's participants will be returned.
Examples:
[
    {
        "chatParticipantTimesGet": {
            "chatId": "12"
        }
    }, 
    {
        "chatParticipantTimesGet": {
            "cookie": "slggjq3240987g0987", 
            "userUri": "bbmpim://user/id/123", 
            "chatId": "234754"
        }
    }
]

chatStart

NamechatStart
Since2017.02
DirectionOutgoing

This message requests that a new chat be started. When successful, a 'listAdd' will be emitted for the new 'chat' element. Otherwise, bbmcore will respond with a 'chatStartFailed' message.

If 'isOneToOne' is true and a 1:1 chat already exists for the invitee, bbmcore will respond with a 'chatStartFailed' with a reason of 'AlreadyExists' and the 'chatId' of that existing chat.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequired2017.02YesAn opaque string generated by your application that will be included in the resulting 'listAdd' or 'chatStartFailed' message.
dataobjectOptionalR6No

This field contains opaque data managed by your 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 a 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 'data' field of 'chatMessage' instead.

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

invitePolicystringOptional (Default=ParticipantsOnly)R4YesThe policy that controls who may invite participants to the chat. This only applies when the 'isOneToOne' field is absent or false.

This field is an enumeration.

MemberDescription
AdminsOnly Only chat admins may invite participants to the chat.
ParticipantsOnly Only chat participants may invite participants to the chat.
inviteesarrayRequired2017.02Yes

Holds the list of invitees to invite to the chat. When 'isOneToOne' is true, this list must contain exactly one entry. Otherwise, it may contain zero or more entries.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectRequired2017.02NoEach invitee may be identified by a user URI or regId. Entries without one of these identifiers will be ignored.
NameTypeRequiredSinceLoggableDescription
regIdnumber (signed 64-bit int)Optional2017.02Yes

The regId of a Spark Communications user to invite to the chat. This will create a new user if the regId isn't already known to bbmcore.

Ignored iff 'userUri' is specified.

userUriuser keyOptional2017.02YesThe URI of an existing user to invite to the chat. When present, the 'regId' is ignored.
isOneToOnebooleanOptional (Default=False)R3YesWhen true, the chat is the singular 1:1 chat between the local user and the other party. bbmcore 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.
localDataobjectOptionalR6No

This field contains opaque local-only data that is associated with this chat and managed by your application. This data is stored locally on this endpoint only.

privateDataobjectOptionalR7No

This field contains opaque data managed by your 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).

subjectstringOptional (Default=)2017.02No

The subject of the chat. This field has a maximum size of 128 code points. When omitted, this defaults to the empty string.

Examples:
[
    {
        "chatStart": {
            "invitePolicy": "ParticipantsOnly", 
            "subject": "New 1:1 chat", 
            "cookie": "chocolate", 
            "invitees": [
                {
                    "userUri": "bbmpim://user/id/3646"
                }
            ], 
            "isOneToOne": true
        }
    }, 
    {
        "chatStart": {
            "invitees": [], 
            "cookie": "vanilla", 
            "invitePolicy": "ParticipantsOnly", 
            "isOneToOne": false, 
            "subject": ""
        }
    }, 
    {
        "chatStart": {
            "privateData": {
                "notificationPriority": "High", 
                "chatNickname": "Friends from Work"
            }, 
            "isOneToOne": false, 
            "cookie": "wafer-thin", 
            "localData": {
                "someData": "someValue"
            }, 
            "invitees": [
                {
                    "userUri": "bbmpim://user/id/4573"
                }, 
                {
                    "regId": 10004723564, 
                    "displayName": "Cookie Monster"
                }
            ], 
            "data": {
                "appContextId": "miZPa8ef1Xj5Vl7YmSyYVxKdbJDBIMNK", 
                "avatar": "https://avatar.server/8GWl2rOF"
            }, 
            "invitePolicy": "AdminsOnly", 
            "subject": "New conference"
        }
    }
]

chatStartFailed

NamechatStartFailed
Since2017.02
DirectionIncoming

Sent by bbmcore when a 'chatStart' request has failed.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyOptionalR6YesThis is present iff the 'reason' is 'AlreadyExists'. This is the id of the existing 1:1 chat.
cookiestringRequired2017.02YesThe opaque value supplied by your application when issuing the 'chatStart' request that has failed.
reasonstringRequired2017.02YesThe reason that the 'chatStart' request failed.

This field is an enumeration.

MemberDescription
AlreadyExists The specified 1:1 chat already exists. The 'chatId' will be present and will contain the id of the existing chat.
None No reason was specified.
Examples:
[
    {
        "chatStartFailed": {
            "reason": "None", 
            "cookie": "chocolate"
        }
    }, 
    {
        "chatStartFailed": {
            "reason": "AlreadyExists", 
            "cookie": "vanilla", 
            "chatId": "12"
        }
    }
]

chatTyping

NamechatTyping
SinceR4
DirectionOutgoing

Your application sends this to bbmcore when it considers the user to have started typing in a chat. This event will be relayed in real-time to other participants of the chat.

Received typing events are reported to receivers via the 'typing' list. On the receiving endpoints, the typing state of a user automatically decays back to "not typing" after a short delay or when a message from them is added to the chat's history. There is no need for your application to inform bbmcore when a user stops typing.

In certain conditions, bbmcore may not actually transmit the typing notification to the other participants of the chat. These conditions include when there are no previous messages in the chat (on the local endpoint) or when the previous messages in the chat are older than five minutes. Filtering the events in this way helps optimize message transmission for cases where it is very unlikely that the other participants are expected to read a typing indicator on their endpoints.

It is recommended that your application wait a short delay after the commencement of typing before issuing this request. Short messages can often be typed in a few seconds, and it is often better to simply send the message itself instead of a typing notification followed by the message in very short succession.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR4YesThe id of the chat in which the local user is typing.
messageIdchatMessage keyOptionalR6YesIf 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 or when the messageId isn't known to bbmcore.
tagstringOptionalR6YesYour application-specified tag that indicates what kind of typing action the local user is performing. For example, this may be used to indicate that the local user is taking a picture to send, recording a voice note, or editing an existing message. When omitted, receivers will assume the local user is typing a message.
Examples:
[
    {
        "chatTyping": {
            "chatId": "2824"
        }
    }, 
    {
        "chatTyping": {
            "tag": "VoiceNote", 
            "chatId": "7"
        }
    }, 
    {
        "chatTyping": {
            "tag": "Edit", 
            "messageId": "375", 
            "chatId": "88"
        }
    }
]

endpointDeregister

NameendpointDeregister
SinceR4
DirectionOutgoing

Requests that bbmcore de-register the identified endpoint. This will forward the de-register request to the BlackBerry Infrastructure, and result in an 'endpointDeregisterResult' with the given cookie from bbmcore.

De-registering an endpoint will revoke its registration on the BlackBerry Infrastructure and remove it from the Spark Communications identity's list of registered endpoints. If currently connected to the BlackBerry Infrastructure, it will be disconnected as soon as possible and wiped.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequiredR4YesAn opaque value to be included in the associated 'endpointDeregisterResult'.
endpointIdstringRequiredR4YesThe identifier of the endpoint to de-register obtained from an 'endpoints' response. This may be any of the Spark Communications identity's endpoints, including the one issuing the de-register request.
Examples:
[
    {
        "endpointDeregister": {
            "cookie": "Dad's Chocolate Chip Cookies", 
            "endpointId": "13124523943944079cdc729adeff25a2A4gD2diIgj5Jd3SG6HFfda"
        }
    }
]

endpointDeregisterResult

NameendpointDeregisterResult
SinceR4
DirectionIncoming

The result of an 'endpointDeregister' request.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequiredR4YesThe opaque value supplied in the 'endpointDeregister' this result is associated to.
resultstringRequiredR4YesThe result of the update.

This field is an enumeration.

MemberDescription
Failure The de-registration could not be completed, and may be retried later.
Success The de-registration has completed successfully.
Examples:
[
    {
        "endpointDeregisterResult": {
            "cookie": "chocolate", 
            "result": "Success"
        }
    }, 
    {
        "endpointDeregisterResult": {
            "cookie": "chocolate", 
            "result": "Failure"
        }
    }
]

endpointDeregistered

NameendpointDeregistered
SinceR6
DirectionIncoming

The local endpoint is no longer registered with the BlackBerry Infrastructure.

bbmcore will wipe and stop in order to forget all information associated with the endpoint, including its user identity. One notable exception is the 'endpointId', will normally will not change.

Your application must delete all information associated with the previous Spark Communications identity. To go through setup again, your application should collect fresh identity credentials from the user and use fresh tokens.

Attributes:
Examples:
[
    {
        "endpointDeregistered": {}
    }
]

endpointUpdate

NameendpointUpdate
SinceR4
DirectionOutgoing

Requests that bbmcore update the identified endpoint's registration details. This will result in an 'endpointUpdateResult' with the given cookie from bbmcore.

This message should be called for the local endpointId before registering (when the 'setupState' is 'NotRequested'i) to set the potentially new endpoint's description on the BlackBerry Infrastructure.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequiredR4YesAn opaque value to be included in the associated 'endpointUpdateResult'.
descriptionstringRequiredR4NoThe human-readable description of the device/OS the endpoint is installed on. This should never be empty. This will be truncated to at most 2000 Unicode Code Points.
endpointIdstringOptionalR4YesThe identifier of the endpoint to update obtained from an 'endpoints' response. If omitted, the local endpointId is used.
nicknamestringRequiredR4NoThe name assigned to the endpoint by the end-user; empty if none assigned. This will be truncated to at most 2000 Unicode Code Points.
Examples:
[
    {
        "endpointUpdate": {
            "isLegacyDelegate": true, 
            "nickname": "", 
            "cookie": "chocolate", 
            "description": "Apple iPhone 8s (iOS v10.1)", 
            "endpointId": "13124523943944079cdc729adeff25a2A4gD2diIgj5Jd3SG6HFfda"
        }
    }, 
    {
        "endpointUpdate": {
            "isLegacyDelegate": false, 
            "nickname": "S.M.A.R.T. Watch", 
            "cookie": "chocolate", 
            "description": "Gumshoe OS"
        }
    }
]

endpointUpdateResult

NameendpointUpdateResult
SinceR4
DirectionIncoming

The result of an 'endpointUpdate' request.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequiredR4YesThe opaque value supplied in the 'endpointUpdate' this result is associated to.
resultstringRequiredR4YesThe result of the update.

This field is an enumeration.

MemberDescription
Failure The update could not be applied, and may be retried later.
Success The update has been applied successfully.
Examples:
[
    {
        "endpointUpdateResult": {
            "cookie": "chocolate", 
            "result": "Success"
        }
    }, 
    {
        "endpointUpdateResult": {
            "cookie": "chocolate", 
            "result": "Failure"
        }
    }
]

endpoints

Nameendpoints
SinceR4
DirectionIncoming

The response to the 'endpointsGet' message. All registered endpoints are included in the 'registeredEndpoints' array.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequiredR4YesThe opaque value supplied in the 'endpointsGet' this result is associated to.
maxEndpointsnumber (unsigned 64-bit int)OptionalR4YesThe maximum number of persistent endpoints that can be registered for this identity. This field will always be present when the 'result' is 'Success'.
registeredEndpointsarrayOptionalR4YesThe Spark Communications identity's registered endpoints. This field will always be present when the 'result' is 'Success'.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectRequiredR4YesA single endpoint.
NameTypeRequiredSinceLoggableDescription
descriptionstringRequiredR4NoThe human-readable description of the device/OS the endpoint is installed on. This may be initially set by your application when the endpoint is registered during setup, and may be updated via the 'endpointUpdate' request.
endpointIdstringRequiredR4YesThe endpoint's identifier for use in 'endpointUpdate' or 'endpointDeregister'. This must be treated as an opaque value by applications with no meaning outside these specific BBMDS messages.
isCurrentbooleanOptional (Default=False)R4YesWhen present and true, this endpoint is the one that issued the 'endpointsGet' request that resulted in this 'endpoints' response.
isEphemeralbooleanOptional (Default=False)R4YesWhen present and true, this endpoint is an ephemeral endpoint without local data storage. When omitted or false, this endpoint is a persistent endpoint with local data storage. Persistent and ephemeral endpoints have different registration requirements and have separate maximums enforced by the BlackBerry Infrastructure.
nicknamestringRequiredR4NoThe name assigned to the endpoint by the end-user; empty if none assigned. This may be initially set by your application when the endpoint is registered during setup, and may be updated via the 'endpointUpdate' request.
resultstringRequiredR4YesThe result of the request.

This field is an enumeration.

MemberDescription
Failure The request could not be completed, and may be retried later.
Success The Spark Communications identity's registered endpoints have been retrieved successfully and are present in the 'registeredEndpoints' array.
Examples:
[
    {
        "endpoints": {
            "cookie": "chocolate", 
            "result": "Failure"
        }
    }, 
    {
        "endpoints": {
            "maxEndpoints": 3, 
            "cookie": "chocolate", 
            "result": "Success", 
            "registeredEndpoints": [
                {
                    "description": "BlackBerry KEYone", 
                    "isEphemeral": false, 
                    "endpointId": "13124523943944079cdc729adeff25a2A4gD2diIgj5Jd3SG6HFfda", 
                    "isLegacyDelegate": false, 
                    "isCurrent": false, 
                    "nickname": "Work Phone"
                }, 
                {
                    "description": "Debian GNU/Linux 9.0", 
                    "isEphemeral": false, 
                    "endpointId": "53484523943944079cdc729adeff25a2A4gD2diIgj5Jd3Sfsdlij3", 
                    "isLegacyDelegate": true, 
                    "isCurrent": false, 
                    "nickname": "Work PC"
                }, 
                {
                    "description": "NVIDIA Shield K1", 
                    "isEphemeral": false, 
                    "endpointId": "fjdsrlgj458944079cdc729adeff25a2A4gD2diIgj5Jd3f35HF569", 
                    "isLegacyDelegate": false, 
                    "isCurrent": false, 
                    "nickname": "Personal Tablet"
                }
            ]
        }
    }
]

endpointsGet

NameendpointsGet
SinceR4
DirectionOutgoing

Requests that bbmcore retrieve all of the Spark Communications identity's registered endpoints and reply with an 'endpoints' message.

Endpoints are individual application installations associated to the same Spark Communications identity. Such an identity can have zero or more endpoints, with a maximum enforced by the BlackBerry Infrastructure.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequiredR4YesAn opaque value to be returned in the associated 'endpoints' response.
Examples:
[
    {
        "endpointsGet": {
            "cookie": "13124523-9439-4407-9cdc-729adeff25a2"
        }
    }
]

identities

Nameidentities
SinceR6
DirectionIncoming

The response to the 'identitiesGet' message.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequiredR6YesThe opaque value supplied in the 'identitiesGet' message this result is associated to.
infoarrayOptionalR6YesThe set of identity information found. Each identifier in the request that corresponds to a known identity will have an entry in this array. Each identifier in the request that does not correspond to a known identity will be omitted from this array.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectRequiredR6YesThe information for a found identity.
NameTypeRequiredSinceLoggableDescription
appUserIdstringRequiredR6YesYour application user id for this identity, in the same form as the 'authToken' 'userId' field.
regIdstring (signed 64-bit int in base 10)RequiredR6YesThe Spark Communications regId for this identity.
resultstringRequiredR6YesThe result of the request.

This field is an enumeration.

MemberDescription
Failure The request could not be completed and may be retried later.
Success The lookup was successful.
Examples:
[
    {
        "identities": {
            "cookie": "arrowroot", 
            "result": "Failure"
        }
    }, 
    {
        "identities": {
            "identities": [
                {
                    "regId": "4855746228", 
                    "appUserId": "23jr95yrr03oe"
                }, 
                {
                    "regId": "1000002393", 
                    "appUserId": "2kfjj5g45kfk4"
                }, 
                {
                    "regId": "1", 
                    "appUserId": "1"
                }
            ], 
            "cookie": "arrowroot", 
            "result": "Success"
        }
    }
]

identitiesGet

NameidentitiesGet
SinceR6
DirectionOutgoing

Requests that the given list of identities, either application user ids or Spark Communications regIds, be resolved to find the associated identity information, and returned via an 'identities' message.

Identities for which identity information cannot be found are omitted from the results.

Overlapping 'identitiesGet' requests are issued in parallel. Issuing too many parallel requests at once can exceed system limits and cause those requests to fail.

Attributes:
NameTypeRequiredSinceLoggableDescription
appUserIdsarrayOptionalR6YesA list of application user ids to lookup. Either this or 'regIds' must be specified.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
stringRequiredR6YesYour application user id for this identity, in the same form as the 'authToken' 'userId' field.
cookiestringRequiredR6YesAn opaque value to be returned in the associated 'identities' response.
regIdsarrayOptionalR6Yes

A list of Spark Communications regIds to lookup. Either this or 'appUserIds' must be specified.

A maximum of 50 identities can be present in one request. If more identities are present, 'identities' will return a 'Failure'.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
string (signed 64-bit int in base 10)RequiredR6YesA Spark Communications regId for this identity.
Examples:
[
    {
        "identitiesGet": {
            "appUserIds": [
                "21389hfdhf983", 
                "rhabawe434g3"
            ], 
            "cookie": "13124523-9439-4407-9cdc-729adeff25a2"
        }
    }, 
    {
        "identitiesGet": {
            "regIds": [
                "1872374576594", 
                "95303948244"
            ], 
            "cookie": "13124523-9439-4407-9cdc-729adeff25a2"
        }
    }
]

listAdd

NamelistAdd
Since2.0
DirectionIncoming

Bbmcore may send this message at any time to insert new elements into a list.

This message contains full element states. All attributes marked as required are also required by this message. Optional attributes are set to their default values if not present.

Either the list attribute must be specified or both the type/id attributes must be specified.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringOptional2.1YesHolds an optional cookie that was previously generated by your application and included in an outgoing request. This attribute should be omitted for add events that were not specifically requested by your application. Your application must gracefully handle unknown cookies and the case where a cookie it passed to bbmcore is never echoed back. Each outgoing message that includes a cookie will document the circumstances in which bbmcore will echo that cookie back to your application and in which lists.
elementsarrayOptional2.0YesHolds the list elements. Includes a full state of the element. Elements must include all attributes marked as required in the schema. Any optionl attributes will be set to default values. See the documentation for this list type for the element schema. If the 'elements' attribute is omitted, it is treated equivalent to the empty set and this message becomes a no-op.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2.0NoHolds the full state of the items to add to the list.
typestringOptional2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "listAdd": {
            "elements": [
                {
                    "stateIsPartial": false, 
                    "timestamp": 30987309874, 
                    "senderUri": "bbmpim://user/id/29", 
                    "content": "Hello world!", 
                    "state": "Delivered", 
                    "tag": "Text", 
                    "flags": "I", 
                    "messageId": "793873", 
                    "recall": "None", 
                    "chatId": "8475"
                }, 
                {
                    "timestamp": 30987309921, 
                    "recall": "None", 
                    "state": "Delivered", 
                    "stateIsPartial": false, 
                    "senderUri": "bbmpim://user/id/29", 
                    "tag": "Join", 
                    "flags": "I", 
                    "messageId": "93874", 
                    "chatId": "5"
                }
            ], 
            "type": "chatMessage"
        }
    }
]

listAll

NamelistAll
Since2.1
DirectionIncoming

Replaces the contents of a list. At its option, bbmcore may send this message at any time to replace the entire list contents or to clear the contents of the list. This is also sent in response to a 'requestListAll' message.

'listAll' does not directly contain the new element set. It is a marker indicating that it will be followed by a group of 'listChunk' messages. The last chunk in the group will contain the attribute 'last' set to true. Bbmcore may send any number of chunks and any of the chunks may be empty. This message never appears on its own. It is always followed by a sequence of 'listChunk' messages and it is always contiguous with those 'listChunk' messages.

Attributes:
NameTypeRequiredSinceLoggableDescription
typestringRequired2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "listAll": {
            "type": "chat"
        }
    }
]

listChange

NamelistChange
Since2.1
DirectionIncoming

Changes attributes of one or more elements in the list. This does not insert or remove elements. At its option, bbmcore may send this message at any time to change existing elements of a list. The elements may appear in any order. The only required attributes are the primary keys of the elements. All other attributes that are normally required are optional. If omitted, the attributes retain their existing values. If specified, the attributes are modified.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringOptional2.1YesHolds an optional cookie that was previously generated by your application and included in an outgoing request. This attribute should be omitted for add events that were not specifically requested by your application. Your application must gracefully handle unknown cookies and the case where a cookie it passed to bbmcore is never echoed back. Each outgoing message that includes a cookie will document the circumstances in which bbmcore will echo that cookie back to your application and in which lists.
elementsarrayOptional2.0YesHolds the list elements. Includes the primary key of the element, along with any attributes that have changed. Elements may include any subset of attributes listed in the element schema that includes the primary key(s), regardless of whether those attributes are marked as required. Any omitted attributes will remain unchanged. See the documentation for this list type for the element schema. If the 'elements' attribute is omitted, it is treated equivalent to the empty set and this message becomes a no-op.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2.0NoHolds a subset of attributes for elements in the list.
typestringOptional2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "listChange": {
            "elements": [
                {
                    "state": "Ready", 
                    "chatId": "793873"
                }
            ], 
            "type": "chat"
        }
    }
]

listChunk

NamelistChunk
Since2.1
DirectionIncoming

Used to send a subset of list elements to your application. One or more 'listChunk' messages will follow a 'listAll' or 'listElements' message. The leading message and the set of 'listChunk' messages that follow it are considered a single logical message. 'listChunk' messages contain full states for the set of elements that go with the trigger message. That is, all attributes marked as required in the element schema must also be present in the 'listChunk' message. All attributes marked as optional but not present in the 'listChunk' element must be considered to be unset or have their default value, as documented in the list's definition.

When your application receives the leading message, it starts gathering elements from subsequent 'listChunk' messages until it receives a 'listChunk' with the 'last' attribute present and true. At that point, all the messages are processed together. A header message and its 'listChunk' messages must be contiguous.

Attributes:
NameTypeRequiredSinceLoggableDescription
elementsarrayRequired2.1YesHolds the list elements. Includes a full state of the element. Elements must include all attributes marked as required in the schema. Any optional attributes will be set to default values. See the documentation for this list type for the element schema. If the elements set is empty, this clears the elements referred to in the trigger message.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2.1NoHolds the full state of the items in the list.
lastbooleanOptional (Default=False)2.1YesDetermines if this is the last chunk in the sequence. The sequence of 'listChunk' messages is not processed until your application recieves the last chunk.
typestringRequired2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "listChunk": {
            "last": false, 
            "elements": [], 
            "type": "chat"
        }
    }, 
    {
        "listChunk": {
            "last": true, 
            "elements": [
                {
                    "subject": "All your base", 
                    "restorePoint": 0, 
                    "localData": {}, 
                    "state": "Ready", 
                    "lastActivity": 1098730987, 
                    "flags": "O", 
                    "lastMessage": 15, 
                    "keyState": "Export", 
                    "numMessages": 10, 
                    "mailboxId": "mbx123", 
                    "chatId": "38267"
                }, 
                {
                    "subject": "Are belong to us", 
                    "expiry": 3600, 
                    "restorePoint": 500, 
                    "localData": {
                        "someData": "someValue"
                    }, 
                    "state": "Waiting", 
                    "lastActivity": 10987300000, 
                    "flags": "AP", 
                    "lastMessage": 10293873870, 
                    "keyState": "Synced", 
                    "chatId": "6", 
                    "invitePolicy": "AdminsOnly", 
                    "mailboxId": "", 
                    "numMessages": 1000
                }
            ], 
            "type": "chat"
        }
    }
]

listElements

NamelistElements
Since2.1
DirectionIncoming

Replaces individual elements in a list. At its option, bbmcore may send this message at any time to replace individual elements in the list. This is also sent in response to a 'requestListElements' message. This message differs from 'listChange' in that it contains full states for the elements being changed rather than a delta, and that the element data follows in a sequence of 'listChunk' messages rather than being embedded within the 'listElements' message

'listElements' does not directly contain the new element set. It is a marker indicating that it will be followed by a group of 'listChunk' messages. The last chunk in the group will contain the attribute 'last' set to true. Bbmcore may send any number of chunks and any of the chunks may be empty. This message never appears on its own. It is always followed by a sequence of 'listChunk' messages and it is always contiguous with those 'listChunk' messages.

The order of the elements may be defined by the outgoing message that triggered this response. In the absence of any ordering contract on the outgoing message, the order of the elements in the result is undefined.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringOptional2.1YesHolds an optional cookie that was previously generated by your application and included in a request. The presence of this field indicates that the elements in the response match exactly the elements included in the requestListElements. If an element is not present, it indicates that the key was unknown to daemon.
typestringRequired2.1YesDetermines the namespace for the ID attribute and the schema for the list elements. For the set of valid list types, see the doc/lists subdirectory.
Examples:
[
    {
        "listElements": {
            "cookie": "23SJFSDF3", 
            "type": "chat"
        }
    }
]

listRemove

NamelistRemove
Since2.0
DirectionIncoming

Bbmcore may send this message at any time to remove elements from the list. The elements in 'listRemove' only contain the primary key. No other attributes may be present, even if they are documented as required in the element schema.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringOptional2.1YesHolds an optional cookie that was previously generated by your application and included in an outgoing request. This attribute should be omitted for remove events that were not specifically requested by your application. Your application must gracefully handle unknown cookies and the case where a cookie it passed to bbmcore is never echoed back. Each outgoing message that includes a cookie will document the circumstances in which bbmcore will echo that cookie back to your application and in which lists.
elementsarrayOptional2.0YesHolds the primary keys of the list elements. See the documentation for this list type for the element schema. If the 'elements' attribute is omitted, it is treated equivalent to the empty set and this message becomes a no-op.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2.0NoHolds the removed elements with only their primary key attribute(s) present.
typestringOptional2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "listRemove": {
            "cookie": "23SJFSDF3", 
            "elements": [
                {
                    "chatId": "1"
                }, 
                {
                    "chatId": "2"
                }
            ], 
            "type": "chat"
        }
    }
]

listResync

NamelistResync
Since2017.02
DirectionIncoming

Indicates that elements of the list that match the given criteria have potentially changed or been removed. bbmcore may send this message at any time it determines that it is more efficient for your application to query the state of elements of interest, rather than emitting events for all the changes in the list's content. listResync does not contain an element set.

Lists do not support this message by default, and those that support requestListAll never support listResync. If the list supports this message, its documentation will indicate which attributes may be used as part of the criteria block. If the list supports multiple criteria attributes then they may be present in any combination. If more than one attribute is present then all the listed attributes must match.

Attributes:
NameTypeRequiredSinceLoggableDescription
criteriaobjectRequired2017.02YesSpecifies a list of criteria key/value pairs. Each key is documented in the 'listResync' rules for the specific list in question. Empty criteria are allowed.
typestringRequired2017.02YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "listResync": {
            "type": "chatMessage", 
            "criteria": {}
        }
    }, 
    {
        "listResync": {
            "type": "chatMessage", 
            "criteria": {
                "chatId": "5"
            }
        }
    }
]

participantDemote

NameparticipantDemote
SinceR4
DirectionOutgoing

Demote the given participant to no longer be an admin of the specified chat. The change will be reflected locally immediately via a change to the participant, and a request will be initiated to the BlackBerry Infrastructure to effect the demotion. Once complete, a 'chatMessage' will be posted to the chat indicating that the local user has demoted the participant.

This request is ignored if:

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR4YesThe id of the chat the demotion will occur within.
userUriuser keyRequiredR4YesThe user URI of the participant to be demoted.
Examples:
[
    {
        "participantDemote": {
            "userUri": "bbmpim://user/id/5483", 
            "chatId": "2347"
        }
    }
]

participantPromote

NameparticipantPromote
SinceR4
DirectionOutgoing

Promote the given participant to be an admin of the specified chat. The change will be reflected locally immediately via a change to the participant, and a request will be initiated to the BlackBerry Infrastructure to effect the promotion. Once complete, a 'chatMessage' will be posted to the chat indicating that the local user has promoted the participant.

This request is ignored if:

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR4YesThe id of the chat the promotion will occur within.
userUriuser keyRequiredR4YesThe user URI of the participant to be promoted.
Examples:
[
    {
        "participantPromote": {
            "userUri": "bbmpim://user/id/5483", 
            "chatId": "2347"
        }
    }
]

participantRemove

NameparticipantRemove
SinceR4
DirectionOutgoing

Remove the given participant from the specified chat. The change will be reflected locally immediately via a change to the participant, and a request will be initiated to the BlackBerry Infrastructure to effect the removal. Once complete, a 'chatMessage' will be posted to the chat indicating that the local user has removed the participant.

This request is ignored if:

Removing a participant does not remove any messages they have posted in the chat.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR4YesThe id of the chat the removal will occur within.
userUriuser keyRequiredR4YesThe user URI of the participant to be removed.
Examples:
[
    {
        "participantRemove": {
            "userUri": "bbmpim://user/id/5483", 
            "chatId": "2347"
        }
    }
]

pinResult

NamepinResult
Since2015.06
DirectionIncoming

Returns the result of a requestPin message.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequired2015.06YesAn opaque value that is echoed back to your application if it was specified in the request.
pinsarrayOptional2015.12NoThe list of regId to PIN mappings. This should only be expected and examined when the 'result' is 'Success'.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2015.12NoAn individual regId to PIN mapping.
NameTypeRequiredSinceLoggableDescription
pinstringRequired2015.12NoThe PIN associated to the regId.
regIdnumber (signed 64-bit int)Required2015.12NoThe regId of the user.
resultstringRequired2015.06YesThe result of the request.

This field is an enumeration.

MemberDescription
Failure The request failed.
Success The request was successful, inspect the pin field for the result.
Examples:
[
    {
        "pinResult": {
            "pins": [], 
            "cookie": "123456ABCDEF", 
            "result": "Success"
        }
    }, 
    {
        "pinResult": {
            "pins": [
                {
                    "regId": 1, 
                    "pin": "12345678"
                }
            ], 
            "cookie": "123456ABCDEF", 
            "result": "Success"
        }
    }, 
    {
        "pinResult": {
            "pins": [
                {
                    "regId": 1, 
                    "pin": "12345678"
                }, 
                {
                    "regId": 2, 
                    "pin": "DEADBEEF"
                }, 
                {
                    "regId": 3, 
                    "pin": "5F735EE2"
                }
            ], 
            "cookie": "123456ABCDEF", 
            "result": "Success"
        }
    }, 
    {
        "pinResult": {
            "pins": [], 
            "cookie": "123456ABCDEF", 
            "result": "Failure"
        }
    }, 
    {
        "pinResult": {
            "cookie": "123456ABCDEF", 
            "result": "Failure"
        }
    }
]

profileKeys

NameprofileKeys
SinceR3
DirectionIncoming

Sent by bbmcore in response to a 'profileKeysExport' request.

This message will not be sent by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
privateKeysobjectRequiredR3YesThe private signing and encryption keys.
NameTypeRequiredSinceLoggableDescription
encryptionstringRequiredR3NoThe unpadded base64url-encoded private encryption key.
signingstringRequiredR3NoThe unpadded base64url-encoded private signing key.
publicKeysobjectRequiredR3YesThe public signing and encryption keys.
NameTypeRequiredSinceLoggableDescription
encryptionstringRequiredR3NoThe unpadded base64url-encoded public encryption key.
signingstringRequiredR3NoThe unpadded base64url-encoded public signing key.
Examples:
[
    {
        "profileKeys": {
            "publicKeys": {
                "encryption": "ZW5jcnlwdGlvblB1YmxpY0tleQ", 
                "signing": "c2lnbmluZ1B1YmxpY0tleQ"
            }, 
            "privateKeys": {
                "encryption": "ZW5jcnlwdGlvblByaXZhdGVLZXk", 
                "signing": "c2lnbmluZ1ByaXZhdGVLZXk"
            }
        }
    }
]

profileKeysExport

NameprofileKeysExport
SinceR3
DirectionOutgoing

Request that bbmcore return the identity keys that are being used by the local user. This will trigger a 'profileKeys' response.

To avoid event loops, your application must only react with 'profileKeysExport' (or 'profileKeysImport') to changes of the 'profileKeysState' to 'NotSynced'. Your application must not react to updates from bbmcore that indicate the 'profileKeysState' is 'NotSynced' when the 'profileKeysState' was already known to your application to be 'NotSynced'. In other words, your application must not export keys unless the 'profileKeysState' is actually changing or being learned for the first time. By following this rule, failed exports will not result in tight event loops and will allow retries (at a minimum on application restart, but also whenever bbmcore decides to toggle the state).

The 'profileKeysState' global is not updated in response to this message, and thus must be set to 'Synced' via a 'requestListChange' once the key is successfully stored externally.

This message will be ignored by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
Examples:
[
    {
        "profileKeysExport": {}
    }
]

profileKeysImport

NameprofileKeysImport
SinceR3
DirectionOutgoing

Request that bbmcore set the profile keys.

If the profile's keys are imported successfully, the 'profileKeysState' global will be updated to 'Synced'. If the import fails, the 'profileKeyState' will remain unchanged.

To avoid event loops, your application must only react with 'profileKeysImport' (or 'profileKeysExport') to changes of the 'profileKeysState' to 'NotSynced'. Your application must not react to updates from bbmcore that indicate the 'profileKeysState' is 'NotSynced' when the 'profileKeysState' was already known to your application to be 'NotSynced'. In other words, your application must not import keys unless the 'profileKeysState' is actually changing or being learned for the first time. By following this rule, failed imports will not result in tight event loops and will allow retries (at a minimum on application restart, but also whenever bbmcore decides to toggle the state).

Regardless of the 'profileKeysState', if your application has external evidence that the user has for some reason newly available or updated keys, your application can use 'profileKeysImport' to provide those keys, subject the event reaction restrictions documented above.

This message will be ignored by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
privateKeysobjectRequiredR3YesThe private signing and encryption keys.
NameTypeRequiredSinceLoggableDescription
encryptionstringRequiredR3NoThe unpadded base64url-encoded private encryption key.
signingstringRequiredR3NoThe unpadded base64url-encoded private signing key.
publicKeysobjectRequiredR3YesThe public signing and encryption keys.
NameTypeRequiredSinceLoggableDescription
encryptionstringRequiredR3NoThe unpadded base64url-encoded public encryption key.
signingstringRequiredR3NoThe unpadded base64url-encoded public signing key.
Examples:
[
    {
        "profileKeysImport": {
            "publicKeys": {
                "encryption": "ZW5jcnlwdGlvblB1YmxpY0tleQ", 
                "signing": "c2lnbmluZ1B1YmxpY0tleQ"
            }, 
            "privateKeys": {
                "encryption": "ZW5jcnlwdGlvblByaXZhdGVLZXk", 
                "signing": "c2lnbmluZ1ByaXZhdGVLZXk"
            }
        }
    }
]

profileKeysImportFailure

NameprofileKeysImportFailure
SinceR4
DirectionIncoming

Indicates that the profile keys received in 'profileKeysImport' failed to import.

This message will not be sent by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
Examples:
[
    {
        "profileKeysImportFailure": {}
    }
]

requestListAdd

NamerequestListAdd
Since2.0
DirectionOutgoing

Requests that bbmcore insert a new element in the list. Most lists do not support this message by default. Those that do contain a section in their documentation explaining what the message is used for and any restrictions on its use.

The documentation for the list indicates a subset of attributes that may be present in the 'requestListAdd' message. If the attributes in the subset are marked as required in the element schema, then they are also required by the 'requestListAdd' message. If they are optional, then they will be reset to their default value if not present.

Attributes:
NameTypeRequiredSinceLoggableDescription
elementsarrayRequired2.0YesHolds the list elements. Each element must include the primary key. If the list type supports this message the documentation for the list type will describe which additional attributes

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2.0NoHolds the full state of the items to add to the list.
typestringRequired2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "requestListAdd": {
            "elements": [
                {
                    "calories": 400, 
                    "type": "cheese", 
                    "eaten": false
                }, 
                {
                    "calories": 500, 
                    "type": "roast", 
                    "eaten": true
                }
            ], 
            "type": "sandwich"
        }
    }
]

requestListAll

NamerequestListAll
Since2.1
DirectionOutgoing

Requests that bbmcore returns the canonical version of the list by responding with a listAll message.

Attributes:
NameTypeRequiredSinceLoggableDescription
typestringRequired2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "requestListAll": {
            "type": "chat"
        }
    }
]

requestListChange

NamerequestListChange
Since2.0
DirectionOutgoing

Requests that bbmcore change attributes of one or more elements in the list. Most lists do not support this message by default. Those that do contain a section in their documentation explaining what the message is used for and any restrictions on its use. This message contains partial element states. The primary key is always required. The documentation for the list will describe a subset of other attributes that may also be present. All non-primary key attributes are optional, even if they are marked as required in the element schema. Elements that are not present remain unchanged and are not reset to default values.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringOptional2.1YesHolds an optional cookie that was generated by your application and included in this request.
elementsarrayRequired2.1YesHolds the list elements. Each element includes the primary key, along with a subset of attributes that should be changed. The set of permissible attributes will be described in the list documentation.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2.1NoHolds the primary key, along with a subset of other attributes that should be changed.
idstringOptional2.1NoIdentifier for the list, unique for a given list type. The exact meaning and format for list ids is determined by the list type. See the documentation in the doc/lists subdirectory for type-specific rules.
typestringRequired2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "requestListChange": {
            "cookie": "23SJFSDF3", 
            "elements": [
                {
                    "localData": {
                        "associatedResource": "RGF0YSBvZiB0aGUgYXBwJ3MgY2hvb3NpbmcuCg=="
                    }, 
                    "id": "42"
                }
            ], 
            "type": "appMessage"
        }
    }
]

requestListElements

NamerequestListElements
Since2.1
DirectionOutgoing

Requests that bbmcore send back full states of a given set of elements by responding with a listElements message. All lists support this message. The elements in this message only contain primary keys. No other attributes may be present, even if they are marked as required in the element schema.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringOptional2.1YesHolds an optional cookie that was generated by your application and included in this request. This allows your application to match up request/response. If present, the daemon will respond with a single listElements with a matching cookie whose elements match exactly those in this request, and the sender will be able to rely on the fact that a missing element is unknown to the daemon. If the cookie is omitted then the daemon may, at its option, merge multiple requestListElements into a single response or break a single requestListElements into multiple responses.
elementsarrayRequired2.1YesSpecifies the primary keys for the elements being requested.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2.1NoHolds the primary keys of the items to fetch.
typestringRequired2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "requestListElements": {
            "cookie": "23SJFSDF3", 
            "elements": [
                {
                    "id": 209
                }, 
                {
                    "id": 210
                }
            ], 
            "type": "chat"
        }
    }
]

requestListMatching

NamerequestListMatching
Since3.0
DirectionOutgoing

Requests that bbmcore send back full states of all elements that match the given criteria in a single listElements message with a matching cookie.

Lists do not support this message by default. If the list supports this message, its documentation will indicate which attributes may be used as part of the criteria block. If the list supports multiple criteria attributes then they may be present in any combination. If more than one attribute is present then all the listed attributes must match. The resulting listElements message will contain all elements for which all criteria match.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringOptional3.0YesHolds a cookie that was generated by your application and included in this request. This allows your application to match up request/response. Bbmcore will respond with a single 'listElements' with a matching 'cookie' whose elements match exactly those in this request, and the sender will be able to rely on the fact that a missing element is unknown to bbmcore.
criteriaobjectRequired3.0YesSpecifies a list of criteria key/value pairs. Each key is documented in the 'requestListMatching' rules for the specific list in question. Iff the list supports 'requestListAll', empty criteria are allowed and will result in all elements of the list being returned (via 'listElements').
typestringRequired3.0YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "requestListMatching": {
            "cookie": "cxZVVuD9WM231Sw3", 
            "type": "user", 
            "criteria": {
                "regId": "10000"
            }
        }
    }, 
    {
        "requestListMatching": {
            "cookie": "GdVAwVeEjkHayFv611vL6Ovxh", 
            "type": "chatMessage", 
            "criteria": {
                "tag": "Remove", 
                "chatId": "12"
            }
        }
    }
]

requestListRemove

NamerequestListRemove
Since2.0
DirectionOutgoing

Requests that bbmcore remove one or more elements from the list. By default, most lists do not support this message. Those that do contain documentation describing the message and any restrictions on its use. The elements in this message only contain primary keys. No other attributes may be present, even if they are marked as required in the element schema.

Attributes:
NameTypeRequiredSinceLoggableDescription
elementsarrayRequired2.0YesHolds the list elements. Each element only includes the primary key.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2.0NoHolds the primary key of the elements to remove.
typestringRequired2.1YesDetermines which list the elements belong to. This must be a list type defined elsewhere in the protocol.
Examples:
[
    {
        "requestListRemove": {
            "elements": [
                {
                    "id": "7"
                }, 
                {
                    "id": "12"
                }
            ], 
            "type": "appMessage"
        }
    }
]

requestPin

NamerequestPin
Since2015.06
DirectionOutgoing

Sent by your application to bbmcore to request the currently registered device PINs for the given regIds. This always triggers a BlackBerry Infrastructure request; bbmcore never considers its local list of users. Your application should first consult the user list to see if bbmcore already knows a PIN for a regId.

The result is returned via a pinResult message.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequired2015.06YesAn opaque value supplied by your application that will be echoed back in the response.
regIdsarrayRequired2015.12NoThe list of regIds whose PINs are to be looked up. If a regId is unknown or has no PINs associated with it, it may or may not appear in the results.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
number (signed 64-bit int)Required2015.12NoAn individual regId.
Examples:
[
    {
        "requestPin": {
            "regIds": [
                123456
            ], 
            "cookie": "123456ABCDEF"
        }
    }, 
    {
        "requestPin": {
            "regIds": [
                1, 
                2, 
                3, 
                4, 
                5, 
                6
            ], 
            "cookie": "123456ABCDEF"
        }
    }
]

retryServerRequests

NameretryServerRequests
Since2017.02
DirectionOutgoing

The purpose of this message is to provide bbmcore with a series of user-driven events to drive its internal retry logic, such as retrying failed BlackBerry Infrastructure requests. Your application must determine the best event(s) to use to drive this logic. In the optimum case, your application will use this message whenever your application goes from being 'not on the screen' to being 'on the screen'. This transition event is considered to be a good representation of the user becoming interested in interacting with Spark Communications Services again, and thus a good event to use as a user-driver retry trigger. However, your application may choose to report only when specific screens transition to be 'on the screen', or tie this trigger to an explicit user action such as a 'Refresh' button.

Your application does not need to "rate limit" or otherwise filter 'retryServerRequests' messages.

Attributes:
NameTypeRequiredSinceLoggableDescription
Examples:
[
    {
        "retryServerRequests": {}
    }
]

search

Namesearch
Since2015.06
DirectionOutgoing

Search bbmcore's local data. This will search for chats that contain messages that contain the search 'text'.

Your application will receive a 'searchResult' in response.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequired2015.06YesThe cookie value that will be included in the searchResult sent in response to this request.
returnIdentifierbooleanOptional2016.03YesIff present, this will specify whether to return an identifier, if applicable, with each search result. As multiple results that are identical but for the identifier can be returned, turning off identifiers may result in a different set of matches, as these otherwise different results become identical without identifiers and are coalesced into a single result. The default is to return an identifier.
suggestedMaxResultsnumber (unsigned 64-bit int)Optional2015.06YesIff present, bbmcore will use this suggestion for the number of results returned. This is where the priority sequence comes into play.
textstringRequired2015.06NoThe text for which the search is being requested. A simple substring match is to be performed. A minimum length of 1 character is required.
Examples:
[
    {
        "search": {
            "text": "foo", 
            "cookie": "search-1"
        }
    }, 
    {
        "search": {
            "text": "foobar", 
            "suggestedMaxResults": 50, 
            "cookie": "search-2"
        }
    }, 
    {
        "search": {
            "text": "foobarbaz", 
            "cookie": "search-3", 
            "returnIdentifier": false
        }
    }
]

searchResult

NamesearchResult
Since2015.06
DirectionIncoming

Sent in response to a search request to provide its matching results.

Attributes:
NameTypeRequiredSinceLoggableDescription
cookiestringRequired2015.06YesThe cookie value that was provided in the request.
elementsarrayRequired2015.06NoThe meta-data describing the results of the search.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectOptional2015.06NoThe meta-data describing a single search result.
NameTypeRequiredSinceLoggableDescription
chatIdstringRequiredR4NoHolds the unique identifier of the chat in which the searched text was found. For a legacy conversation, this is the 8 lower-case letter URI id.
identifierstringOptional2015.12YesA key to provide additional information on where the match occurred in the case that the match was not on message content. This field will be present only if it is requested to be enabled in the search request. When present, the contents of this value depend on the type (see the 'type' documentation for details).
messageIdstring (unsigned 64-bit int in base 10)Optional2015.12YesA key to identify the message in the conversation in which a match was found. This is always an FK into chatMessage (or message for legacy).
typestringRequired2015.06YesThe type of search result. This is where the text was found.

This field is an enumeration.

MemberDescription
Message

The chat contains a text message that matched the search.

The 'chatId' field identifies the chat.

The 'messageId' field will be a foreign key into 'chatMessage' pointing to the most recent matched message.

The 'identifier' field will not be present.

Subject

The chat has a subject which matched the search.

The 'chatId' field identifies the chat.

The 'messageId' field will not be present.

The 'identifier' field will not be present.

Examples:
[
    {
        "searchResult": {
            "elements": [
                {
                    "identifier": "3", 
                    "type": "DisplayName", 
                    "chatId": "17"
                }, 
                {
                    "type": "Subject", 
                    "chatId": "25894"
                }
            ], 
            "cookie": "search-1"
        }
    }
]

setupError

NamesetupError
Since2.1
DirectionIncoming

Sent by bbmcore when a setup attempt encounters an error. The error does not mean that bbmcore has stopped trying to complete setup. In all cases, the 'authTokenState' and the 'setupState' will be updated as necessary and your application must respect and react to those changes accordingly and at user speeds.

Attributes:
NameTypeRequiredSinceLoggableDescription
errorstringRequired2.1YesThe type of error encountered.

This field is an enumeration.

MemberDescription
CertificateError There was a problem with one of the setup steps due to a certificate error.
Forbidden The BlackBerry Infrastructure forbids this user from registering for an undisclosed reason. The user id provided in 'authToken' might be unusable.
PermanentServerError There was a serious problem with one of the setup steps.
TemporaryServerError There was a problem with one of the setup steps but it is possible that a retry will succeed.
Examples:
[
    {
        "setupError": {
            "error": "PermanentServerError"
        }
    }, 
    {
        "setupError": {
            "error": "TemporaryServerError"
        }
    }
]

setupRetry

NamesetupRetry
SinceR4
DirectionOutgoing

Requests that bbmcore restart setup after a previous setup attempt was stopped.

If the current 'setupState' 'state' global is 'DeviceSwitchRequired', this will move the user's profile from the user's other device to this one.

If the current 'setupState' 'state' global is 'Full', this will register and add the current endpoint to any existing endpoints.

This message will be ignored for any other 'setupState' 'state'.

Attributes:
NameTypeRequiredSinceLoggableDescription
Examples:
[
    {
        "setupRetry": {}
    }
]

statsCommitted

NamestatsCommitted
Since2015.04
DirectionOutgoing

Your application sends this message to indicate two things:

  1. Your application has taken custodianship of the most recently fetched 'stat' list values. Your application did (or will) record them in its reporting system.
  2. Those previously reported 'stat' values must no longer be included in future fetches of the 'stat' list. In other words, it resets the counters, but does so without losing the stats collected since the last 'stat' list fetch.

See the 'stat' list for a detailed explanation how to use this message.

Note that 'statsCommitted' always applies to the most recently fetched 'stat' list values. If no 'stat' list values have ever been fetched, this has no effect.

There is no reply to this message.

Attributes:
NameTypeRequiredSinceLoggableDescription
Examples:
[
    {
        "statsCommitted": {}
    }
]

syncError

NamesyncError
SinceR4
DirectionIncoming

Sent by bbmcore when there is an endpoint sync error after receiving an 'syncStart' message on the initiating endpoint.

Attributes:
NameTypeRequiredSinceLoggableDescription
errorstringRequiredR4YesThe type of endpoint sync error encountered.

This field is an enumeration.

MemberDescription
Failure The endpoint sync failed.
IncorrectPasscode

The provided passcode was incorrect.

Timeout The endpoint sync timed out before it could be completed.
Examples:
[
    {
        "syncError": {
            "error": "IncorrectPasscode"
        }
    }
]

syncPasscodeChange

NamesyncPasscodeChange
SinceR6
DirectionOutgoing

Applications that use the BlackBerry Key Management Service (KMS) send this message to bbmcore on an endpoint that has completed setup in order to change the passcode that must be provided by 'syncStart' on new endpoints.

This message uses information already known to this endpoint to protect the existing sync data in KMS with the new 'passcode'. The old passcode is not required and will not be checked. Because of this, applications can let users change the sync passcode without knowing the current sync passcode. In all circumstances, applications should take steps to re-confirm the identity of the user with a relevant credentials challenge before issuing this request to bbmcore.

The result of this action is reported by 'syncPasscodeChangeResult'. Applications must not issue overlapping requests.

This action does not deregister existing endpoints (unlike 'syncStart' with 'action' 'New').

It is an error to send a 'syncPasscodeChange' request when your application isn't using the BlackBerry Key Management Service or when setup hasn't yet completed.

Attributes:
NameTypeRequiredSinceLoggableDescription
passcodestringRequiredR6NoThe passcode to use when re-protecting the identity's existing sync data.
Examples:
[
    {
        "syncPasscodeChange": {
            "passcode": "newSecret"
        }
    }
]

syncPasscodeChangeResult

NamesyncPasscodeChangeResult
SinceR6
DirectionIncoming

This message reports the result of a previous 'syncPasscodeChange' request.

Attributes:
NameTypeRequiredSinceLoggableDescription
resultstringRequiredR6YesThe result of attempting to set a new passcode.

This field is an enumeration.

MemberDescription
Success The passcode has been changed.
TemporaryFailure A temporary error has occurred that prevented the passcode from being changed. The change will not automatically be retried.
Examples:
[
    {
        "syncPasscodeChangeResult": {
            "result": "Success"
        }
    }, 
    {
        "syncPasscodeChangeResult": {
            "result": "TemporaryFailure"
        }
    }
]

syncStart

NamesyncStart
SinceR4
DirectionOutgoing

This message is only used by applications that use the BlackBerry Key Management Service (KMS). When the 'setupState' is 'SyncRequired', your application must examine the 'syncPasscodeState' global.

Attributes:
NameTypeRequiredSinceLoggableDescription
actionstringOptionalR6Yes

This field is ignored by bbmcore unless your application uses the BlackBerry Key Management Service.

This controls whether the passcode is being used to try to unprotect existing keys or to protect new keys. See the message description for more information.

This field is an enumeration.

MemberDescription
Existing Valid only when 'syncPasscodeState' is 'Existing'. Try to use the 'passcode' to unprotect and import the existing sync data.
New Use the 'passcode' to protect and export new sync data. Any existing sync data will be deleted and all other endpoints will be deregistered.
passcodestringRequiredR4NoThis is the passcode used to protect sync data in the BlackBerry Key Management Service.
Examples:
[
    {
        "syncStart": {
            "passcode": "ABC123"
        }
    }, 
    {
        "syncStart": {
            "passcode": "NewSecret", 
            "action": "New"
        }
    }, 
    {
        "syncStart": {
            "passcode": "OldSecret", 
            "action": "Existing"
        }
    }
]

userKeysChanged

NameuserKeysChanged
SinceR6
DirectionIncoming

This message is sent by bbmcore only when your application uses the BlackBerry Key Management Service (KMS). It indicates that bbmcore has found new keys for a user.

This is not sent when the user gains their initial set of keys. It is sent only when the local endpoint has an existing set of keys for a given user and then later learns that the user has different keys for any reason.

This is not sent for the local user.

Attributes:
NameTypeRequiredSinceLoggableDescription
userUriuser keyRequiredR6YesThe URI of the user whose keys have changed.
Examples:
[
    {
        "userKeysChanged": {
            "userUri": "bbmpim://user/id/123"
        }
    }
]

userKeysImport

NameuserKeysImport
SinceR3
DirectionOutgoing

Request that bbmcore set one or more users' keys.

Your application should try to include keys for as many users as possible in a single 'userKeysImport' request (within BBMDS message size limits) for greater efficiency.

If no user with a given 'regId' exists, a new user is created with a 'keyState' of 'Synced' and protection enabled. If the import fails, no user is created at all and no response is sent by bbmcore.

If the user with a given 'regId' exists, the user's 'keyState' will be changed to 'Synced' and protection will be enabled for the user. If the import fails, the user's 'keyState' will remain unchanged.

To avoid event loops, your application must only react with 'userKeysImport' to changes of a user's 'keyState' to 'Import'. Your application must not react to updates from bbmcore that indicate the 'keyState' is 'Import' when the 'keyState' was already known to your application to be 'Import'. When your application first learns of a user (such as after starting up) and their 'keyState' is 'Import', your application should consider that a change and can react to it with 'userKeysImport'. In other words, your application must not import keys unless the 'keyState' is actually changing or being learned for the first time. By following this rule, failed imports will not result in tight event loops and will allow retries (at a minimum on application restart, but also whenever bbmcore decides to toggle the state).

Regardless of a user's 'keyState', if your application has external evidence that the user has for some reason newly available or updated keys, your application can use 'userKeysImport' to provide those keys, subject the event reaction restrictions documented above.

This message will be ignored by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
keysarrayRequiredR3YesThe list of user keys to set.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectRequiredR3YesThe keys for the user.
NameTypeRequiredSinceLoggableDescription
encryptionPublicKeystringRequiredR3NoThe unpadded base64url-encoded encryption public key.
regIdstringRequiredR3YesThe regId of the user the keys are for. If no user with the given regId exists, one will be created.
signingPublicKeystringRequiredR3NoThe unpadded base64url-encoded signing public key.
Examples:
[
    {
        "userKeysImport": {
            "keys": [
                {
                    "regId": "123", 
                    "encryptionPublicKey": "ZW5jcnlwdGlvblB1YmxpY0tleTEyMw", 
                    "signingPublicKey": "c2lnbmluZ1B1YmxpY0tleTEyMw"
                }, 
                {
                    "regId": "321", 
                    "encryptionPublicKey": "ZW5jcnlwdGlvblB1YmxpY0tleTMyMQ", 
                    "signingPublicKey": "c2lnbmluZ1B1YmxpY0tleTMyMQ"
                }
            ]
        }
    }
]

userKeysImportFailure

NameuserKeysImportFailure
SinceR4
DirectionIncoming

Indicates that one or more user's keys received in 'userKeysImport' failed to import.

This message will not be sent by bbmcore if your application uses the BlackBerry Key Management Service.

Attributes:
NameTypeRequiredSinceLoggableDescription
regIdsarrayRequiredR4YesThe list of regIds that failed to import.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
stringRequiredR4YesThe regId that failed to import.
Examples:
[
    {
        "userKeysImportFailure": {
            "regIds": [
                "123", 
                "321"
            ]
        }
    }
]

wipe

Namewipe
Since2016.06
DirectionOutgoing

Request that bbmcore forget all information associated with the current Spark Communications identity by deleting all data and stopping, thus triggering a required BBMDS resync by your application (as is necessary on all BBMDS reconnects).

Attributes:
NameTypeRequiredSinceLoggableDescription
Examples:
[
    {
        "wipe": {}
    }
]

All Lists

The list API is used to synchronize a list of elements between the application and bbmcore. Each list has a type, indicating the type of elements in the list and how the list is used by bbmcore.

Bbmcore owns the model and your application is stateless with respect to it. In other words, bbmcore sends a message to your application every time the list changes, even if the change was requested by your application. The application reacts to these events and occasionally makes requests from bbmcore. Bbmcore has the option to decide how it reacts to your application's requests. Some requests may be ignored or result in changes to multiple lists.

List messages sent from bbmcore start with the prefix list. These are documented with the other incoming messages. The contract for these messages is the same regardless of the list type and your application is responsible for reacting correctly to any list message sent from bbmcore sent at any time. Bbmcore is free to use these messages to change the list contents at any time. Bbmcore is also required to notify your application of every change to a list (if such changes are supported by the list's events), regardless of how that change occurred. For example, bbmcore cannot omit sending a change notification to your application just because the change was requested by your application.

The following table summarizes the messages in the list protocol:

Message Message Type Elements Description
listAdd Event Full Adds one or more elements to the list.
listAll Event None Sends the entire list contents to your application.
listChange Event Partial Changes specific attributes in one or more elements in the list.
listChunk Event Full This is a degenerate message that can only follow 'listAll' or 'listElements' to carry the actual elements. It is omitted from the documentation of supported event messages because it is implied when those leading messages are supported.
listElements Event None Updates the entire state of specific elements in the list.
listRemove Event Primary key Removes one or more elements to the list.
listResync Event None Indicates that elements of the list that match the given criteria have potentially changed or been removed.
requestListAdd Action Partial Requests that bbmcore add a new element to the list.
requestListAll Action None Requests full states for all elements.
requestListChange Action Partial Requests that bbmcore change an existing element in the list.
requestListElements Action Primary key Requests full states for one or more elements.
requestListRemove Action Primary key Requests that bbmcore remove an existing element from the list.
requestListMatching Action None Requests all elements whose attributes exactly match the criteria supplied.

Many list messages contain an "elements" attribute, which either contain full or partial element states, or only contain primary keys. The table above describes what sort of elements show up in each message. The following table describes the meaning of the various element types.

Element Type Description
Full The 'listAdd' and 'listChunk' messages contain full element states. Full states contain all required attributes, and if any optional attributes are not present, they are reset to their default values.
Partial

For the 'listChange' and 'requestListChange' events, the primary key is required and all other attributes are optional, even if they are marked as required in the element schema. Attributes that are not present are treated as unmodified. No attributes are reset to their defaults. In the case of 'requestListChange', only a subset of attributes (documented for each list) may be included in the message.

In the case of 'requestListAdd', only a subset of attributes may be included. If an attribute in the subset is marked as required, it is also required in the 'requestListAdd'. If an attribute in the subset is marked as optional, it is reset to its default if not present. Attributes outside the subset may not be included in a 'requestListAdd' even if they are marked as required. The primary key is only required by 'requestListAdd' if named in the subset.

Primary key The 'listRemove', 'requestListRemove', and 'requestListElements' messages only contain primary keys. No other attributes may be present, even if they are marked as required.
None The 'listAll', 'listElements', and 'requestListAll' messages do not directly contain an elements attribute, although in the first two cases the message will be followed by one or more 'listChunk' messages that do contain elements.

Not all lists support all messages. Each list defines which "action" and "event" messages it supports in its definition. Almost all lists (except those whose elements contain only one field) implicitly support 'listChange' and 'listElements'. There are no other implicitly supported messages.

The following table discusses some common key attributes of lists.

Attribute Description
type This is the unique identifier for the list type, included verbatim in the type attribute of every message in this list.
primaryKey Identifies the primary key for the list. If more than one attribute is named, the list uses a composite key. Certain list messages (such as 'listRemove') only require the primary key to be included for each element.
since The protocol version in which the list type was added. This is a rough guide for humans only because protocol version is not strong.

A typical message interaction for a list supporting 'requestListAll', 'requestListAdd', and 'requestListRemove' would look like this. In this example, the elements have two attributes: lineNum and text.

// Your application wakes up and requests the list of elements from bbmcore. Bbmcore decides to break the response into two chunks.
Outgoing: {"requestListAll":{"type":"test"}}
Incoming: {"listAll":{"type":"test"}}
Incoming: {"listChunk":{"type":"test", "elements":[{"lineNum":0, "text":"Hello"},{"lineNum":1, "text":"World"}]}}
Incoming: {"listChunk":{"type":"test", "elements":[{"lineNum":2, "text":"Testing"},{"lineNum":3, "text":"123"}], "last":true}}

// Your application requests that bbmcore add a new element to the list.
Outgoing: {"requestListAdd":{"type":"test", "elements":[{"lineNum":5, "text":"456"}]}}
Incoming: {"listAdd":{"type":"test", "elements":[{"lineNum":5, "text":"456"}]}}

// Bbmcore decides to add an additional element to the list for unrelated reasons.
Incoming: {"listAdd":{"type":"test", "elements":[{"lineNum":6, "text":"789"}]}}

// Your application requests that bbmcore remove one of the elements.
Outgoing: {"requestListRemove": {"type":"test", "elements":["lineNum":2]}}
Incoming: {"listRemove": {"type":"test", "elements":["lineNum":2]}}

appMessage

TypeappMessage
SinceR4
Primary keyid
ActionsrequestListAll, requestListChange, requestListElements, requestListRemove
EventslistAdd, listAll, listChange, listElements, listRemove

This list holds the set of application messages known to bbmcore. Application messages are application-specific messages with application-defined content sent to one or more identities for delivery to all their registered endpoints. Application messages are injected at the infrastructure level, not by typical endpoints. If you are interested in sending application messages to your application, please contact the Spark Communications Services sales team.

These messages are not processed by bbmcore but are stored for your application to consume as it sees fit. Only 1000 application messages will be stored by bbmcore at any one time. If more application messages arrive, older ones will be deleted to make room. No 'listRemove' notification will be sent for such removals.

Attributes:
NameTypeRequiredSinceLoggableDescription
dataobjectRequiredR4NoThe data of your application message in the form of a JSON object. The meaning of the JSON object's contents are defined by your application.
externalIdstringRequiredR4YesThe id of your application message, as specified by the system that injected it.
idstringRequiredR4YesThe local id of your application message.
localDataobjectRequiredR4YesThis field contains opaque local-only data managed by your application that is associated to your application message. A newly arrived application message always has an empty JSON object (i.e. {}) for its 'localData'.
postTimenumber (signed 64-bit int)RequiredR4YesThe time, in milliseconds since 1970 UTC, at which the message was posted for delivery.
Action Details:
MessagerequestListRemove
SinceR4

Use this to remove application messages.

MessagerequestListChange
SinceR4
AttributeslocalData

requestListChange is used by your application to change the 'localData' field of an application message.

Examples:
[
    {
        "listAdd": {
            "elements": [
                {
                    "localData": {}, 
                    "postTime": 1499459819000, 
                    "externalId": "456783-ltr392-873jklo", 
                    "id": "7", 
                    "data": {
                        "body": "Enjoy the secure messaging! Your messages are protected.", 
                        "ref": 1234, 
                        "title": "Welcome."
                    }
                }
            ], 
            "type": "appMessage"
        }
    }, 
    {
        "listAll": {
            "type": "appMessage"
        }
    }, 
    {
        "listChunk": {
            "type": "appMessage", 
            "elements": [
                {
                    "localData": {}, 
                    "postTime": 1499459819000, 
                    "externalId": "456783-ltr392-873jklo", 
                    "id": "7", 
                    "data": {
                        "body": "Enjoy the secure messaging! Your messages are protected.", 
                        "ref": 1234, 
                        "title": "Welcome."
                    }
                }
            ], 
            "last": true
        }
    }, 
    {
        "listRemove": {
            "elements": [
                {
                    "id": "7"
                }
            ], 
            "type": "appMessage"
        }
    }, 
    {
        "listElements": {
            "type": "appMessage"
        }
    }, 
    {
        "listChunk": {
            "type": "appMessage", 
            "elements": [
                {
                    "localData": {}, 
                    "postTime": 1499459819000, 
                    "externalId": "456783-ltr392-873jklo", 
                    "id": "7", 
                    "data": {
                        "body": "Enjoy the secure messaging! Your messages are protected.", 
                        "ref": 1234, 
                        "title": "Welcome."
                    }
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "localData": {}, 
                    "id": "7"
                }
            ], 
            "type": "appMessage"
        }
    }
]

chat

Typechat
Since2017.02
Primary keychatId
ActionsrequestListAll, requestListChange, requestListElements, requestListMatching
EventslistAdd, listAll, listChange, listElements, listRemove

This list contains an entry for each chat the user is participating in. Chats are backed by the BlackBerry Infrastructure, and they will be restored when signing into an existing Spark Communications identity.

Chats must be started explicitly via the 'chatStart' message, and content may be added using the 'chatMessageSend' message.

When bbmcore issues a 'listRemove' for a chat, or when the 'numMessages' counter decreases, it is not necessary to also issue a separate 'listRemove' for the messages. Your application will cleanup their cache of the (now orphaned) messages when appropriate.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdstringRequired2017.02YesThe unique identifier for this chat. This is used as the value portion of chat URIs. See the URIs section for information on the URI format.
dataobjectRequiredR6No

This field contains opaque data managed by your 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 a 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 'data' field of 'chatMessage' instead.

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

flagsstringRequired2017.02YesCompact read-only flags about the chat. Each flag that is 'true' has its corresponding letter present in the string. Each flag that is 'false' has its corresponding letter not present in the string. The letters will always be provided in alphabetical order.
Flag NameLetterSinceDescription
admin A R4 The local user is an admin for the chat, and may perform administrative actions such as promoting/demoting other participants to/from admin status, and removing other participants from the chat.
hidden H 2017.02 The chat has been hidden (by 'stopConversation'). The chat will automatically stop being hidden when:
  • the next incoming or outgoing 'chatMessage' is added, or
  • (iff this is a 1:1 chat) when a 'chatStart' request identifying this chat is received.
oneToOne O R4 The chat is the singular 1:1 chat between the local user and the other party. bbmcore 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.
invitePolicystringOptionalR4YesThe policy that controls who may invite participants to the chat. This only applies to chats that do not have the 'oneToOne' flag, in which case the field will always be present. The field will never be present for chats with the 'oneToOne' flag.

This field is an enumeration.

MemberDescription
AdminsOnly Only chat admins may invite participants to the chat.
ParticipantsOnly Only chat participants may invite participants to the chat.
keyStatestringOptional (Default=Synced)R3YesThe current state of the chat's key. New chats that are created with a key start in the 'Export' state. New chats that are created without a key start in the 'Import' state.

This field is an enumeration.

MemberDescription
Export The chat's key needs to be exported from bbmcore and placed into external storage. When using Cloud Key Storage, your application must perform this export using 'chatKeyExport'. When using the BlackBerry Key Management Service (KMS), bbmcore will do this automatically.
Import The chat's key needs to be retrieved from external storage and imported into bbmcore. When using Cloud Key Storage, your application must perform this import using 'chatKeysImport'. When using the BlackBerry Key Management Service (KMS), bbmcore will do this automatically.
Synced The chat's key is synced.
lastActivitynumber (unsigned 64-bit int)Required2017.02Yes

This holds the timestamp, in seconds since the POSIX epoch, of the most recent notable activity in the chat. Notable activity includes:

  • When a 'chat' is created, 'lastActivity' is set to the timestamp associated with the event that created the chat.
  • When a new 'chatMessage' is added to this chat, the 'timestamp' of that chat is used to set 'lastActivity'.

Note that the 'lastActivity' does not always increase. Messages can arrive with lower timestamps than previous messages or the current 'lastActivity' and their timestamps will be applied to this field.

lastMessagenumber (unsigned 64-bit int)Required2017.02YesThe identifier of the most recent message added to the history. When combined with the chatId, this is a foreign key into 'listChatMessage'. bbmcore notifies your application of new messages by incrementing this value.
localDataobjectRequired2017.02NoThis field contains opaque local-only data that is associated with this chat and managed by your application. This data is stored locally on this endpoint only.
mailboxIdstringRequiredR3YesThe identifier used externally to uniquely identify this chat. Empty when not known.
numMessagesnumber (unsigned 64-bit int)Required2017.02YesThe total number of messages in the chat. When this value decreases, messages have been removed from the 'old' end of the message list. When this value increases, messages have been added to the 'new' end of the message list. bbmcore will increment this attribute whenever a new message arrives.
numUnreadnumber (unsigned 64-bit int)RequiredR5YesThe number of incoming messages in the chat that the local user has yet to mark as Read.
privateDataobjectRequiredR7No

This field contains opaque data managed by your 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).

restorePointnumber (unsigned 64-bit int)Required2017.02YesThe identifier of the most recent message restored from the BlackBerry Infrastructure when the chat was joined or restored. Messages after this point are considered to have arrived while this endpoint was actively receiving content from the chat. This value is not updated when the message it identifies is no longer part of the chat. If no messages existed in the chat when it was created, joined, or restored, or if for some reason the restore point is unknown, then this will be zero.
statestringRequired2017.02YesThe state of the chat.

This field is an enumeration.

MemberDescription
Defunct The BlackBerry Infrastructure has notified bbmcore that 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. bbmcore will not send or receive any further messages for a chat in this state. bbmcore does not automatically remove defunct chats. Your application may remove it explicitly.
Ready The chat is ready to send and receive messages. Any delays in sending or receiving messages in this state are due only to BlackBerry Infrastructure connectivity and availability.
Restore The chat is currently restoring message history. Content added via 'chatMessageSend' will be queued to be sent and will still be added to the 'chatMessage' list.
Waiting The chat is not ready to send or receive messages because it is waiting on an unspecified "slow" activity. Content added via 'chatMessageSend' will be queued to be sent and will still be added to the 'chatMessage' list.
subjectstringRequired2017.02NoHolds the user-readable subject of the chat. This field has a maximum size of 128 code points.
Action Details:
MessagerequestListChange
SinceR2
Attributessubject, localData, privateData, data, keyState, invitePolicy

A 'requestListChange' message can be sent by your application to change certain fields of a chat.

The 'keyState' field can be set by your application to 'Synced' only, and only when your application is using Cloud Key Storage. See the 'chatKeyExport' message for details on when to do this.

The 'invitePolicy' field can be changed only if the local user is an admin of the chat.

MessagerequestListMatching
Description

Use requestListMatching to lookup subsets of this list.

Criteria
NameTypeSinceDescription
mailboxIdstringR5Match the single chat with the specified mailboxId. When this criterion is specified, all other criteria are ignored.
keyStatestringR3Match all chats with the given 'keyState'. Returns an empty list if no match is found, or any errors occur.
Examples:
[
    {
        "listAdd": {
            "elements": [
                {
                    "numMessages": 10, 
                    "numUnread": 0, 
                    "privateData": {}, 
                    "restorePoint": 0, 
                    "keyState": "Export", 
                    "state": "Ready", 
                    "lastActivity": 1098730987, 
                    "flags": "O", 
                    "lastMessage": 15, 
                    "localData": {}, 
                    "chatId": "38267", 
                    "data": {}, 
                    "mailboxId": "mbx123", 
                    "subject": "All your base"
                }, 
                {
                    "numMessages": 1000, 
                    "numUnread": 23, 
                    "privateData": {
                        "notificationPriority": "High", 
                        "chatNickname": "Friends from Work"
                    }, 
                    "expiry": 3600, 
                    "restorePoint": 500, 
                    "keyState": "Synced", 
                    "state": "Waiting", 
                    "lastActivity": 10987300000, 
                    "flags": "AP", 
                    "lastMessage": 10293873870, 
                    "localData": {
                        "someData": "someValue"
                    }, 
                    "chatId": "6", 
                    "data": {
                        "appContextId": "miZPa8ef1Xj5Vl7YmSyYVxKdbJDBIMNK", 
                        "avatar": "https://avatar.server/8GWl2rOF"
                    }, 
                    "invitePolicy": "AdminsOnly", 
                    "mailboxId": "", 
                    "subject": "Are belong to us"
                }
            ], 
            "type": "chat"
        }
    }, 
    {
        "listAll": {
            "type": "chat"
        }
    }, 
    {
        "listChunk": {
            "type": "chat", 
            "elements": [
                {
                    "numMessages": 10, 
                    "numUnread": 0, 
                    "privateData": {}, 
                    "restorePoint": 0, 
                    "keyState": "Export", 
                    "state": "Ready", 
                    "lastActivity": 1098730987, 
                    "flags": "O", 
                    "lastMessage": 15, 
                    "localData": {}, 
                    "chatId": "38267", 
                    "data": {}, 
                    "mailboxId": "mbx123", 
                    "subject": "All your base"
                }, 
                {
                    "numMessages": 1000, 
                    "numUnread": 23, 
                    "privateData": {
                        "notificationPriority": "High", 
                        "chatNickname": "Friends from Work"
                    }, 
                    "expiry": 3600, 
                    "restorePoint": 500, 
                    "keyState": "Synced", 
                    "state": "Waiting", 
                    "lastActivity": 10987300000, 
                    "flags": "AP", 
                    "lastMessage": 10293873870, 
                    "localData": {
                        "someData": "someValue"
                    }, 
                    "chatId": "6", 
                    "data": {
                        "appContextId": "miZPa8ef1Xj5Vl7YmSyYVxKdbJDBIMNK", 
                        "avatar": "https://avatar.server/8GWl2rOF"
                    }, 
                    "invitePolicy": "AdminsOnly", 
                    "mailboxId": "", 
                    "subject": "Are belong to us"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listRemove": {
            "elements": [
                {
                    "chatId": "38267"
                }, 
                {
                    "chatId": "6"
                }
            ], 
            "type": "chat"
        }
    }, 
    {
        "listElements": {
            "type": "chat"
        }
    }, 
    {
        "listChunk": {
            "type": "chat", 
            "elements": [
                {
                    "numMessages": 10, 
                    "numUnread": 0, 
                    "privateData": {}, 
                    "restorePoint": 0, 
                    "keyState": "Export", 
                    "state": "Ready", 
                    "lastActivity": 1098730987, 
                    "flags": "O", 
                    "lastMessage": 15, 
                    "localData": {}, 
                    "chatId": "38267", 
                    "data": {}, 
                    "mailboxId": "mbx123", 
                    "subject": "All your base"
                }, 
                {
                    "numMessages": 1000, 
                    "numUnread": 23, 
                    "privateData": {
                        "notificationPriority": "High", 
                        "chatNickname": "Friends from Work"
                    }, 
                    "expiry": 3600, 
                    "restorePoint": 500, 
                    "keyState": "Synced", 
                    "state": "Waiting", 
                    "lastActivity": 10987300000, 
                    "flags": "AP", 
                    "lastMessage": 10293873870, 
                    "localData": {
                        "someData": "someValue"
                    }, 
                    "chatId": "6", 
                    "data": {
                        "appContextId": "miZPa8ef1Xj5Vl7YmSyYVxKdbJDBIMNK", 
                        "avatar": "https://avatar.server/8GWl2rOF"
                    }, 
                    "invitePolicy": "AdminsOnly", 
                    "mailboxId": "", 
                    "subject": "Are belong to us"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "localData": {}, 
                    "keyState": "Export", 
                    "subject": "All your base", 
                    "data": {}, 
                    "chatId": "38267"
                }, 
                {
                    "keyState": "Synced", 
                    "localData": {
                        "someData": "someValue"
                    }, 
                    "chatId": "6", 
                    "data": {
                        "appContextId": "miZPa8ef1Xj5Vl7YmSyYVxKdbJDBIMNK", 
                        "avatar": "https://avatar.server/8GWl2rOF"
                    }, 
                    "invitePolicy": "AdminsOnly", 
                    "subject": "Are belong to us"
                }
            ], 
            "type": "chat"
        }
    }
]

chatMessage

TypechatMessage
Since2017.02
Primary keychatId, messageId
ActionsrequestListChange, requestListElements, requestListMatching
EventslistAdd, listChange, listElements, listResync

Each element in this list is a message in a chat. The primary key for each element is the 'chatId' and 'messageId'.

The range of valid message ids for a given chat can be found in the chat list as ['lastMessage' - 'numMessages', 'lastMessage'].

When a new message is added to a chat, bbmcore will first 'listAdd' the message entry, and then will 'listChange' the chat to update the 'lastMessage' and 'numMessages' fields.

Note that 'listRemove' is not supported for this list. The message counters maintained in the chat list indicate when messages have been removed from this list.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequired2017.02YesThe unique identifier of the chat to which this message belongs.
contentstringOptional2017.02NoHolds the text content of the message, when the 'tag' has such a concept; otherwise omitted.
dataobjectOptional2017.02Yes

This field contains opaque data managed by your application that is sent with the message. Unless specifically noted, bbmcore 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'.

NameTypeRequiredSinceLoggableDescription
AdminobjectOptionalR4YesInformation about an admin change. Sent by the user who made the change. bbmcore does read and write the 'data' object including this object when the 'tag' is 'Admin'.
NameTypeRequiredSinceLoggableDescription
promotionbooleanRequiredR4YesTrue if the user has been promoted to admin. False if they have been demoted.
userUriuser keyRequiredR4YesIdentifies the participant that has been updated.
RemoveobjectOptionalR4YesInformation about a participant removal. Sent by the user who made the removal.
NameTypeRequiredSinceLoggableDescription
userUriuser keyRequiredR4YesIdentifies the participant that has been removed.
filestringOptional2017.02No

A path to a large file that is not carried in the message. This file is uploaded or download by bbmcore automatically. For downloads, this will only be set once 'fileState' progresses to 'Done'.

A maximum file size limit of 128 MB is imposed by bbmcore. The size limit may change in future versions. Clients that encounter files that are larger than their maximums will not download them.

fileSizenumber (unsigned 64-bit int)OptionalR7No

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, this field will not be present. Otherwise, this value is available in all 'fileState' states, even 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.

In versions after this field was introduced, bbmcore automatically includes this size value when attaching a file to an outgoing message.

fileStatestringOptional2017.02Yes

Indicates the state of file upload or download.

Generally, whether the transfer is an upload or download is not exposed to your application. However, some states imply that the transfer is a download that can be started or restarted by the 'chatMessageFileDownload' message. The 'incoming' 'flag' on this 'chatMessage' does not indicate whether the transfer is an upload or download.

Bbmcore automatically handles temporary errors during uploads and downloads. Such errors and the retries that occur are not exposed to your application. Eventually, bbmcore will give up and place a transfer into either the 'Failed' or 'FailedAvailable' state.

This field is an enumeration.

MemberDescription
Available

Most downloads are automatically initiated and automatically retried by bbmcore. In some circumstances, such as joining a chat or restoring a chat's history, or when the 'chatMessageFileAutoDownload' global is false, bbmcore does not automatically download attachments.

This state indicates that the file is available to be downloaded but bbmcore isn't downloading it yet. Your application can send 'chatMessageFileDownload' to start the download.

Uploads are never in this state.

Done The upload or download has completed. For downloads, the 'file' path should now be set.
Failed

Bbmcore gave up trying to upload or download the file. Your application cannot ask bbmcore to try again.

Failed uploads always end up as 'Failed' (never 'FailedAvailable') and do not post a message entry to the network. Failed uploads can be retried by sending 'chatMessage' again.

FailedAvailable Bbmcore gave up trying to download the file. Your application can ask bbmcore to try again by sending 'chatMessageFileDownload'.
Transferring The file is being uploaded or downloaded.
flagsstringRequired2017.02YesCompact read-only flags about the message. Each flag that is 'true' has its corresponding letter present in the string. Each flag that is 'false' has its corresponding letter not present in the string. The letters will always be provided in alphabetical order.
Flag NameLetterSinceDescription
deleted D 2017.02 The message has been deleted.
incoming I 2017.02 The 'senderUri' is not the local user, and the message may be considered to be incoming from the local user's perspective. This is a convenience alias for inspecting the 'senderUri' field. The absence of this flag reflects the fact that the 'senderUri' is the local user.
unverified U 2017.02 The message's signature was not verified as being from the claimed sender. Despite this, the content of the message is made available to be processed or ignored as your application sees fit.
localDataobjectOptionalR5NoThis field contains opaque local-only data managed by your application that is associated to the message. This field will be omitted until your application sets it via 'requestListChange'. When present, it will always be a valid JSON object.
messageIdstring (unsigned 64-bit int in base 10)Required2017.02YesThe unique identifier for this message. These are consecutive integers, ordered by arrival time. The range of valid integers for a given chat is stored in 'listChat's 'lastMessage' and 'numMessages' values.
recallstringOptional (Default=None)2017.02YesThis field indicates the recall state of the message.

This field is an enumeration.

MemberDescription
Failed For an outgoing message only, the recall request could not be sent to the BlackBerry Infrastructure. The recall request may be retried.
None The message is not recalled.
Recalled The message has been recalled.
Recalling For an outgoing message only, the recall request is in the process of being sent to the BlackBerry Infrastructure.
refarrayOptionalR5Yes

A 'chatMessage' can reference other messages or be referenced by other messages.

All references are directional and known to both messages involved. If message A references message B, then A has an entry in its 'ref' array with the 'messageId' of B, and B has an entry in its 'refBy' array that counts the reference from A.

Each reference in the 'ref' array has an application-specified 'tag' that indicates what kind of reference it is. A single message can only have one 'ref' for each tag string. Your application uses 'tag' strings to allow multiple different kinds of references between messages. For example, a message could both 'Quote' one message and 'Edit' another.

Each reference in the 'refBy' array has the same application-specified tag. A single message can have multiple references to it with the same 'tag'. To find all messages that refer to a given message, use 'requestListMatching' with the 'tag' and the 'messageId' of the referred-to message. Because the number of incoming references to a message can be large, only the most recent referring message is identified by 'newestRef' in 'refBy', along with a count of the total number of referring messages.

When there are no references to any other messages, the 'ref' field is omitted.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectRequiredR5YesEach element of the 'ref' array represents a single reference to another 'chatMessage'.
NameTypeRequiredSinceLoggableDescription
messageIdchatMessage keyRequiredR5YesThe messageId being referenced. If this contains the id of an element that does not currently exist in the 'chatMessage' list, then this message references another message that has been removed. If this is the empty string, then this 'chatMessage' references another message that is not currently known. It could have been deleted or its delivery could have been delayed. If the message becomes known, this 'messageId' will be updated to refer to it.
tagstringRequiredR5YesYour application-specified tag that indicates what kind of reference it is. A single 'chatMessage' can only have one 'ref' for each tag string. If a tag string appears more than once, subsequent instances are ignored.

This field is an enumeration.

MemberDescription
Edit This message edits the referenced message.
Quote This message quotes the referenced message.
Thread This message belongs to a thread that has the referenced message as its parent.
refByarrayOptionalR5Yes

See 'ref' for an explanation of 'ref' and 'refBy'.

This field will be omitted entirely if there are no references from other messages.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
objectRequiredR5YesEach element of the 'refBy' array represents one or more references from another 'chatMessage'.
NameTypeRequiredSinceLoggableDescription
countnumber (unsigned 64-bit int)RequiredR5YesThe number of messages referencing this message via the tag. To find all messages that refer to a given message, use 'requestListMatching' with this 'tag' and the 'messageId' of this referred-to 'chatMessage'.
newestRefchatMessage keyRequiredR5YesThe newest messageId referencing this message via the tag. If this contains the id of an element that does not currently exist in the 'chatMessage' list, then this message references another message that has been removed. This will not be the empty string.
tagstringRequiredR5YesYour application-specified tag that indicates what kind of reference it is.

This field is an enumeration.

MemberDescription
Edit This message edits the referenced message.
Quote This message quotes the referenced message.
Thread This message belongs to a thread that has the referenced message as its parent.
senderUriuser keyRequired2017.02YesHolds the user URI of the sender of this message. See the URIs section for information on the URI format.
statestringRequired2017.02YesThis field indicates the overall delivery state of the message.

This field is an enumeration.

MemberDescription
Delivered The message has been delivered to at least one recipient.
Failed The message failed to be sent.
Read The message has been read by at least one recipient.
Sending The message is in the process of being sent to the BlackBerry Infrastructure.
Sent The message has been accepted by the BlackBerry Infrastructure.
stateIsPartialbooleanRequired2017.02YesThis indicates whether or not the state applies to some (true) or all (false) recipients.
tagstringRequired2017.02YesIndicates the type of content this message represents.

This field is an enumeration.

MemberDescription
Admin The message contains an admin change. This tag contains no content. The 'data' must contain 'Admin'.
Gap The message history contains a gap at this position where messages have been permanently lost. The 'senderUri' will be that of the local user, the 'state' will be 'Sent', and the 'timestamp' will be the time the gap was detected. This tag has no 'content'
Join The sender has joined the chat. This tag has no 'content'.
Leave The sender has left the chat. This tag has no 'content'. The 'data', if present, must contain 'Leave'.
Remove This message indicates that the sending user has removed another user from the chat. This tag contains no content. The 'data' must contain 'Remove' and will indicate which user has been removed.
Shred The sender has requested that all previously sent messages be recalled. This tag has no 'content''.
Subject The sender has changed the chat's 'subject'. The content contains the new subject.
Text The message contains plain text content. This tag requires 'content'.
thumbstringOptional2017.02NoA path to a small file that is carried in the message.
timestampnumber (unsigned 64-bit int)Required2017.02YesHolds the POSIX timestamp of the message.
Action Details:
MessagerequestListChange
SinceR5
AttributeslocalData

requestListChange may be used to change certain fields of a message.

MessagerequestListMatching
Description

Use requestListMatching to lookup subsets of this list.

Criteria
NameTypeSinceDescription
chatIdstring2017.02Filters the requested list by the 'chatId' attribute. This field is required, and at least one of the other fields must also be present.
tagstring2017.02When provided, the requested list will be filtered by the 'tag' attribute. 'Text' is not a supported value for this criteria.
refobjectR5When present, this criterion filters the requested list to only those messages that reference another individual message. In the 'requestListMatching' request, this 'ref' field's value must be a single element with 'tag' and 'messageId' fields that will be used to match the 'chatMessage' element's 'ref' array. Any 'chatMessage' that has a 'ref' with the same 'tag' and 'messageId' will match.
Event Details:
MessagelistResync
Description

bbmcore will emit this event to indicate that elements of the list that match the given criteria have potentially changed or been removed.

Criteria
NameTypeSinceDescription
chatIdstring2017.02Elements of this list with a 'chatId' matching the 'chatId' of this message, have changed or been removed.
Examples:
[
    {
        "listAdd": {
            "elements": [
                {
                    "content": "Hello world!", 
                    "timestamp": 30987309874, 
                    "state": "Delivered", 
                    "stateIsPartial": false, 
                    "senderUri": "bbmpim://user/id/29", 
                    "tag": "Text", 
                    "flags": "I", 
                    "messageId": "793873", 
                    "localData": {
                        "field": "value"
                    }, 
                    "recall": "None", 
                    "ref": [
                        {
                            "tag": "Quote", 
                            "messageId": "236"
                        }, 
                        {
                            "tag": "Edit", 
                            "messageId": "56"
                        }, 
                        {
                            "tag": "Thread", 
                            "messageId": "8"
                        }
                    ], 
                    "chatId": "8475"
                }, 
                {
                    "refBy": [
                        {
                            "count": 1, 
                            "tag": "Quote", 
                            "newestRef": "793873"
                        }, 
                        {
                            "count": 7, 
                            "tag": "Thread", 
                            "newestRef": "793873"
                        }
                    ], 
                    "timestamp": 30987309921, 
                    "state": "Delivered", 
                    "stateIsPartial": false, 
                    "senderUri": "bbmpim://user/id/29", 
                    "tag": "Join", 
                    "flags": "I", 
                    "messageId": "236", 
                    "localData": {}, 
                    "recall": "None", 
                    "chatId": "5"
                }, 
                {
                    "content": "Goodbye cruel world!", 
                    "timestamp": 309873099870, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Text", 
                    "flags": "", 
                    "messageId": "799873", 
                    "recall": "None", 
                    "chatId": "4347"
                }, 
                {
                    "fileState": "Done", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Admin", 
                    "flags": "", 
                    "file": "/files/report.doc", 
                    "messageId": "799874", 
                    "recall": "None", 
                    "data": {
                        "Admin": {
                            "promotion": true, 
                            "userUri": "bbmpim://user/id/1"
                        }, 
                        "priority": "None"
                    }, 
                    "chatId": "4347"
                }, 
                {
                    "fileState": "Done", 
                    "content": "Here is my report", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "File", 
                    "flags": "", 
                    "file": "/files/report.doc", 
                    "messageId": "799874", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "File": {
                            "suggestedFilename": "report.doc"
                        }
                    }, 
                    "chatId": "4347"
                }, 
                {
                    "content": "Follow me on Glympse: www.glympse.com", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Glympse", 
                    "flags": "", 
                    "messageId": "6", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Glympse": {
                            "id": "123234232"
                        }
                    }, 
                    "chatId": "6"
                }, 
                {
                    "content": "Follow me on Glympse: www.glympse.com", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "GlympseRequest", 
                    "flags": "", 
                    "messageId": "7", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "GlympseRequest": {
                            "duration": 300
                        }
                    }, 
                    "chatId": "7"
                }, 
                {
                    "content": "Important Message", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Text", 
                    "flags": "", 
                    "messageId": "8", 
                    "recall": "None", 
                    "data": {
                        "priority": "High"
                    }, 
                    "chatId": "8"
                }, 
                {
                    "content": "The answer is 2.", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Quote", 
                    "flags": "IU", 
                    "messageId": "9", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Quote": {
                            "text": "What is 1+1?", 
                            "timestamp": 562737600, 
                            "source": "John Doe"
                        }
                    }, 
                    "chatId": "9"
                }, 
                {
                    "content": "Me too!", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "ReferencedUpdate", 
                    "flags": "", 
                    "messageId": "10", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "ReferencedUpdate": {
                            "type": "PersonalMessage", 
                            "update": "Looking forward to this weekend."
                        }
                    }, 
                    "chatId": "10"
                }, 
                {
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Remove", 
                    "flags": "", 
                    "messageId": "799874", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Remove": {
                            "userUri": "bbmpim://user/id/1"
                        }
                    }, 
                    "chatId": "4347"
                }, 
                {
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Screencap", 
                    "flags": "", 
                    "messageId": "11", 
                    "recall": "None", 
                    "chatId": "11"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/12", 
                    "tag": "Call", 
                    "flags": "", 
                    "messageId": "12", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Call": {
                            "callType": "Video", 
                            "eventType": "Ended", 
                            "duration": 326, 
                            "secure": false
                        }
                    }, 
                    "chatId": "12"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/12", 
                    "tag": "InviteStatus", 
                    "flags": "", 
                    "messageId": "12", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "InviteStatus": {
                            "status": "InterOrgRestriction"
                        }
                    }, 
                    "chatId": "12"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/12", 
                    "tag": "Leave", 
                    "flags": "", 
                    "messageId": "12", 
                    "recall": "None", 
                    "data": {
                        "Leave": {
                            "reason": "InterOrgRestriction"
                        }, 
                        "priority": "None"
                    }, 
                    "chatId": "12"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/12", 
                    "tag": "Leave", 
                    "flags": "", 
                    "messageId": "12", 
                    "recall": "None", 
                    "chatId": "12"
                }, 
                {
                    "timestamp": 309873090861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/13", 
                    "tag": "Location", 
                    "flags": "", 
                    "messageId": "13", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Location": {
                            "city": "Halifax", 
                            "name": "Halifax, NS, Canada", 
                            "country": "Canada", 
                            "altitude": "3", 
                            "longitude": "-63.57822", 
                            "postalCode": "", 
                            "state": "NS", 
                            "street": "", 
                            "horizontalAccuracy": "90", 
                            "latitude": "44.64692"
                        }
                    }, 
                    "chatId": "13"
                }, 
                {
                    "content": "Let's discuss this with the others.", 
                    "timestamp": 309873090861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/3000", 
                    "tag": "MediaConf", 
                    "flags": "", 
                    "messageId": "2000", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "MediaConf": {
                            "url": "https://conf.bbm.bbmenterprise.com/join?appId=example", 
                            "requireAuth": false
                        }
                    }, 
                    "chatId": "1000"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/14", 
                    "tag": "Sticker", 
                    "flags": "", 
                    "messageId": "14", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Sticker": {
                            "id": "14"
                        }
                    }, 
                    "chatId": "14"
                }, 
                {
                    "fileState": "Done", 
                    "content": "Cats are funny!", 
                    "thumb": "/picture/funny_cat_small.jpg", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Picture", 
                    "flags": "", 
                    "file": "/picture/funny_cat.jpg", 
                    "messageId": "799874", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Picture": {
                            "mimeType": "image/jpeg", 
                            "suggestedFilename": "funny_cat.jpg"
                        }
                    }, 
                    "chatId": "15"
                }, 
                {
                    "fileState": "Done", 
                    "content": "Here's the sales rep's info", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/16", 
                    "tag": "Contact", 
                    "flags": "", 
                    "file": "/contact/JohnDoe.vcf", 
                    "messageId": "16", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Contact": {
                            "suggestedFilename": "JohnDoe.vcf"
                        }
                    }, 
                    "chatId": "16"
                }, 
                {
                    "fileState": "Done", 
                    "content": "Our meeting tomorrow", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/17", 
                    "tag": "Calendar", 
                    "flags": "", 
                    "file": "/calendar/meeting.ics", 
                    "messageId": "17", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Calendar": {
                            "suggestedFilename": "meeting.ics"
                        }
                    }, 
                    "chatId": "17"
                }, 
                {
                    "fileState": "Done", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/18", 
                    "tag": "VoiceNote", 
                    "flags": "", 
                    "file": "/voicenotes/note.amr", 
                    "messageId": "18", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "VoiceNote": {
                            "suggestedFilename": "note.amr"
                        }
                    }, 
                    "chatId": "18"
                }, 
                {
                    "timestamp": 30984323543, 
                    "state": "Delivered", 
                    "stateIsPartial": false, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Gap", 
                    "flags": "I", 
                    "messageId": "8575645352", 
                    "recall": "None", 
                    "chatId": "38663836456"
                }, 
                {
                    "content": "https://www.blackberry.com/us/en/products/blackberry-spark-platform", 
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": false, 
                    "senderUri": "bbmpim://user/id/14", 
                    "tag": "Link", 
                    "flags": "", 
                    "messageId": "19", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Link": {
                            "url": "https://www.blackberry.com/us/en/products/blackberry-spark-platform", 
                            "image": "https://rimblogs.files.wordpress.com/2017/06/business-man-secure.png", 
                            "name": "BlackBerry Spark", 
                            "descr": "BlackBerry Spark is the only Enterprise of Things (EoT) platform designed and built for ultra-secure hyperconnectivity from the kernel to the edge.", 
                            "title": "BlackBerry Spark: The EoT Platform for Ultra-secure Hyperconnectivity"
                        }
                    }, 
                    "chatId": "19"
                }
            ], 
            "type": "chatMessage"
        }
    }, 
    {
        "listElements": {
            "type": "chatMessage"
        }
    }, 
    {
        "listChunk": {
            "type": "chatMessage", 
            "elements": [
                {
                    "content": "Hello world!", 
                    "timestamp": 30987309874, 
                    "state": "Delivered", 
                    "stateIsPartial": false, 
                    "senderUri": "bbmpim://user/id/29", 
                    "tag": "Text", 
                    "flags": "I", 
                    "messageId": "793873", 
                    "localData": {
                        "field": "value"
                    }, 
                    "recall": "None", 
                    "ref": [
                        {
                            "tag": "Quote", 
                            "messageId": "236"
                        }, 
                        {
                            "tag": "Edit", 
                            "messageId": "56"
                        }, 
                        {
                            "tag": "Thread", 
                            "messageId": "8"
                        }
                    ], 
                    "chatId": "8475"
                }, 
                {
                    "refBy": [
                        {
                            "count": 1, 
                            "tag": "Quote", 
                            "newestRef": "793873"
                        }, 
                        {
                            "count": 7, 
                            "tag": "Thread", 
                            "newestRef": "793873"
                        }
                    ], 
                    "timestamp": 30987309921, 
                    "state": "Delivered", 
                    "stateIsPartial": false, 
                    "senderUri": "bbmpim://user/id/29", 
                    "tag": "Join", 
                    "flags": "I", 
                    "messageId": "236", 
                    "localData": {}, 
                    "recall": "None", 
                    "chatId": "5"
                }, 
                {
                    "content": "Goodbye cruel world!", 
                    "timestamp": 309873099870, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Text", 
                    "flags": "", 
                    "messageId": "799873", 
                    "recall": "None", 
                    "chatId": "4347"
                }, 
                {
                    "fileState": "Done", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Admin", 
                    "flags": "", 
                    "file": "/files/report.doc", 
                    "messageId": "799874", 
                    "recall": "None", 
                    "data": {
                        "Admin": {
                            "promotion": true, 
                            "userUri": "bbmpim://user/id/1"
                        }, 
                        "priority": "None"
                    }, 
                    "chatId": "4347"
                }, 
                {
                    "fileState": "Done", 
                    "content": "Here is my report", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "File", 
                    "flags": "", 
                    "file": "/files/report.doc", 
                    "messageId": "799874", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "File": {
                            "suggestedFilename": "report.doc"
                        }
                    }, 
                    "chatId": "4347"
                }, 
                {
                    "content": "Follow me on Glympse: www.glympse.com", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Glympse", 
                    "flags": "", 
                    "messageId": "6", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Glympse": {
                            "id": "123234232"
                        }
                    }, 
                    "chatId": "6"
                }, 
                {
                    "content": "Follow me on Glympse: www.glympse.com", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "GlympseRequest", 
                    "flags": "", 
                    "messageId": "7", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "GlympseRequest": {
                            "duration": 300
                        }
                    }, 
                    "chatId": "7"
                }, 
                {
                    "content": "Important Message", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Text", 
                    "flags": "", 
                    "messageId": "8", 
                    "recall": "None", 
                    "data": {
                        "priority": "High"
                    }, 
                    "chatId": "8"
                }, 
                {
                    "content": "The answer is 2.", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Quote", 
                    "flags": "IU", 
                    "messageId": "9", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Quote": {
                            "text": "What is 1+1?", 
                            "timestamp": 562737600, 
                            "source": "John Doe"
                        }
                    }, 
                    "chatId": "9"
                }, 
                {
                    "content": "Me too!", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "ReferencedUpdate", 
                    "flags": "", 
                    "messageId": "10", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "ReferencedUpdate": {
                            "type": "PersonalMessage", 
                            "update": "Looking forward to this weekend."
                        }
                    }, 
                    "chatId": "10"
                }, 
                {
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Remove", 
                    "flags": "", 
                    "messageId": "799874", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Remove": {
                            "userUri": "bbmpim://user/id/1"
                        }
                    }, 
                    "chatId": "4347"
                }, 
                {
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Screencap", 
                    "flags": "", 
                    "messageId": "11", 
                    "recall": "None", 
                    "chatId": "11"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/12", 
                    "tag": "Call", 
                    "flags": "", 
                    "messageId": "12", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Call": {
                            "callType": "Video", 
                            "eventType": "Ended", 
                            "duration": 326, 
                            "secure": false
                        }
                    }, 
                    "chatId": "12"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/12", 
                    "tag": "InviteStatus", 
                    "flags": "", 
                    "messageId": "12", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "InviteStatus": {
                            "status": "InterOrgRestriction"
                        }
                    }, 
                    "chatId": "12"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/12", 
                    "tag": "Leave", 
                    "flags": "", 
                    "messageId": "12", 
                    "recall": "None", 
                    "data": {
                        "Leave": {
                            "reason": "InterOrgRestriction"
                        }, 
                        "priority": "None"
                    }, 
                    "chatId": "12"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/12", 
                    "tag": "Leave", 
                    "flags": "", 
                    "messageId": "12", 
                    "recall": "None", 
                    "chatId": "12"
                }, 
                {
                    "timestamp": 309873090861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/13", 
                    "tag": "Location", 
                    "flags": "", 
                    "messageId": "13", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Location": {
                            "city": "Halifax", 
                            "name": "Halifax, NS, Canada", 
                            "country": "Canada", 
                            "altitude": "3", 
                            "longitude": "-63.57822", 
                            "postalCode": "", 
                            "state": "NS", 
                            "street": "", 
                            "horizontalAccuracy": "90", 
                            "latitude": "44.64692"
                        }
                    }, 
                    "chatId": "13"
                }, 
                {
                    "content": "Let's discuss this with the others.", 
                    "timestamp": 309873090861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/3000", 
                    "tag": "MediaConf", 
                    "flags": "", 
                    "messageId": "2000", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "MediaConf": {
                            "url": "https://conf.bbm.bbmenterprise.com/join?appId=example", 
                            "requireAuth": false
                        }
                    }, 
                    "chatId": "1000"
                }, 
                {
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/14", 
                    "tag": "Sticker", 
                    "flags": "", 
                    "messageId": "14", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Sticker": {
                            "id": "14"
                        }
                    }, 
                    "chatId": "14"
                }, 
                {
                    "fileState": "Done", 
                    "content": "Cats are funny!", 
                    "thumb": "/picture/funny_cat_small.jpg", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Picture", 
                    "flags": "", 
                    "file": "/picture/funny_cat.jpg", 
                    "messageId": "799874", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Picture": {
                            "mimeType": "image/jpeg", 
                            "suggestedFilename": "funny_cat.jpg"
                        }
                    }, 
                    "chatId": "15"
                }, 
                {
                    "fileState": "Done", 
                    "content": "Here's the sales rep's info", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/16", 
                    "tag": "Contact", 
                    "flags": "", 
                    "file": "/contact/JohnDoe.vcf", 
                    "messageId": "16", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Contact": {
                            "suggestedFilename": "JohnDoe.vcf"
                        }
                    }, 
                    "chatId": "16"
                }, 
                {
                    "fileState": "Done", 
                    "content": "Our meeting tomorrow", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/17", 
                    "tag": "Calendar", 
                    "flags": "", 
                    "file": "/calendar/meeting.ics", 
                    "messageId": "17", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Calendar": {
                            "suggestedFilename": "meeting.ics"
                        }
                    }, 
                    "chatId": "17"
                }, 
                {
                    "fileState": "Done", 
                    "timestamp": 309873099871, 
                    "state": "Delivered", 
                    "stateIsPartial": true, 
                    "senderUri": "bbmpim://user/id/18", 
                    "tag": "VoiceNote", 
                    "flags": "", 
                    "file": "/voicenotes/note.amr", 
                    "messageId": "18", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "VoiceNote": {
                            "suggestedFilename": "note.amr"
                        }
                    }, 
                    "chatId": "18"
                }, 
                {
                    "timestamp": 30984323543, 
                    "state": "Delivered", 
                    "stateIsPartial": false, 
                    "senderUri": "bbmpim://user/id/0", 
                    "tag": "Gap", 
                    "flags": "I", 
                    "messageId": "8575645352", 
                    "recall": "None", 
                    "chatId": "38663836456"
                }, 
                {
                    "content": "https://www.blackberry.com/us/en/products/blackberry-spark-platform", 
                    "timestamp": 309873099861, 
                    "state": "Delivered", 
                    "stateIsPartial": false, 
                    "senderUri": "bbmpim://user/id/14", 
                    "tag": "Link", 
                    "flags": "", 
                    "messageId": "19", 
                    "recall": "None", 
                    "data": {
                        "priority": "None", 
                        "Link": {
                            "url": "https://www.blackberry.com/us/en/products/blackberry-spark-platform", 
                            "image": "https://rimblogs.files.wordpress.com/2017/06/business-man-secure.png", 
                            "name": "BlackBerry Spark", 
                            "descr": "BlackBerry Spark is the only Enterprise of Things (EoT) platform designed and built for ultra-secure hyperconnectivity from the kernel to the edge.", 
                            "title": "BlackBerry Spark: The EoT Platform for Ultra-secure Hyperconnectivity"
                        }
                    }, 
                    "chatId": "19"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "localData": {
                        "field": "value"
                    }, 
                    "messageId": "793873", 
                    "chatId": "8475"
                }, 
                {
                    "localData": {}, 
                    "messageId": "236", 
                    "chatId": "5"
                }, 
                {
                    "messageId": "799873", 
                    "chatId": "4347"
                }, 
                {
                    "messageId": "799874", 
                    "chatId": "4347"
                }, 
                {
                    "messageId": "799874", 
                    "chatId": "4347"
                }, 
                {
                    "messageId": "6", 
                    "chatId": "6"
                }, 
                {
                    "messageId": "7", 
                    "chatId": "7"
                }, 
                {
                    "messageId": "8", 
                    "chatId": "8"
                }, 
                {
                    "messageId": "9", 
                    "chatId": "9"
                }, 
                {
                    "messageId": "10", 
                    "chatId": "10"
                }, 
                {
                    "messageId": "799874", 
                    "chatId": "4347"
                }, 
                {
                    "messageId": "11", 
                    "chatId": "11"
                }, 
                {
                    "messageId": "12", 
                    "chatId": "12"
                }, 
                {
                    "messageId": "12", 
                    "chatId": "12"
                }, 
                {
                    "messageId": "12", 
                    "chatId": "12"
                }, 
                {
                    "messageId": "12", 
                    "chatId": "12"
                }, 
                {
                    "messageId": "13", 
                    "chatId": "13"
                }, 
                {
                    "messageId": "2000", 
                    "chatId": "1000"
                }, 
                {
                    "messageId": "14", 
                    "chatId": "14"
                }, 
                {
                    "messageId": "799874", 
                    "chatId": "15"
                }, 
                {
                    "messageId": "16", 
                    "chatId": "16"
                }, 
                {
                    "messageId": "17", 
                    "chatId": "17"
                }, 
                {
                    "messageId": "18", 
                    "chatId": "18"
                }, 
                {
                    "messageId": "8575645352", 
                    "chatId": "38663836456"
                }, 
                {
                    "messageId": "19", 
                    "chatId": "19"
                }
            ], 
            "type": "chatMessage"
        }
    }
]

chatMessageFileProgress

TypechatMessageFileProgress
SinceR5
Primary keychatId, messageId
ActionsrequestListElements
EventslistAdd, listChange, listElements, listRemove

This list reports upload and download progress information for active 'chatMessage' file attachment transfers.

Each item in this list corresponds to a single 'chatMessage' entry and is identified by the same key fields: 'chatId' and 'messageId'. When an entry exists in this list, bbmcore is actively trying to upload or download the attached file. The fields of the entry in this list indicate the progress bbmcore has made in that active transfer. When an entry is removed from this list, bbmcore is no longer actively trying to transfer it. When a transfer attempt fails, it will not be represented in this list until bbmcore retries it, but the associated 'chatMessage' 'fileState' will still be 'Transferring'.

Changes in this list will be reported only when the previously reported value of 'bytes' and the current value of 'bytes' differ enough that the progress towards the 'total' achieves a different 5% increment.

For example, if a file was 100 bytes in 'total' and the previous report was 37 'bytes', then a change would only be reported for this entry after 'bytes' reached at least 40. A change from 37 to 39 would not be reported by bbmcore because 'bytes' must reach at least 40 to move from the 35-40% increment to the 40-45% (or higher) increment.

Your application doesn't have to wait for a change in 'bytes' to get an initial progress value for an active transfer it has previously been ignoring. Your application can query the list directly with 'requestListElements' at any time. When such a request returns no entry for a given pair of ids, it means that bbmcore isn't currently trying to upload or download the attached file or no progress information is available for the transfer. (See the caveat on 'total'.)

Attributes:
NameTypeRequiredSinceLoggableDescription
bytesnumber (unsigned 64-bit int)RequiredR5Yes

The number of bytes transferred so far in this attempt.

Your application must not depend on this reaching 'total' to mean the transfer succeeded or completed. Use the 'fileState' of the actual 'chatMessage' to determine the overall transfer state.

chatIdchat keyRequiredR5YesHolds the id of the chat that contains the attachment's message.
messageIdchatMessage keyRequiredR5YesHolds the id of the message (within that chat referred to by 'chatId') whose attachment's transfer progress is being reported.
totalnumber (unsigned 64-bit int)RequiredR5Yes

The total number of bytes expected in the transfer.

If for some reason the total number of bytes cannot be determined or if the total number of bytes is zero, the transfer will not report progress via this list. This doesn't mean that bbmcore isn't trying to perform the transfer in such cases.

Thus, this value is never zero and never changes until the list element is removed.

Examples:
[
    {
        "listAdd": {
            "elements": [
                {
                    "total": 1000, 
                    "messageId": "2", 
                    "bytes": 0, 
                    "chatId": "12"
                }, 
                {
                    "total": 32768, 
                    "messageId": "8122", 
                    "bytes": 16384, 
                    "chatId": "1"
                }, 
                {
                    "total": 400, 
                    "messageId": "8123", 
                    "bytes": 400, 
                    "chatId": "1"
                }
            ], 
            "type": "chatMessageFileProgress"
        }
    }, 
    {
        "listRemove": {
            "elements": [
                {
                    "messageId": "2", 
                    "chatId": "12"
                }, 
                {
                    "messageId": "8122", 
                    "chatId": "1"
                }, 
                {
                    "messageId": "8123", 
                    "chatId": "1"
                }
            ], 
            "type": "chatMessageFileProgress"
        }
    }, 
    {
        "listElements": {
            "type": "chatMessageFileProgress"
        }
    }, 
    {
        "listChunk": {
            "type": "chatMessageFileProgress", 
            "elements": [
                {
                    "total": 1000, 
                    "messageId": "2", 
                    "bytes": 0, 
                    "chatId": "12"
                }, 
                {
                    "total": 32768, 
                    "messageId": "8122", 
                    "bytes": 16384, 
                    "chatId": "1"
                }, 
                {
                    "total": 400, 
                    "messageId": "8123", 
                    "bytes": 400, 
                    "chatId": "1"
                }
            ], 
            "last": true
        }
    }
]

chatParticipant

TypechatParticipant
SinceR4
Primary keychatId, userUri
ActionsrequestListElements, requestListMatching
EventslistAdd, listChange, listElements, listRemove

This list holds the participants for each chat identified by chatId. The local user is never included in this list.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdstringRequiredR4YesThe id of the chat this participant is a member of.
flagsstringRequiredR4YesCompact read-only flags about the participant. Each flag that is 'true' has its corresponding letter present in the string. Each flag that is 'false' has its corresponding letter not present in the string. The letters will always be provided in alphabetical order.
Flag NameLetterSinceDescription
admin A R4 The participant is an admin for the chat. This only applies to chats without the 'oneToOne' flag.
statestringRequiredR4YesThe current state of the participant.

This field is an enumeration.

MemberDescription
Active The participant is active in the chat and will receive messages posted to the chat.
Left The participant has left the chat. They remain in the participant list to identify their historical messages.
Pending The participant is in the process of being invited to a chat.
userUriuser keyRequiredR4YesThe URI of the user this participant represents.
Action Details:
MessagerequestListMatching
Description

Use requestListMatching to lookup subsets of this list.

Criteria
NameTypeSinceDescription
chatIdstringR4When provided, all participants for the given chat will be returned. The local user's participant is not included. This criteria may not be used in combination with any other.
userUristringR5Must be used in combination with state. When provided, returns all participants from any chat if they match the given userUri and state.
statestringR5Must be used in combination with userUri.
Examples:
[
    {
        "listAdd": {
            "elements": [
                {
                    "state": "Active", 
                    "flags": "", 
                    "userUri": "bbmpim://user/id/123", 
                    "chatId": "2398734"
                }, 
                {
                    "state": "Pending", 
                    "flags": "A", 
                    "userUri": "bbmpim://user/id/321", 
                    "chatId": "77"
                }
            ], 
            "type": "chatParticipant"
        }
    }, 
    {
        "listRemove": {
            "elements": [
                {
                    "userUri": "bbmpim://user/id/123", 
                    "chatId": "2398734"
                }, 
                {
                    "userUri": "bbmpim://user/id/321", 
                    "chatId": "77"
                }
            ], 
            "type": "chatParticipant"
        }
    }, 
    {
        "listElements": {
            "type": "chatParticipant"
        }
    }, 
    {
        "listChunk": {
            "type": "chatParticipant", 
            "elements": [
                {
                    "state": "Active", 
                    "flags": "", 
                    "userUri": "bbmpim://user/id/123", 
                    "chatId": "2398734"
                }, 
                {
                    "state": "Pending", 
                    "flags": "A", 
                    "userUri": "bbmpim://user/id/321", 
                    "chatId": "77"
                }
            ], 
            "last": true
        }
    }
]

global

Typeglobal
Since2.1
Primary keyname
ActionsrequestListChange, requestListElements
EventslistChange, listElements

This list holds the set of global variables exchanged between your application and bbmcore. The list uses string keys and mixed-type values. The key is the variable name. The set of valid variables and their meaning is documented in the 'globals' section.

Attributes:
NameTypeRequiredSinceLoggableDescription
namestringRequired2.1YesString name of the global variable. This list has a closed set of valid variable names. See the 'global' section for information about the set of variables and their semantics.
valueanyRequired2.1YesValue of the variable. The type depends on the variable name, so ignore what 'type' is documented for this attribute here.
Action Details:
MessagerequestListChange
Since2.1
Attributesvalue

requestListChange is used for modifying the value of a global variable. Certain globals are read-only and will ignore attempts to modify their value. The schema of the value attribute must match the schema of the global itself. See the documentation of the global for more information.

Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "setupState", 
                    "value": {
                        "progressMessage": "Restoring", 
                        "state": "Ongoing"
                    }
                }, 
                {
                    "name": "endpointId", 
                    "value": "asd4fgdffssf3987bb0a"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "setupState", 
                    "value": {
                        "progressMessage": "Restoring", 
                        "state": "Ongoing"
                    }
                }, 
                {
                    "name": "endpointId", 
                    "value": "asd4fgdffssf3987bb0a"
                }
            ], 
            "type": "global"
        }
    }
]

stat

Typestat
SinceR5
Primary keyname
ActionsrequestListAll
EventslistAll, listChange, listElements

Your application uses this list to retrieve stats that bbmcore has recorded about its operation and performance. Stats recorded by bbmcore are local to the device and do not contain personally identifiable information. bbmcore will only ever provide this data to your application when requested to do so.

Every time your application retrieves this list with 'requestListAll', it can contain different data. Bbmcore remembers what values were sent in the most recent 'stat' list collected by your application until your application sends a 'statsCommitted' message. When it receives 'statsCommitted', bbmcore considers the values in the most recently collected 'stat' list to have been exported by your application and committed permanently. After that 'statsCommitted' message, subsequent collections of stats with this list will no longer include that committed data.

If your application can't commit the values it collected with 'requestListAll', it must not send 'statsCommitted'. In such cases, the next copy of of this list that your application collects will be even more up to date and will include the data returned previously (back to the previous 'statsCommitted').

The values in this list persist across bbmcore restarts, and a 'statsCommitted' message can and will complete a 'stats' retrieval even if it was from a previous incarnation of bbmcore.

Statistics whose values are zero when the list is requested are not included in the list.

No 'listElements' or 'listChange' will ever be sent for this list.

This list does not define which statistics are recorded. Interpretation of the statistics is intended to be done by offline analysis and reporting.

Attributes:
NameTypeRequiredSinceLoggableDescription
countarrayRequiredR5Yes

The count(s) associated with this statistic.

Iff there are multiple elements, then this statistic has multiple parts, each with its own scalar counter. Each part that has a non-zero count will be included with a number in the 'count' array and its part name in the 'part' array. The part's name and number will be at corresponding positions in the two arrays.

If no 'part' array is present, then the statistic does not have multiple parts and the 'count' array will have only one element.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
number (unsigned 64-bit int)RequiredR5YesThe count of this statistic (or this part of the statistic). This will always contain at least one element.
namestringRequiredR5YesThe name of the statistic.
partarrayOptionalR5Yes

Iff there are multiple elements, then this statistic has multiple parts, each with its own scalar counter. Each part that has a non-zero count will be included with a number in the 'count' array and its part name in the 'part' array. The part's name and number will be at corresponding positions in the two arrays.

If no 'part' array is present, then the statistic does not have multiple parts and the 'count' array will have only one element.

The following table describes the type of each array element.

TypeRequiredSinceLoggableDescription
stringRequiredR5YesThe name of this part of the statistic. If the 'part' array is present, it will always contain at least one part name.
Examples:
[
    {
        "listAll": {
            "type": "stat"
        }
    }, 
    {
        "listChunk": {
            "type": "stat", 
            "elements": [
                {
                    "count": [
                        1
                    ], 
                    "name": "setup"
                }, 
                {
                    "count": [
                        77
                    ], 
                    "name": "setup.err"
                }, 
                {
                    "count": [
                        12, 
                        1, 
                        2
                    ], 
                    "part": [
                        "ok", 
                        "500", 
                        "400"
                    ], 
                    "name": "mailbox.addMember"
                }, 
                {
                    "count": [
                        42
                    ], 
                    "part": [
                        "ok"
                    ], 
                    "name": "mailbox.removeMember"
                }, 
                {
                    "count": [
                        7, 
                        102, 
                        4
                    ], 
                    "part": [
                        "Picture", 
                        "Text", 
                        "File"
                    ], 
                    "name": "msg"
                }, 
                {
                    "count": [
                        1, 
                        2, 
                        4
                    ], 
                    "part": [
                        "4K", 
                        "8K", 
                        "64K"
                    ], 
                    "name": "msg.thumb.Picture"
                }, 
                {
                    "count": [
                        1, 
                        2, 
                        2, 
                        1, 
                        1
                    ], 
                    "part": [
                        "256K", 
                        "2M", 
                        "3M", 
                        "4M", 
                        "8M"
                    ], 
                    "name": "msg.file.Picture"
                }, 
                {
                    "count": [
                        2, 
                        1, 
                        1
                    ], 
                    "part": [
                        "128K", 
                        "48M", 
                        "128M"
                    ], 
                    "name": "msg.file.File"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listElements": {
            "type": "stat"
        }
    }, 
    {
        "listChunk": {
            "type": "stat", 
            "elements": [
                {
                    "count": [
                        1
                    ], 
                    "name": "setup"
                }, 
                {
                    "count": [
                        77
                    ], 
                    "name": "setup.err"
                }, 
                {
                    "count": [
                        12, 
                        1, 
                        2
                    ], 
                    "part": [
                        "ok", 
                        "500", 
                        "400"
                    ], 
                    "name": "mailbox.addMember"
                }, 
                {
                    "count": [
                        42
                    ], 
                    "part": [
                        "ok"
                    ], 
                    "name": "mailbox.removeMember"
                }, 
                {
                    "count": [
                        7, 
                        102, 
                        4
                    ], 
                    "part": [
                        "Picture", 
                        "Text", 
                        "File"
                    ], 
                    "name": "msg"
                }, 
                {
                    "count": [
                        1, 
                        2, 
                        4
                    ], 
                    "part": [
                        "4K", 
                        "8K", 
                        "64K"
                    ], 
                    "name": "msg.thumb.Picture"
                }, 
                {
                    "count": [
                        1, 
                        2, 
                        2, 
                        1, 
                        1
                    ], 
                    "part": [
                        "256K", 
                        "2M", 
                        "3M", 
                        "4M", 
                        "8M"
                    ], 
                    "name": "msg.file.Picture"
                }, 
                {
                    "count": [
                        2, 
                        1, 
                        1
                    ], 
                    "part": [
                        "128K", 
                        "48M", 
                        "128M"
                    ], 
                    "name": "msg.file.File"
                }
            ], 
            "last": true
        }
    }
]

typing

Typetyping
SinceR4
Primary keyuserUri, chatId
ActionsrequestListAll, requestListElements
EventslistAdd, listAll, listChange, listElements, listRemove

This is used to store the set of users that are currently typing a message in a chat. When bbmcore believes the remote user to be typing a message in a chat, it will insert the user/chat pair into this list. When it no longer believes the user to be typing a message, it removes the pair from the list. The same user may be typing in multiple chats, and the same chat may contain multiple typing users. This list never contains entries for the local user. This list may contain entries for nonexistent users and chats.

Attributes:
NameTypeRequiredSinceLoggableDescription
chatIdchat keyRequiredR4YesHolds the id of the chat in which the user is typing.
messageIdchatMessage keyOptionalR6YesIf supplied, this is the id of the 'chatMessage' the user is taking the action against as indicated by the 'tag' field. This field is never present without the 'tag' field. If the message identified by this field isn't known to the local endpoint when the typing notification arrives, the notification (including 'tag') will still be added to this list, but the 'messageId' field will be omitted.
tagstringOptionalR6YesYour application-specified tag that indicates what kind of typing action the user is performing. For example, this may be used to indicate that the user is taking a picture to send, recording a voice note, or editing an existing message. When omitted, your application must assume the user is typing a message.
userUriuser keyRequiredR4YesHolds the unique identifier of the user that is currently typing.
Examples:
[
    {
        "listAdd": {
            "elements": [
                {
                    "userUri": "bbmpim://user/id/1", 
                    "chatId": "239789432"
                }, 
                {
                    "tag": "VoiceNote", 
                    "userUri": "bbmpim://user/id/5", 
                    "chatId": "17"
                }, 
                {
                    "tag": "Edit", 
                    "messageId": "90", 
                    "userUri": "bbmpim://user/id/5", 
                    "chatId": "17"
                }
            ], 
            "type": "typing"
        }
    }, 
    {
        "listAll": {
            "type": "typing"
        }
    }, 
    {
        "listChunk": {
            "type": "typing", 
            "elements": [
                {
                    "userUri": "bbmpim://user/id/1", 
                    "chatId": "239789432"
                }, 
                {
                    "tag": "VoiceNote", 
                    "userUri": "bbmpim://user/id/5", 
                    "chatId": "17"
                }, 
                {
                    "tag": "Edit", 
                    "messageId": "90", 
                    "userUri": "bbmpim://user/id/5", 
                    "chatId": "17"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listRemove": {
            "elements": [
                {
                    "userUri": "bbmpim://user/id/1", 
                    "chatId": "239789432"
                }, 
                {
                    "userUri": "bbmpim://user/id/5", 
                    "chatId": "17"
                }, 
                {
                    "userUri": "bbmpim://user/id/5", 
                    "chatId": "17"
                }
            ], 
            "type": "typing"
        }
    }, 
    {
        "listElements": {
            "type": "typing"
        }
    }, 
    {
        "listChunk": {
            "type": "typing", 
            "elements": [
                {
                    "userUri": "bbmpim://user/id/1", 
                    "chatId": "239789432"
                }, 
                {
                    "tag": "VoiceNote", 
                    "userUri": "bbmpim://user/id/5", 
                    "chatId": "17"
                }, 
                {
                    "tag": "Edit", 
                    "messageId": "90", 
                    "userUri": "bbmpim://user/id/5", 
                    "chatId": "17"
                }
            ], 
            "last": true
        }
    }
]

user

Typeuser
Since2.0
Primary keyuri
ActionsrequestListChange, requestListElements, requestListMatching
EventslistAdd, listChange, listElements, listRemove

This list consists of all the users known to bbmcore. Other lists, such as the 'participant' list, often refer to entries in this 'user' list. Your application never requests the list in full. Instead, it uses 'requestListElements' calls to lookup one or more users by their 'uri'.

Attributes:
NameTypeRequiredSinceLoggableDescription
keyStatestringOptional (Default=Synced)R3YesThe current state of the user's keys. A new protected user is created in the 'Import' state.

This field is an enumeration.

MemberDescription
Import The user's keys need to be retrieved from external storage and imported into bbmcore. When using Cloud Key Storage, your application must perform this import using 'userKeysImport'. When using the BlackBerry Key Management Service (KMS), bbmcore will do this automatically.
Synced The user's keys are synced.
pinstringOptionalR4NoHolds the user's PIN as an 8-character lowercase hexadecimal string. This field will be omitted when the user has no PIN.
regIdstring (signed 64-bit int in base 10)Optional2014.10NoHolds the unique identifier for the user. This identifier is exposed to partner applications. If this field is not present, it indicates that the user does not have a regId or that the regId is unknown.
uristringRequired2.1YesHolds the unique identifier for the user. See the URIs section for information on the URI format.
Action Details:
MessagerequestListMatching
Description

Use requestListMatching to lookup subsets of this list.

Criteria
NameTypeSinceDescription
regIdstring (signed 64-bit int in base 10)2014.10Match a single user by regId. This is mutually exclusive with all other criteria. Returns an empty list if no match is found, any other criteria are specified, or any errors are encountered.
pinstringR3Match a single user by PIN. This is mutually exclusive with all other criteria. Returns an empty list if no match is found, any other criteria are specified, or any errors are encountered.
keyStatestringR3Match all users with the given 'keyState'. The local user is not returned. Its 'keyState' can be queried via the 'profileKeysState' global. This is mutually exclusive with all other criteria. Returns an empty list if no match is found, any other criteria are specified, or any errors are encountered.
Examples:
[
    {
        "listAdd": {
            "elements": [
                {
                    "category": "Colleagues", 
                    "maxVcardSize": 15, 
                    "displayName": "J. Binks", 
                    "isContact": true, 
                    "avatarHash": "450235345", 
                    "uri": "bbmpim://dbid/93", 
                    "personalMessage": "Busy writing scripts", 
                    "flags": "EPR", 
                    "keyState": "Import", 
                    "personalMessageTimestamp": "98739872", 
                    "nickname": "J. Binks"
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 194, 
                    "displayName": "G. Smith", 
                    "isContact": false, 
                    "avatarHash": "150235345", 
                    "uri": "bbmpim://dbid/33", 
                    "personalMessage": "Destroy him, my robots.", 
                    "flags": "PQS", 
                    "keyState": "Synced", 
                    "personalMessageTimestamp": "28739872", 
                    "nickname": "G. Smith"
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 0, 
                    "displayName": "H. Solo", 
                    "isContact": true, 
                    "avatarHash": "34234321", 
                    "uri": "bbmpim://dbid/100", 
                    "personalMessage": "I shot first", 
                    "flags": "ER", 
                    "keyState": "Synced", 
                    "personalMessageTimestamp": "2987392", 
                    "nickname": "H. Solo"
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 0, 
                    "displayName": "John Smith", 
                    "isContact": false, 
                    "avatarHash": "235345", 
                    "uri": "bbmpim://dbid/400", 
                    "personalMessage": "Boom goes the dynamite", 
                    "flags": "EPQ", 
                    "keyState": "Synced", 
                    "personalMessageTimestamp": "3434344", 
                    "nickname": "John from work"
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 0, 
                    "displayName": "John Traveller", 
                    "isContact": true, 
                    "uri": "bbmpim://dbid/500", 
                    "avatarHash": "650235345", 
                    "keyState": "Synced", 
                    "personalMessage": "", 
                    "lastConnectedTime": "1432580033", 
                    "flags": "EFPRZ", 
                    "regId": "123456789012", 
                    "nickname": "Johnny"
                }, 
                {
                    "category": "Rebels", 
                    "maxVcardSize": 0, 
                    "displayName": "David", 
                    "isContact": false, 
                    "pin": "ca224cbb", 
                    "uri": "bbmpim://dbid/99", 
                    "avatarHash": "9024296666", 
                    "keyState": "Synced", 
                    "personalMessage": "", 
                    "flags": "EFPR", 
                    "regId": "19024296666", 
                    "org": {
                        "lastName": "Jones", 
                        "readOnly": true, 
                        "id": "a1taxi", 
                        "firstName": "David"
                    }, 
                    "nickname": ""
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 0, 
                    "displayName": "JC", 
                    "isContact": false, 
                    "pin": "ffff1111", 
                    "uri": "bbmpim://dbid/99", 
                    "avatarHash": "9024296666", 
                    "keyState": "Synced", 
                    "personalMessage": "", 
                    "flags": "EFPR", 
                    "regId": "1902429777", 
                    "org": {
                        "firstName": "John", 
                        "title": "CEO", 
                        "lastName": "Chen", 
                        "readOnly": false, 
                        "department": "Executives", 
                        "id": "blackberry"
                    }, 
                    "nickname": ""
                }
            ], 
            "type": "user"
        }
    }, 
    {
        "listRemove": {
            "elements": [
                {
                    "uri": "bbmpim://dbid/93"
                }, 
                {
                    "uri": "bbmpim://dbid/33"
                }, 
                {
                    "uri": "bbmpim://dbid/100"
                }, 
                {
                    "uri": "bbmpim://dbid/400"
                }, 
                {
                    "uri": "bbmpim://dbid/500"
                }, 
                {
                    "uri": "bbmpim://dbid/99"
                }, 
                {
                    "uri": "bbmpim://dbid/99"
                }
            ], 
            "type": "user"
        }
    }, 
    {
        "listElements": {
            "type": "user"
        }
    }, 
    {
        "listChunk": {
            "type": "user", 
            "elements": [
                {
                    "category": "Colleagues", 
                    "maxVcardSize": 15, 
                    "displayName": "J. Binks", 
                    "isContact": true, 
                    "avatarHash": "450235345", 
                    "uri": "bbmpim://dbid/93", 
                    "personalMessage": "Busy writing scripts", 
                    "flags": "EPR", 
                    "keyState": "Import", 
                    "personalMessageTimestamp": "98739872", 
                    "nickname": "J. Binks"
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 194, 
                    "displayName": "G. Smith", 
                    "isContact": false, 
                    "avatarHash": "150235345", 
                    "uri": "bbmpim://dbid/33", 
                    "personalMessage": "Destroy him, my robots.", 
                    "flags": "PQS", 
                    "keyState": "Synced", 
                    "personalMessageTimestamp": "28739872", 
                    "nickname": "G. Smith"
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 0, 
                    "displayName": "H. Solo", 
                    "isContact": true, 
                    "avatarHash": "34234321", 
                    "uri": "bbmpim://dbid/100", 
                    "personalMessage": "I shot first", 
                    "flags": "ER", 
                    "keyState": "Synced", 
                    "personalMessageTimestamp": "2987392", 
                    "nickname": "H. Solo"
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 0, 
                    "displayName": "John Smith", 
                    "isContact": false, 
                    "avatarHash": "235345", 
                    "uri": "bbmpim://dbid/400", 
                    "personalMessage": "Boom goes the dynamite", 
                    "flags": "EPQ", 
                    "keyState": "Synced", 
                    "personalMessageTimestamp": "3434344", 
                    "nickname": "John from work"
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 0, 
                    "displayName": "John Traveller", 
                    "isContact": true, 
                    "uri": "bbmpim://dbid/500", 
                    "avatarHash": "650235345", 
                    "keyState": "Synced", 
                    "personalMessage": "", 
                    "lastConnectedTime": "1432580033", 
                    "flags": "EFPRZ", 
                    "regId": "123456789012", 
                    "nickname": "Johnny"
                }, 
                {
                    "category": "Rebels", 
                    "maxVcardSize": 0, 
                    "displayName": "David", 
                    "isContact": false, 
                    "pin": "ca224cbb", 
                    "uri": "bbmpim://dbid/99", 
                    "avatarHash": "9024296666", 
                    "keyState": "Synced", 
                    "personalMessage": "", 
                    "flags": "EFPR", 
                    "regId": "19024296666", 
                    "org": {
                        "lastName": "Jones", 
                        "readOnly": true, 
                        "id": "a1taxi", 
                        "firstName": "David"
                    }, 
                    "nickname": ""
                }, 
                {
                    "category": "", 
                    "maxVcardSize": 0, 
                    "displayName": "JC", 
                    "isContact": false, 
                    "pin": "ffff1111", 
                    "uri": "bbmpim://dbid/99", 
                    "avatarHash": "9024296666", 
                    "keyState": "Synced", 
                    "personalMessage": "", 
                    "flags": "EFPR", 
                    "regId": "1902429777", 
                    "org": {
                        "firstName": "John", 
                        "title": "CEO", 
                        "lastName": "Chen", 
                        "readOnly": false, 
                        "department": "Executives", 
                        "id": "blackberry"
                    }, 
                    "nickname": ""
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "nickname": "J. Binks", 
                    "uri": "bbmpim://dbid/93"
                }, 
                {
                    "nickname": "G. Smith", 
                    "uri": "bbmpim://dbid/33"
                }, 
                {
                    "nickname": "H. Solo", 
                    "uri": "bbmpim://dbid/100"
                }, 
                {
                    "nickname": "John from work", 
                    "uri": "bbmpim://dbid/400"
                }, 
                {
                    "nickname": "Johnny", 
                    "uri": "bbmpim://dbid/500"
                }, 
                {
                    "nickname": "", 
                    "uri": "bbmpim://dbid/99"
                }, 
                {
                    "nickname": "", 
                    "uri": "bbmpim://dbid/99"
                }
            ], 
            "type": "user"
        }
    }
]

All Globals

authTokenState

NameauthTokenState
Since2016.03

This global indicates if bbmcore requires an authToken value from your application, using the 'authToken' message. The authToken value is used by identity providers to grant further authorization within the BlackBerry Infrastructure.

Bbmcore will try to avoid requesting authToken values as much as possible.

Your application may rely on bbmcore to rate limit how often this global value is something other than 'Ok'. Your application should react automatically when this global's value changes.

Attributes:
TypeRequiredSinceLoggableDescription
stringRequired2016.03YesThe current state of the authToken value in bbmcore.

This field is an enumeration.

MemberDescription
Needed

bbmcore doesn't currently have a usable authToken value. To continue any communication with the BlackBerry Infrastructure, your application must provide an authToken using the 'authToken' message. If the 'authTokenState' is 'Needed', setup can't proceed.

The first time setup is initiated by the 'authToken' message, the 'authTokenState' will be 'Needed'. However, there are a number of other conditions that can cause the state to change to 'Needed', such as a failed setup attempt, or an internal refresh of authentication.

Ok Bbmcore has a usable authToken value, and it doesn't require another value from your application. If your application has a reason to supply an updated authToken value, it can be updated without solicitation.
Rejected bbmcore attempted to use a previously-supplied authToken value, but the value (or its derivative products) was rejected during authentication or authorization. In this state, your application must provide an authToken using the 'authToken' message. However, your application is encouraged to re-assert the user's identity before providing an updated authToken value, and the user might need to be prompted to log in again, or your application might need to clear cached credentials.
Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "authTokenState", 
                    "value": "Needed"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "authTokenState", 
                    "value": "Needed"
                }
            ], 
            "type": "global"
        }
    }, 
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "authTokenState", 
                    "value": "Ok"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "authTokenState", 
                    "value": "Ok"
                }
            ], 
            "type": "global"
        }
    }
]

chatMessageFileAutoDownload

NamechatMessageFileAutoDownload
SinceR5

This controls whether bbmcore will automatically download newly received file attachments.

Regardless of this setting, your application can ask for individual attachments to be downloaded using the 'chatMessageFileDownload' request.

Attributes:
TypeRequiredSinceLoggableDescription
booleanRequiredR5Yes

When true (the default), bbmcore will download any 'chatMessage' file attachments as soon as it receives a message with an attachment in a 'Ready' chat. (Messages downloaded as part of chat restoration or joining a chat are never automatically downloaded even when 'chatMessageFileAutoDownload' is set to true. Such file attachments remain in the 'Available' state.)

When false, bbmcore will not automatically download any 'chatMessage' file attachments. Available file attachments will remain in the 'Available' state.

Action Details:
MessagerequestListChange
SinceR5
Attributesvalue

Your application can change the 'chatMessageFileAutoDownload' setting with 'requestListChange' on the 'global' list.

Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "chatMessageFileAutoDownload", 
                    "value": true
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "chatMessageFileAutoDownload", 
                    "value": true
                }
            ], 
            "type": "global"
        }
    }
]

endpointId

NameendpointId
SinceR5

The identifier for this endpoint. This must be treated as an opaque value by application.

Attributes:
TypeRequiredSinceLoggableDescription
stringRequiredR5No
Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "endpointId", 
                    "value": "asd4fgdffssf3987bb0a"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "endpointId", 
                    "value": "asd4fgdffssf3987bb0a"
                }
            ], 
            "type": "global"
        }
    }
]

localPin

NamelocalPin
Since2.1

Associates the PIN that is assigned by the BlackBerry Infrastructure with the local profile. The PIN is an 8-character hexadecimal string (in lower case), or it is an empty string if no PIN is currently assigned to the local profile.

Attributes:
TypeRequiredSinceLoggableDescription
stringRequired2.1No
Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "localPin", 
                    "value": "3987bb0a"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "localPin", 
                    "value": "3987bb0a"
                }
            ], 
            "type": "global"
        }
    }, 
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "localPin", 
                    "value": ""
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "localPin", 
                    "value": ""
                }
            ], 
            "type": "global"
        }
    }
]

localUri

NamelocalUri
Since2.2

This holds the local user's URI as a foreign key into 'listUser'. When a user URI appears elsewhere in the protocol, your application compares the user URI to the 'localUri' value, to determine if the URI refers to the local user.

Attributes:
TypeRequiredSinceLoggableDescription
user keyRequired2.2No
Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "localUri", 
                    "value": "bbmpim://user/id/0"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "localUri", 
                    "value": "bbmpim://user/id/0"
                }
            ], 
            "type": "global"
        }
    }
]

profileKeysState

NameprofileKeysState
SinceR3

Indicates the current state of the profile's signing and encryption key pairs.

This state only applies when your application uses Cloud Key Storage without the BlackBerry Key Management Service.

Attributes:
TypeRequiredSinceLoggableDescription
stringRequiredR3YesThe current state of the profile's keys. A new profile is created in the 'NotSynced' state.

This field is an enumeration.

MemberDescription
NotSynced The profile's keys are not synced. The profile's keys need to be either imported into bbmcore via 'profileKeysImport', or exported from bbmcore via 'profileKeysExport' and put into external storage.
Synced The profile's keys are synced.
Action Details:
MessagerequestListChange
SinceR3
Attributesvalue

requestListChange can be used to set the state to 'Synced'.

Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "profileKeysState", 
                    "value": "Synced"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "profileKeysState", 
                    "value": "Synced"
                }
            ], 
            "type": "global"
        }
    }, 
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "profileKeysState", 
                    "value": "NotSynced"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "profileKeysState", 
                    "value": "NotSynced"
                }
            ], 
            "type": "global"
        }
    }
]

registrationToken

NameregistrationToken
SinceR5

In R5, endpoints are given this registration token when they are assigned a regId during setup. This token is signed by the BlackBerry Infrastructure. When decoded, the token contains trusted information about the association of your application user id (as passed to 'authToken') with the assigned regId. The steps for decoding and verifying the registration token are explained in detail in the Developer Guide.

Endpoints that have not yet been assigned a regId and endpoints that were assigned a regId before the R5 release do not have a registration token value. In those endpoints, this global will be the empty string.

Attributes:
TypeRequiredSinceLoggableDescription
stringRequiredR5NoThe registration token given to this endpoint during setup, or the empty string. See above.
Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "registrationToken", 
                    "value": "50yjSGScACkfrdPE3CHibuopdF7yQWulFafTepbtOCcALhslpwudzZ7X3cMfwUP9Q8aT52GkwXJ2yqEbSLpkJepHbqwrNOVrirlzoChDXk40mEP6kxqi9uw7uY13UkFz"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "registrationToken", 
                    "value": "50yjSGScACkfrdPE3CHibuopdF7yQWulFafTepbtOCcALhslpwudzZ7X3cMfwUP9Q8aT52GkwXJ2yqEbSLpkJepHbqwrNOVrirlzoChDXk40mEP6kxqi9uw7uY13UkFz"
                }
            ], 
            "type": "global"
        }
    }
]

setupAccount

NamesetupAccount
Since2015.04

Indicates if a new or existing Spark Communications identity was used during the most recent setup attempt. Note: the value of this global changes before setup is complete. To see what kind of identity was used for the most recent setup attempt that was successful, check this 'setupAccount' value when 'setupState' transitions to 'Success'.

Attributes:
TypeRequiredSinceLoggableDescription
stringRequired2015.04YesIndicates what kind of identity was used for the most recent attempt to set up Spark Communications Services.

This field is an enumeration.

MemberDescription
Existing An existing Spark Communications identity was used during the most recent attempt to set up.
New A new Spark Communications identity was used during the most recent attempt to set up.
None No attempt has been made to set up Spark Communications Services.
Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "setupAccount", 
                    "value": "None"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "setupAccount", 
                    "value": "None"
                }
            ], 
            "type": "global"
        }
    }, 
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "setupAccount", 
                    "value": "New"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "setupAccount", 
                    "value": "New"
                }
            ], 
            "type": "global"
        }
    }, 
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "setupAccount", 
                    "value": "Existing"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "setupAccount", 
                    "value": "Existing"
                }
            ], 
            "type": "global"
        }
    }
]

setupState

NamesetupState
Since2.1

This indicates the state of the setup process.

Endpoint setup includes registering the endpoint with the BlackBerry Infrastructure and synchronizing the endpoint's copy of identity data, including any security keys.

The following diagram demonstrates the flow of state changes in 'setupState' for all modes of setup:

Attributes:
NameTypeRequiredSinceLoggableDescription
progressMessagestringOptional2.1YesWhen the 'state' is 'Ongoing', this indicates the current phase of setup. When the 'state' is not 'Ongoing', this field is omitted or set to 'Unknown'.

This field is an enumeration.

MemberDescription
Completing Setup is completing with a new registration.
Restoring The user's Spark Communications identity information is being restored from the BlackBerry Infrastructure.
Transferring The user's Spark Communications identity information is being transferred.
Unknown The current state of the progress is unknown or not applicable.
statestringRequired2.1Yes

This indicates the current setup state.

The initial 'authToken' request triggers bbmcore to begin setup. However, 'authTokenState' transitions don't change the setup state. For example, the 'authTokenState' transitions to 'Rejected' or 'Needed', setup doesn't fail (but it might not succeed until a usable 'authToken' is provided). The 'authTokenState' and the 'setupState' are independent, but 'authToken' can trigger a setup attempt when 'setupState' is set to 'NotRequested'.

The only way to stop setup after it starts is by sending the 'wipe' command to delete all bbmcore data.

When certain minor errors occur during setup, bbmcore automatically retries the setup by using the 'retryServerRequests' message. These minor errors are handled by bbmcore, and they don't result in 'state' changes.

This field is an enumeration.

MemberDescription
DeviceSwitchRequired A device switch is required for setup to proceed. bbmcore is waiting for 'setupRetry' as a confirmation from your application. Once the confirmation is received, the 'state' will return to 'Ongoing'.
Full At least one other endpoint must be removed before setup may proceed. Endpoints may be removed using 'endpointDeregister'. After removing some endpoints, setup may be retried using 'setupRetry'. Once a retry is started, the 'state' will return to 'Ongoing'.
NotRequested Endpoint setup hasn't started. In this state, bbmcore is waiting for 'authToken' before proceeding (see that message for more details).
Ongoing Indicates that bbmcore is performing actions that will cause a state change. The current progress message is obtained from the 'progressMessage' attribute.
Success Indicates setup was successful.
SyncRequired

This endpoint must be synchronized before setup can proceed. bbmcore is waiting for 'syncStart' to start the sync. Once the sync is started, the 'state' will move to 'SyncStarted'.

This occurs only when your application uses the BlackBerry Key Management Service (KMS). In such applications, all endpoints must synchronize with KMS during setup. In this state, bbmcore either needs the passcode for existing sync data, or it needs a new passcode to create new sync data.

The 'syncStart' documentation explains how to provide bbmcore with the information necessary to proceed from this state.

SyncStarted

The endpoint sync has been started.

This occurs only when your application uses the BlackBerry Key Management Service (KMS).

Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "setupState", 
                    "value": {
                        "state": "Success"
                    }
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "setupState", 
                    "value": {
                        "state": "Success"
                    }
                }
            ], 
            "type": "global"
        }
    }, 
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "setupState", 
                    "value": {
                        "progressMessage": "Transferring", 
                        "state": "Ongoing"
                    }
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "setupState", 
                    "value": {
                        "progressMessage": "Transferring", 
                        "state": "Ongoing"
                    }
                }
            ], 
            "type": "global"
        }
    }
]

syncPasscodeState

NamesyncPasscodeState
SinceR6

This state is only used when your application uses the BlackBerry Key Management Service and the 'setupState' is 'SyncRequired'.

When your application sees 'setupState' change to 'SyncRequired', it should examine this global.

  1. When 'syncPasscodeState' is 'None', your application should wait for 'syncPasscodeState' to change before sending 'syncStart'.
  2. When 'syncPasscodeState' is not 'None', its value is already current and your application does not have to wait.

See 'syncStart' for more information.

Attributes:
TypeRequiredSinceLoggableDescription
stringRequiredR6YesThis state tells your application whether bbmcore requires a passcode during the endpoint sync phase of setup.

This field is an enumeration.

MemberDescription
Existing Existing sync data was found and is protected by a passcode. Your application must provide the existing passcode to bbmcore once the 'setupState' is 'state' 'SyncRequired' by sending 'syncStart' with 'action' set to 'Existing'. See that message for more information.
New No usable existing sync data was found. Your application must provide a new passcode to bbmcore once the 'setupState' is 'state' 'SyncRequired' by sending 'syncStart' with 'action' set to 'New'. See that message for more information.
None No sync passcode is required by bbmcore.
Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "syncPasscodeState", 
                    "value": "None"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "syncPasscodeState", 
                    "value": "None"
                }
            ], 
            "type": "global"
        }
    }, 
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "syncPasscodeState", 
                    "value": "New"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "syncPasscodeState", 
                    "value": "New"
                }
            ], 
            "type": "global"
        }
    }, 
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "syncPasscodeState", 
                    "value": "Existing"
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "syncPasscodeState", 
                    "value": "Existing"
                }
            ], 
            "type": "global"
        }
    }
]

syncing

Namesyncing
SinceR7

This global boolean indicates when bbmcore is performing reconnect synchronization with the BlackBerry Infrastructure. On mobile OSes and within other environments that are aggressive about terminating or suspending applications, your application should take steps to keep bbmcore running while this global is true.

For example, consider an Android application that receives push notifications when there are protocol messages waiting for bbmcore to fetch from the BlackBerry Infrastructure. Your application could use this global as part of the following strategy.

  1. When your application receives the push, it raises a "connected" foreground notification (if one is not already raised) that will keep your application running.
  2. When that notification is raised, your application starts a short timer. This timer will give bbmcore time to connect to the BlackBerry Infrastructure, which will happen before this global is raised. If this timer expires, your application "gives up" on waiting for the global to change, and removes the foreground notification.
  3. Your application then forwards that push notification to the lower layers which will react by connecting to the BlackBerry Infrastructure.
  4. Once bbmcore has successfully connected, it changes the 'syncing' global to 'true'. In response, your application raises the notification if it isn't already raised. Your application also sets or extends the notification timer for a longer duration. Again, if that timer expires, your application removes the notification.
  5. When the syncing process completes, bbmcore changes the 'syncing' global back to 'false'. In response, if the notification is still raised, your application removes it and cancels the timer.

In extreme circumstances, the 'syncing' global can remain true for a long time as bbmcore attempts to recover from unusual failure cases. The timers described above give your application control over the maximum duration it is willing to keep the notification raised.

Attributes:
TypeRequiredSinceLoggableDescription
booleanRequiredR7No
Examples:
[
    {
        "listElements": {
            "type": "global"
        }
    }, 
    {
        "listChunk": {
            "type": "global", 
            "elements": [
                {
                    "name": "syncing", 
                    "value": true
                }
            ], 
            "last": true
        }
    }, 
    {
        "listChange": {
            "elements": [
                {
                    "name": "syncing", 
                    "value": true
                }
            ], 
            "type": "global"
        }
    }
]