Name	authToken
Since	2016.03
Direction	Outgoing

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

Name	Type	Req	Since	Log	Description
authToken	string	Req	2016.03	No	The 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.
userId	string	Req	2016.03	No	The 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.

Toggle display

[
    {
        "authToken": {
            "authToken": "WW91J3JlIHRob3JvdWdoIQ==",
            "userId": "BlackBerryUser"
        }
    },
    {
        "authToken": {
            "authToken": "    why?   ",
            "userId": "\u0000Very\nstrange\t user #id"
        }
    }
]

Name	chatEvent
Since	R7
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R7	Yes	The id of the chat in which the chat event was received.
data	object	Opt	R7	Yes	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.
flags	string	Opt	R7	Yes	Compact 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 Name Letter Since Description 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.
senderUri	user key	Req	R7	Yes	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.
tag	string	Req	R7	Yes	Your application-specified tag that indicates what kind of chat event has been received.

Toggle display

[
    {
        "chatEvent": {
            "chatId": "2824",
            "flags": "",
            "senderUri": "bbmpim://user/id/12",
            "tag": "Heartbeat"
        }
    },
    {
        "chatEvent": {
            "chatId": "7",
            "data": {
                "Location": {
                    "lat": 0,
                    "long": 0,
                    "place": "Home"
                }
            },
            "flags": "U",
            "senderUri": "bbmpim://user/id/0",
            "tag": "Location"
        }
    }
]

Name	chatEventSend
Since	R7
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R7	Yes	The id of the chat in which the chat event is to be posted.
data	object	Opt	R7	Yes	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).
tag	string	Req	R7	Yes	Your application-specified tag that indicates what kind of chat event is being sent.

Toggle display

[
    {
        "chatEventSend": {
            "chatId": "2824",
            "tag": "Heartbeat"
        }
    },
    {
        "chatEventSend": {
            "chatId": "7",
            "data": {
                "Location": {
                    "lat": 0,
                    "long": 0,
                    "place": "Home"
                }
            },
            "tag": "Location"
        }
    }
]

Name	chatHide
Since	R4
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatIds	array	Req	R4	Yes	An array of ids of the chats that are to be hidden. The following table describes the type of each array element. Type Req Since Log Description chat key Req R4 Yes The id of a chat that is to be hidden.

Toggle display

[
    {
        "chatHide": {
            "chatIds": [
                "6"
            ]
        }
    },
    {
        "chatHide": {
            "chatIds": [
                "2824",
                "12"
            ]
        }
    }
]

Name	chatInvite
Since	R3
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatId	string	Req	R3	Yes	The id of the existing chat to invite the invitees to.
invitees	array	Req	R3	Yes	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. Type Req Since Log Description object Req R3 No Each invitee may be identified by a user URI or regId. Entries without one of these identifiers will be ignored. Name Type Req Since Log Description regId number (int64) Opt R3 Yes 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. userUri user key Opt R3 Yes The URI of an existing user to invite to the chat. When present, the 'regId' is ignored.

Toggle display

[
    {
        "chatInvite": {
            "chatId": "7",
            "invitees": [
                {
                    "userUri": "bbmpim://user/id/4736"
                }
            ]
        }
    },
    {
        "chatInvite": {
            "chatId": "2347",
            "invitees": [
                {
                    "userUri": "bbmpim://user/id/4736"
                },
                {
                    "regId": 2783476
                }
            ]
        }
    },
    {
        "chatInvite": {
            "chatId": "887",
            "invitees": [
                {
                    "pin": "abcd1234",
                    "regId": 123456789
                },
                {
                    "displayName": "Sue Smith",
                    "pin": "11111111",
                    "regId": 5583673
                },
                {
                    "userUri": "bbmpim://user/id/4736"
                }
            ]
        }
    },
    {
        "chatInvite": {
            "chatId": "1",
            "invitees": []
        }
    }
]

Name	chatJoined
Since	R11
Direction	Incoming

This message is sent to your application by bbmcore when this endpoint finishes joining a chat started by another identity.

The chat is already in the 'chat' list (so any 'listAdd' for the chat has already been sent), but when the chat was added to that list, it was not yet in 'state' 'Ready'. When 'chatJoined' is sent, the chat has moved to 'state' 'Ready' and your application will start to receive 'listAdd' events for 'chatMessage' elements as messages arrive in the chat. Note that no 'listAdd' event occurs for a 'chatMessage' restored or received while a chat is in 'state' 'Restore'.

No 'chatJoined' message is sent for chats that the local user created themselves on this or another endpoint or when a chat is discovered during reconciliation, including initial reconciliation after setting up a new endpoint.

As an example of how to react to this event, your application could raise a user notification for each recently received unread 'chatMessage' in a joined one-to-one chat. Or, your application could raise a user notification that advertises the existence of a newly joined chat in general.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R11	Yes	The id of the chat that this endpoint has finished joining.

Toggle display

[
    {
        "chatJoined": {
            "chatId": "2824"
        }
    }
]

Name	chatKey
Since	R3
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
cookie	string	Req	R3	Yes	The cookie used to track this response to its 'chatKeyExport' request.
key	string	Req	R3	No	The unpadded base64url-encoded chat key.
mailboxId	string	Req	R3	Yes	The mailboxId of the chat key for use in external storage.

Toggle display

[
    {
        "chatKey": {
            "cookie": "823gudb3d2qwe",
            "key": "Y2hhdEtleTEyMw",
            "mailboxId": "123"
        }
    }
]

Name	chatKeyExport
Since	R3
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R3	Yes	The id of the chat to get the key for.
cookie	string	Req	R3	Yes	The cookie used to track this request to a 'chatKey' response.

Toggle display

[
    {
        "chatKeyExport": {
            "chatId": "123",
            "cookie": "823gudb3d2qwe"
        }
    }
]

Name	chatKeysImport
Since	R3
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
keys	array	Req	R3	Yes	The list of chat keys to set. The following table describes the type of each array element. Type Req Since Log Description object Req R3 Yes The key for the chat. Name Type Req Since Log Description key string Req R3 No The unpadded base64url-encoded chat key. mailboxId string Req R3 Yes The mailboxId of the chat key for use in external storage.

Toggle display

[
    {
        "chatKeysImport": {
            "keys": [
                {
                    "key": "Y2hhdEtleW1ieDEyMw==",
                    "mailboxId": "mbx123"
                },
                {
                    "key": "Y2hhdEtleW1ieDMyMQ==",
                    "mailboxId": "mbx321"
                }
            ]
        }
    }
]

Name	chatKeysImportFailure
Since	R4
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
mailboxIds	array	Req	R4	Yes	The list of mailboxIds that failed to import. The following table describes the type of each array element. Type Req Since Log Description string Req R4 Yes The mailboxId that failed to import.

Toggle display

[
    {
        "chatKeysImportFailure": {
            "mailboxIds": [
                "mbx1",
                "mbx3"
            ]
        }
    }
]

Name	chatLeave
Since	R4
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatIds	array	Req	R4	Yes	An array of ids of the chats that are to be left. The following table describes the type of each array element. Type Req Since Log Description chat key Req R4 Yes The id of a chat that is to be left.

Toggle display

[
    {
        "chatLeave": {
            "chatIds": [
                "6"
            ]
        }
    },
    {
        "chatLeave": {
            "chatIds": [
                "2824",
                "12"
            ]
        }
    }
]

Name	chatMessageDelete
Since	R4
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R4	Yes	The identifier of the chat containing the message to be deleted.
id	string (uint64)	Req	R4	Yes	The unique identifier for the message to be deleted within the provided chat.

Toggle display

[
    {
        "chatMessageDelete": {
            "chatId": "64",
            "id": "256789"
        }
    }
]

Name	chatMessageDestroy
Since	R6
Direction	Outgoing

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

• the local endpoint,
• other endpoints of the local user's identity,
• all endpoints of all other participants of the chat, and
• the BlackBerry Infrastructure.

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R6	Yes	The id of the chat containing the message to be recalled and destroyed.
messageId	chatMessage key	Opt	R6	Yes	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.

Toggle display

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

Name	chatMessageDetach
Since	2017.02
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	2017.02	Yes	The identifier of the chat containing the 'chatMessage'.
detachFile	boolean	Opt False	2017.02	Yes	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.
detachThumb	boolean	Opt False	2017.02	Yes	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.
messageId	string (uint64)	Req	2017.02	Yes	The identifier of the 'chatMessage' within the chat identified by 'chatId'.

Toggle display

[
    {
        "chatMessageDetach": {
            "chatId": "64",
            "detachFile": false,
            "detachThumb": true,
            "messageId": "6510"
        }
    },
    {
        "chatMessageDetach": {
            "chatId": "64",
            "detachFile": true,
            "detachThumb": false,
            "messageId": "1541"
        }
    },
    {
        "chatMessageDetach": {
            "chatId": "64",
            "detachFile": true,
            "detachThumb": true,
            "messageId": "6581"
        }
    }
]

Name	chatMessageFileDownload
Since	2017.02
Direction	Outgoing

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

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	2017.02	Yes	The identifier of the chat containing the 'chatMessage'.
messageId	string (uint64)	Req	2017.02	Yes	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.

Toggle display

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

Name	chatMessageRead
Since	R4
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R4	Yes	The id of the chat containing the message referred to by 'messageId'.
messageId	chatMessage key	Req	R4	Yes	The largest 'messageId' (within the chat referred to by 'chatId') of the messages that are to be marked as read by the local user.

Toggle display

[
    {
        "chatMessageRead": {
            "chatId": "2824",
            "messageId": "786"
        }
    }
]

Name	chatMessageRefRemove
Since	R8
Direction	Outgoing

Request that bbmcore remove the 'ref' with the given 'tag' locally for a single 'chatMessage'. This message does not change the 'chatMessage' for any other endpoints or identities.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R8	Yes	The identifier of the chat containing the 'chatMessage'.
messageId	string (uint64)	Req	R8	Yes	The identifier of the 'chatMessage' within the chat identified by 'chatId'.
tag	string	Req	R8	Yes	The 'ref' 'tag' to be removed. If there is a matching 'refBy' on another 'chatMessage', it will also be updated. List updates will result for affected messages, if any.

Toggle display

[
    {
        "chatMessageRefRemove": {
            "chatId": "64",
            "messageId": "6510",
            "tag": "Edit"
        }
    }
]

Name	chatMessageSend
Since	2017.02
Direction	Outgoing

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

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	2017.02	Yes	The identifier of the chat in which to send the message.
content	string	Opt	2017.02	No	Holds the text content of the message, when the 'tag' has such a concept; otherwise omitted. The total size of the 'content' in UTF-8 is subject to a cumulative size limit when combined with the size of the 'data' object (encoded as JSON in UTF-8) and the size of the 'thumb' attachment. These three fields combined must not exceed 71680 bytes (70 KB).
data	object	Opt	2017.02	Yes	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). Name Type Req Since Log Description forwarded boolean Opt R11 Yes Iff present and true, then this message is considered a forwarded message. It can be present for any 'tag' and is independent from other fields in 'data'. A forwarded message is a message that was obtained from one chat and sent in another chat.
file	string	Opt	2017.02	No	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. Attachments from R5 or later endpoints preserve a locally-cleaned version of any suggested attachment filename that the sender provided by including it as the leaf filename of this path. Attachments that did not have a suggested filename will use an implementation-defined locally-assigned sequential or random filename.
filePolicy	string	Opt	2017.02	Yes	This enumeration tells bbmcore what to do with the file referenced by 'file'. For all other documentation, please see 'thumbPolicy'. This field is an enumeration. Member Description Copy See 'thumbPolicy'. Delete See 'thumbPolicy'. Move See 'thumbPolicy'.
isControl	boolean	Opt False	R9	Yes	Set the 'control' flag ('C') on the 'chatMessage'. See the 'chatMessage' 'flags' field for details.
neverCountUnread	boolean	Opt False	R9	Yes	Set the 'neverCountUnread' flag ('N') on the 'chatMessage'. See the 'chatMessage' 'flags' field for details.
ref	array	Opt	R5	Yes	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. Type Req Since Log Description object Req R5 Yes Each element of the 'ref' array represents a single reference to another 'chatMessage'. Name Type Req Since Log Description messageId chatMessage key Req R5 Yes The 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. tag string Req R5 Yes Your 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. Member Description Edit This message edits the referenced message. If you allow edits from the original sender only, your application should not send a message with an 'Edit' ref to another sender's message and must also check received references as described in the documentation of the 'Edit' tag for 'chatMessage' 'ref' and 'refBy'. An 'Edit' can not itself be edited. Instead, send a new message with an 'Edit' 'ref' to the original message that is to be edited. Quote This message quotes the referenced message. Thread This message belongs to a thread that has the referenced message as its parent.
tag	string	Req	2017.02	Yes	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. Member Description Text The message contains plain text content. This tag requires 'content'
thumb	string	Opt	2017.02	No	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). Attachments from R5 or later endpoints preserve a locally-cleaned version of any suggested attachment filename that the sender provided by including it as the leaf filename of this path. Attachments that did not have a suggested filename will use an implementation-defined locally-assigned sequential or random filename.
thumbPolicy	string	Opt	2017.02	Yes	This 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. Member Description 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).

Toggle display

[
    {
        "chatMessageSend": {
            "chatId": "436",
            "content": "Hello, folks. This is a test.",
            "isControl": false,
            "neverCountUnread": false,
            "tag": "Text"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "436",
            "content": "Cats are funny!",
            "data": {
                "File": {
                    "contentType": "suggestedFilename",
                    "suggestedFilename": "funny_cat.jpg"
                },
                "priority": "None"
            },
            "file": "/picture/funny_cat.jpg",
            "filePolicy": "Delete",
            "isControl": false,
            "neverCountUnread": false,
            "tag": "File",
            "thumb": "/picture/funny_cat_small.jpg",
            "thumbPolicy": "Delete"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "3",
            "content": "Follow me on Glympse: www.glympse.com",
            "data": {
                "Glympse": {
                    "id": "123234232"
                },
                "priority": "None"
            },
            "isControl": false,
            "neverCountUnread": false,
            "tag": "Glympse"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "4",
            "content": "Follow me on Glympse: www.glympse.com",
            "data": {
                "GlympseRequest": {
                    "duration": 300
                },
                "priority": "None"
            },
            "isControl": false,
            "neverCountUnread": false,
            "tag": "GlympseRequest"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "5",
            "content": "The answer is 2.",
            "data": {
                "Quote": {
                    "source": "John Doe",
                    "text": "What is 1+1?",
                    "timestamp": 562737600
                },
                "priority": "None"
            },
            "isControl": false,
            "neverCountUnread": false,
            "tag": "Quote"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "6",
            "content": "Me too!",
            "data": {
                "ReferencedUpdate": {
                    "type": "PersonalMessage",
                    "update": "Looking forward to this weekend."
                },
                "priority": "None"
            },
            "isControl": false,
            "neverCountUnread": false,
            "tag": "ReferencedUpdate"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "7",
            "isControl": false,
            "neverCountUnread": false,
            "tag": "Screencap"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "8",
            "content": "Important Message",
            "data": {
                "priority": "High"
            },
            "isControl": false,
            "neverCountUnread": false,
            "ref": [
                {
                    "messageId": "634",
                    "tag": "Quote"
                },
                {
                    "messageId": "6",
                    "tag": "Thread"
                }
            ],
            "tag": "Text"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "9",
            "content": "My Location",
            "data": {
                "Location": {
                    "altitude": "3",
                    "city": "Halifax",
                    "country": "Canada",
                    "horizontalAccuracy": "90",
                    "latitude": "44.64692",
                    "longitude": "-63.57822",
                    "name": "Halifax, NS, Canada",
                    "postalCode": "",
                    "state": "NS",
                    "street": ""
                },
                "priority": "None"
            },
            "isControl": false,
            "neverCountUnread": false,
            "tag": "Location"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "1000",
            "content": "Let's discuss this with the others.",
            "data": {
                "MediaConf": {
                    "requireAuth": true,
                    "url": "https://conf.bbm.bbmenterprise.com/join?appId=example"
                },
                "priority": "None"
            },
            "isControl": false,
            "neverCountUnread": false,
            "tag": "MediaConf"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "10",
            "data": {
                "Call": {
                    "callType": "Video",
                    "duration": 326,
                    "eventType": "Ended"
                },
                "priority": "None"
            },
            "isControl": false,
            "neverCountUnread": false,
            "tag": "Call"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "11",
            "content": "https://www.blackberry.com/us/en/products/blackberry-spark-platform",
            "data": {
                "Link": {
                    "descr": "BlackBerry Spark is the only Enterprise of Things (EoT) platform designed and built for ultra-secure hyperconnectivity from the kernel to the edge.",
                    "image": "https://rimblogs.files.wordpress.com/2017/06/business-man-secure.png",
                    "name": "BlackBerry Spark",
                    "title": "BlackBerry Spark: The EoT Platform for Ultra-secure Hyperconnectivity",
                    "url": "https://www.blackberry.com/us/en/products/blackberry-spark-platform"
                },
                "priority": "None"
            },
            "isControl": false,
            "neverCountUnread": false,
            "tag": "Link"
        }
    },
    {
        "chatMessageSend": {
            "chatId": "11",
            "content": "@John Doe, can you please respond to the request from @Jane Doe.",
            "data": {
                "mentions": {
                    "users": [
                        {
                            "len": 9,
                            "pos": 0,
                            "regId": "1602329767"
                        },
                        {
                            "len": 9,
                            "pos": 55,
                            "regId": "1404567733"
                        }
                    ]
                },
                "priority": "None"
            },
            "isControl": false,
            "neverCountUnread": false,
            "tag": "Text"
        }
    }
]

Name	chatMessageState
Since	R4
Direction	Incoming

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

Name	Type	Req	Since	Log	Description
cookie	string	Opt	R4	Yes	An opaque value that is echoed back to your application if it was specified in the request.
states	array	Req	R4	Yes	The 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. Type Req Since Log Description object Opt R4 No The individual delivery state for the message for a single recipient. Name Type Req Since Log Description state string Req R4 Yes The delivery state of the message for the individual recipient. This field is an enumeration. Member Description Delivered The message has been delivered. Read The message has been read. userUri string Req R4 Yes The URI of the recipient.

Toggle display

[
    {
        "chatMessageState": {
            "cookie": "asdgjh2095hga984598hg",
            "states": []
        }
    },
    {
        "chatMessageState": {
            "cookie": "asdgjh2095hga984598hg",
            "states": [
                {
                    "state": "Read",
                    "userUri": "bbmpim://user/id/23576"
                }
            ]
        }
    },
    {
        "chatMessageState": {
            "states": [
                {
                    "state": "Delivered",
                    "userUri": "bbmpim://user/id/5"
                },
                {
                    "state": "Read",
                    "userUri": "bbmpim://user/id/6"
                }
            ]
        }
    }
]

Name	chatMessageStateGet
Since	R4
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R4	Yes	The id of the chat containing the message referred to by 'messageId'.
cookie	string	Opt	R4	Yes	An opaque value supplied by your application that will be echoed back in the response.
messageId	chatMessage key	Req	R4	Yes	The id of the message (within the chat referred to by 'chatId') for which information is to be returned.

Toggle display

[
    {
        "chatMessageStateGet": {
            "chatId": "12",
            "messageId": "256789"
        }
    },
    {
        "chatMessageStateGet": {
            "chatId": "234754",
            "cookie": "slggjq3240987g0987",
            "messageId": "8"
        }
    }
]

Name	chatParticipantTimes
Since	R5
Direction	Incoming

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

Name	Type	Req	Since	Log	Description
cookie	string	Opt	R5	Yes	An opaque value that is echoed back to your application if it was specified in the request.
times	array	Req	R5	Yes	The 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. Type Req Since Log Description object Opt R5 No The individual delivery times for a single participant. Name Type Req Since Log Description delivered number (uint64) Opt R5 Yes The 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. read number (uint64) Opt R5 Yes The 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. userUri string Req R5 Yes The URI of the participant.

Toggle display

[
    {
        "chatParticipantTimes": {
            "cookie": "asdgjh2095hga984598hg",
            "times": []
        }
    },
    {
        "chatParticipantTimes": {
            "cookie": "asdgjh2095hga984598hg",
            "times": [
                {
                    "delivered": 12345,
                    "userUri": "bbmpim://user/id/23576"
                }
            ]
        }
    },
    {
        "chatParticipantTimes": {
            "times": [
                {
                    "delivered": 12345,
                    "read": 12346,
                    "userUri": "bbmpim://user/id/5"
                },
                {
                    "read": 7124,
                    "userUri": "bbmpim://user/id/6"
                },
                {
                    "userUri": "bbmpim://user/id/7"
                }
            ]
        }
    }
]

Name	chatParticipantTimesGet
Since	R5
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R5	Yes	The id of the chat whose participants are being queried.
cookie	string	Opt	R5	Yes	An opaque value supplied by your application that will be echoed back in the response.
userUri	user key	Opt	R5	Yes	Iff 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.

Toggle display

[
    {
        "chatParticipantTimesGet": {
            "chatId": "12"
        }
    },
    {
        "chatParticipantTimesGet": {
            "chatId": "234754",
            "cookie": "slggjq3240987g0987",
            "userUri": "bbmpim://user/id/123"
        }
    }
]

Name	chatStart
Since	2017.02
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
cookie	string	Req	2017.02	Yes	An opaque string generated by your application that will be included in the resulting 'listAdd' or 'chatStartFailed' message.
data	object	Opt	R6	No	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).
invitePolicy	string	Opt ParticipantsOnly	R4	Yes	The 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. Member Description AdminsOnly Only chat admins may invite participants to the chat. ParticipantsOnly Only chat participants may invite participants to the chat.
invitees	array	Req	2017.02	Yes	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. Type Req Since Log Description object Req 2017.02 No Each invitee may be identified by a user URI or regId. Entries without one of these identifiers will be ignored. Name Type Req Since Log Description regId number (int64) Opt 2017.02 Yes 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. userUri user key Opt 2017.02 Yes The URI of an existing user to invite to the chat. When present, the 'regId' is ignored.
isOneToOne	boolean	Opt False	R3	Yes	When 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.
localData	object	Opt	R6	No	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.
privateData	object	Opt	R7	No	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).
subject	string	Opt	2017.02	No	The subject of the chat. This field has a maximum size of 128 code points. When omitted, this defaults to the empty string.

Toggle display

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

Name	chatStartFailed
Since	2017.02
Direction	Incoming

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

Name	Type	Req	Since	Log	Description
chatId	chat key	Opt	R6	Yes	This is present iff the 'reason' is 'AlreadyExists'. This is the id of the existing 1:1 chat.
cookie	string	Req	2017.02	Yes	The opaque value supplied by your application when issuing the 'chatStart' request that has failed.
reason	string	Req	2017.02	Yes	The reason that the 'chatStart' request failed. This field is an enumeration. Member Description 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.

Toggle display

[
    {
        "chatStartFailed": {
            "cookie": "chocolate",
            "reason": "None"
        }
    },
    {
        "chatStartFailed": {
            "chatId": "12",
            "cookie": "vanilla",
            "reason": "AlreadyExists"
        }
    }
]

Name	chatTyping
Since	R4
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R4	Yes	The id of the chat in which the local user is typing.
messageId	chatMessage key	Opt	R6	Yes	If supplied, this is the id of the 'chatMessage' the local user is taking the action against as indicated by the 'tag' field. This field is ignored when the 'tag' isn't present or when the messageId isn't known to bbmcore.
tag	string	Opt	R6	Yes	Your 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.

Toggle display

[
    {
        "chatTyping": {
            "chatId": "2824"
        }
    },
    {
        "chatTyping": {
            "chatId": "7",
            "tag": "VoiceNote"
        }
    },
    {
        "chatTyping": {
            "chatId": "88",
            "messageId": "375",
            "tag": "Edit"
        }
    }
]

Name	endpointDeregister
Since	R4
Direction	Outgoing

Requests that bbmcore de-register endpoint(s). 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.

Name	Type	Req	Since	Log	Description
cookie	string	Req	R4	Yes	An opaque value to be included in the associated 'endpointDeregisterResult'.
endpointId	string	Opt	R4	Yes	The identifier of the endpoint to de-register, or to keep if the 'keep' flag is true. When no endpointId is provided all endpoints will be de-registered, including the one issuing the de-register request. The current list of endpoints can be obtained using the 'endpointsGet' request.
keep	boolean	Opt	R11	Yes	Flag indicating if the endpointId provided should be kept, and all other endpoints de-registered.

Toggle display

[
    {
        "endpointDeregister": {
            "cookie": "cookie1",
            "endpointId": "13124523943944079cdc729adeff25a2A4gD2diIgj5Jd3SG6HFfda"
        }
    },
    {
        "endpointDeregister": {
            "cookie": "cookie2",
            "endpointId": "13124523943944079cdc729adeff25a2A4gD2diIgj5Jd3SG6HFfda",
            "keep": true
        }
    },
    {
        "endpointDeregister": {
            "cookie": "cookie3"
        }
    }
]

Name	endpointDeregisterResult
Since	R4
Direction	Incoming

The result of an 'endpointDeregister' request.

Name	Type	Req	Since	Log	Description
cookie	string	Req	R4	Yes	The opaque value supplied in the 'endpointDeregister' this result is associated to.
result	string	Req	R4	Yes	The result of the update. This field is an enumeration. Member Description Failure The de-registration could not be completed, and may be retried later. Success The de-registration has completed successfully.

Toggle display

[
    {
        "endpointDeregisterResult": {
            "cookie": "chocolate",
            "result": "Success"
        }
    },
    {
        "endpointDeregisterResult": {
            "cookie": "chocolate",
            "result": "Failure"
        }
    }
]

Name	endpointDeregistered
Since	R6
Direction	Incoming

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.

Toggle display

[
    {
        "endpointDeregistered": {}
    }
]

Name	endpointUpdate
Since	R4
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
cookie	string	Req	R4	Yes	An opaque value to be included in the associated 'endpointUpdateResult'.
description	string	Req	R4	No	The 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.
endpointId	string	Opt	R4	Yes	The identifier of the endpoint to update obtained from an 'endpoints' response. If omitted, the local endpointId is used.
nickname	string	Req	R4	No	The name assigned to the endpoint by the end-user; empty if none assigned. This will be truncated to at most 2000 Unicode Code Points.

Toggle display

[
    {
        "endpointUpdate": {
            "cookie": "chocolate",
            "description": "Apple iPhone 8s (iOS v10.1)",
            "endpointId": "13124523943944079cdc729adeff25a2A4gD2diIgj5Jd3SG6HFfda",
            "isLegacyDelegate": true,
            "nickname": ""
        }
    },
    {
        "endpointUpdate": {
            "cookie": "chocolate",
            "description": "Gumshoe OS",
            "isLegacyDelegate": false,
            "nickname": "S.M.A.R.T. Watch"
        }
    }
]

Name	endpointUpdateResult
Since	R4
Direction	Incoming

The result of an 'endpointUpdate' request.

Name	Type	Req	Since	Log	Description
cookie	string	Req	R4	Yes	The opaque value supplied in the 'endpointUpdate' this result is associated to.
result	string	Req	R4	Yes	The result of the update. This field is an enumeration. Member Description Failure The update could not be applied, and may be retried later. Success The update has been applied successfully.

Toggle display

[
    {
        "endpointUpdateResult": {
            "cookie": "chocolate",
            "result": "Success"
        }
    },
    {
        "endpointUpdateResult": {
            "cookie": "chocolate",
            "result": "Failure"
        }
    }
]

Name	endpoints
Since	R4
Direction	Incoming

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

Name	Type	Req	Since	Log	Description
cookie	string	Req	R4	Yes	The opaque value supplied in the 'endpointsGet' this result is associated to.
maxEndpoints	number (uint64)	Opt	R4	Yes	The maximum number of persistent endpoints that can be registered for this identity. This field will always be present when the 'result' is 'Success'.
registeredEndpoints	array	Opt	R4	Yes	The 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. Type Req Since Log Description object Req R4 Yes A single endpoint. Name Type Req Since Log Description description string Req R4 No The 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. endpointId string Req R4 Yes The 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. isCurrent boolean Opt False R4 Yes When present and true, this endpoint is the one that issued the 'endpointsGet' request that resulted in this 'endpoints' response. isEphemeral boolean Opt False R4 Yes When 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. nickname string Req R4 No The 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.
result	string	Req	R4	Yes	The result of the request. This field is an enumeration. Member Description 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.

Toggle display

[
    {
        "endpoints": {
            "cookie": "chocolate",
            "result": "Failure"
        }
    },
    {
        "endpoints": {
            "cookie": "chocolate",
            "maxEndpoints": 3,
            "registeredEndpoints": [
                {
                    "description": "BlackBerry KEYone",
                    "endpointId": "13124523943944079cdc729adeff25a2A4gD2diIgj5Jd3SG6HFfda",
                    "isCurrent": false,
                    "isEphemeral": false,
                    "isLegacyDelegate": false,
                    "nickname": "Work Phone"
                },
                {
                    "description": "Debian GNU/Linux 9.0",
                    "endpointId": "53484523943944079cdc729adeff25a2A4gD2diIgj5Jd3Sfsdlij3",
                    "isCurrent": false,
                    "isEphemeral": false,
                    "isLegacyDelegate": true,
                    "nickname": "Work PC"
                },
                {
                    "description": "NVIDIA Shield K1",
                    "endpointId": "fjdsrlgj458944079cdc729adeff25a2A4gD2diIgj5Jd3f35HF569",
                    "isCurrent": false,
                    "isEphemeral": false,
                    "isLegacyDelegate": false,
                    "nickname": "Personal Tablet"
                }
            ],
            "result": "Success"
        }
    }
]

Name	endpointsGet
Since	R4
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
cookie	string	Req	R4	Yes	An opaque value to be returned in the associated 'endpoints' response.

Toggle display

[
    {
        "endpointsGet": {
            "cookie": "13124523-9439-4407-9cdc-729adeff25a2"
        }
    }
]

Name	identities
Since	R6
Direction	Incoming

The response to the 'identitiesGet' message.

Name	Type	Req	Since	Log	Description
cookie	string	Req	R6	Yes	The opaque value supplied in the 'identitiesGet' message this result is associated to.
info	array	Opt	R6	Yes	The 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. Type Req Since Log Description object Req R6 Yes The information for a found identity. Name Type Req Since Log Description appUserId string Req R6 Yes Your application user id for this identity, in the same form as the 'authToken' 'userId' field. regId string (int64) Req R6 Yes The Spark Communications regId for this identity.
result	string	Req	R6	Yes	The result of the request. This field is an enumeration. Member Description Failure The request could not be completed and may be retried later. Success The lookup was successful.

Toggle display

[
    {
        "identities": {
            "cookie": "arrowroot",
            "result": "Failure"
        }
    },
    {
        "identities": {
            "cookie": "arrowroot",
            "identities": [
                {
                    "appUserId": "23jr95yrr03oe",
                    "regId": "4855746228"
                },
                {
                    "appUserId": "2kfjj5g45kfk4",
                    "regId": "1000002393"
                },
                {
                    "appUserId": "1",
                    "regId": "1"
                }
            ],
            "result": "Success"
        }
    }
]

Name	identitiesGet
Since	R6
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
appUserIds	array	Opt	R6	Yes	A list of application user ids to lookup. Either this or 'regIds' must be specified. The following table describes the type of each array element. Type Req Since Log Description string Req R6 Yes Your application user id for this identity, in the same form as the 'authToken' 'userId' field.
cookie	string	Req	R6	Yes	An opaque value to be returned in the associated 'identities' response.
regIds	array	Opt	R6	Yes	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. Type Req Since Log Description string (int64) Req R6 Yes A Spark Communications regId for this identity.

Toggle display

[
    {
        "identitiesGet": {
            "appUserIds": [
                "21389hfdhf983",
                "rhabawe434g3"
            ],
            "cookie": "13124523-9439-4407-9cdc-729adeff25a2"
        }
    },
    {
        "identitiesGet": {
            "cookie": "13124523-9439-4407-9cdc-729adeff25a2",
            "regIds": [
                "1872374576594",
                "95303948244"
            ]
        }
    }
]

Name	listAdd
Since	2.0
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
cookie	string	Opt	2.1	Yes	Holds 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.
elements	array	Opt	2.0	Yes	Holds 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. Type Req Since Log Description object Opt 2.0 No Holds the full state of the items to add to the list.
type	string	Opt	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "listAdd": {
            "elements": [
                {
                    "chatId": "8475",
                    "content": "Hello world!",
                    "flags": "I",
                    "messageId": "793873",
                    "recall": "None",
                    "senderUri": "bbmpim://user/id/29",
                    "state": "Delivered",
                    "stateIsPartial": false,
                    "tag": "Text",
                    "timestamp": 30987309874
                },
                {
                    "chatId": "5",
                    "flags": "I",
                    "messageId": "93874",
                    "recall": "None",
                    "senderUri": "bbmpim://user/id/29",
                    "state": "Delivered",
                    "stateIsPartial": false,
                    "tag": "Join",
                    "timestamp": 30987309921
                }
            ],
            "type": "chatMessage"
        }
    }
]

Name	listAll
Since	2.1
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
type	string	Req	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "listAll": {
            "type": "chat"
        }
    }
]

Name	listChange
Since	2.1
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
cookie	string	Opt	2.1	Yes	Holds 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.
elements	array	Opt	2.0	Yes	Holds 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. Type Req Since Log Description object Opt 2.0 No Holds a subset of attributes for elements in the list.
type	string	Opt	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "listChange": {
            "elements": [
                {
                    "chatId": "793873",
                    "state": "Ready"
                }
            ],
            "type": "chat"
        }
    }
]

Name	listChunk
Since	2.1
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
elements	array	Req	2.1	Yes	Holds 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. Type Req Since Log Description object Opt 2.1 No Holds the full state of the items in the list.
last	boolean	Opt False	2.1	Yes	Determines if this is the last chunk in the sequence. The sequence of 'listChunk' messages is not processed until your application recieves the last chunk.
type	string	Req	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "listChunk": {
            "elements": [],
            "last": false,
            "type": "chat"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "chatId": "38267",
                    "flags": "O",
                    "keyState": "Export",
                    "lastActivity": 1098730987,
                    "lastMessage": 15,
                    "localData": {},
                    "mailboxId": "mbx123",
                    "numMessages": 10,
                    "restorePoint": 0,
                    "state": "Ready",
                    "subject": "All your base"
                },
                {
                    "chatId": "6",
                    "expiry": 3600,
                    "flags": "AP",
                    "invitePolicy": "AdminsOnly",
                    "keyState": "Synced",
                    "lastActivity": 10987300000,
                    "lastMessage": 10293873870,
                    "localData": {
                        "someData": "someValue"
                    },
                    "mailboxId": "",
                    "numMessages": 1000,
                    "restorePoint": 500,
                    "state": "Waiting",
                    "subject": "Are belong to us"
                }
            ],
            "last": true,
            "type": "chat"
        }
    }
]

Name	listElements
Since	2.1
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
cookie	string	Opt	2.1	Yes	Holds 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.
type	string	Req	2.1	Yes	Determines 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.

Toggle display

[
    {
        "listElements": {
            "cookie": "23SJFSDF3",
            "type": "chat"
        }
    }
]

Name	listRemove
Since	2.0
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
cookie	string	Opt	2.1	Yes	Holds 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.
elements	array	Opt	2.0	Yes	Holds 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. Type Req Since Log Description object Opt 2.0 No Holds the removed elements with only their primary key attribute(s) present.
type	string	Opt	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "listRemove": {
            "cookie": "23SJFSDF3",
            "elements": [
                {
                    "chatId": "1"
                },
                {
                    "chatId": "2"
                }
            ],
            "type": "chat"
        }
    }
]

Name	listResync
Since	2017.02
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
criteria	object	Req	2017.02	Yes	Specifies 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.
type	string	Req	2017.02	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "listResync": {
            "criteria": {},
            "type": "chatMessage"
        }
    },
    {
        "listResync": {
            "criteria": {
                "chatId": "5"
            },
            "type": "chatMessage"
        }
    }
]

Name	participantDemote
Since	R4
Direction	Outgoing

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:

• the chat is a one-to-one chat, or
• the local user is not an admin of the chat, or
• the chat's 'state' is not 'Ready'.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R4	Yes	The id of the chat the demotion will occur within.
userUri	user key	Req	R4	Yes	The user URI of the participant to be demoted.

Toggle display

[
    {
        "participantDemote": {
            "chatId": "2347",
            "userUri": "bbmpim://user/id/5483"
        }
    }
]

Name	participantPromote
Since	R4
Direction	Outgoing

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:

• the chat is a one-to-one chat, or
• the local user is not an admin of the chat, or
• the chat's 'state' is not 'Ready'.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R4	Yes	The id of the chat the promotion will occur within.
userUri	user key	Req	R4	Yes	The user URI of the participant to be promoted.

Toggle display

[
    {
        "participantPromote": {
            "chatId": "2347",
            "userUri": "bbmpim://user/id/5483"
        }
    }
]

Name	participantRemove
Since	R4
Direction	Outgoing

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:

• the chat is a one-to-one chat, or
• the local user is not an admin of the chat, or
• the chat's 'state' is not 'Ready'.

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

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R4	Yes	The id of the chat the removal will occur within.
userUri	user key	Req	R4	Yes	The user URI of the participant to be removed.

Toggle display

[
    {
        "participantRemove": {
            "chatId": "2347",
            "userUri": "bbmpim://user/id/5483"
        }
    }
]

Name	pinResult
Since	2015.06
Direction	Incoming

Returns the result of a requestPin message.

Name	Type	Req	Since	Log	Description
cookie	string	Req	2015.06	Yes	An opaque value that is echoed back to your application if it was specified in the request.
pins	array	Opt	2015.12	No	The 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. Type Req Since Log Description object Opt 2015.12 No An individual regId to PIN mapping. Name Type Req Since Log Description pin string Req 2015.12 No The PIN associated to the regId. regId number (int64) Req 2015.12 No The regId of the user.
result	string	Req	2015.06	Yes	The result of the request. This field is an enumeration. Member Description Failure The request failed. Success The request was successful, inspect the pin field for the result.

Toggle display

[
    {
        "pinResult": {
            "cookie": "123456ABCDEF",
            "pins": [],
            "result": "Success"
        }
    },
    {
        "pinResult": {
            "cookie": "123456ABCDEF",
            "pins": [
                {
                    "pin": "12345678",
                    "regId": 1
                }
            ],
            "result": "Success"
        }
    },
    {
        "pinResult": {
            "cookie": "123456ABCDEF",
            "pins": [
                {
                    "pin": "12345678",
                    "regId": 1
                },
                {
                    "pin": "DEADBEEF",
                    "regId": 2
                },
                {
                    "pin": "5F735EE2",
                    "regId": 3
                }
            ],
            "result": "Success"
        }
    },
    {
        "pinResult": {
            "cookie": "123456ABCDEF",
            "pins": [],
            "result": "Failure"
        }
    },
    {
        "pinResult": {
            "cookie": "123456ABCDEF",
            "result": "Failure"
        }
    }
]

Name	profileKeys
Since	R3
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
privateKeys	object	Req	R3	Yes	The private signing and encryption keys. Name Type Req Since Log Description encryption string Req R3 No The unpadded base64url-encoded private encryption key. signing string Req R3 No The unpadded base64url-encoded private signing key.
publicKeys	object	Req	R3	Yes	The public signing and encryption keys. Name Type Req Since Log Description encryption string Req R3 No The unpadded base64url-encoded public encryption key. signing string Req R3 No The unpadded base64url-encoded public signing key.

Toggle display

[
    {
        "profileKeys": {
            "privateKeys": {
                "encryption": "ZW5jcnlwdGlvblByaXZhdGVLZXk",
                "signing": "c2lnbmluZ1ByaXZhdGVLZXk"
            },
            "publicKeys": {
                "encryption": "ZW5jcnlwdGlvblB1YmxpY0tleQ",
                "signing": "c2lnbmluZ1B1YmxpY0tleQ"
            }
        }
    }
]

Name	profileKeysExport
Since	R3
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description

Toggle display

[
    {
        "profileKeysExport": {}
    }
]

Name	profileKeysImport
Since	R3
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
privateKeys	object	Req	R3	Yes	The private signing and encryption keys. Name Type Req Since Log Description encryption string Req R3 No The unpadded base64url-encoded private encryption key. signing string Req R3 No The unpadded base64url-encoded private signing key.
publicKeys	object	Req	R3	Yes	The public signing and encryption keys. Name Type Req Since Log Description encryption string Req R3 No The unpadded base64url-encoded public encryption key. signing string Req R3 No The unpadded base64url-encoded public signing key.

Toggle display

[
    {
        "profileKeysImport": {
            "privateKeys": {
                "encryption": "ZW5jcnlwdGlvblByaXZhdGVLZXk",
                "signing": "c2lnbmluZ1ByaXZhdGVLZXk"
            },
            "publicKeys": {
                "encryption": "ZW5jcnlwdGlvblB1YmxpY0tleQ",
                "signing": "c2lnbmluZ1B1YmxpY0tleQ"
            }
        }
    }
]

Name	profileKeysImportFailure
Since	R4
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description

Toggle display

[
    {
        "profileKeysImportFailure": {}
    }
]

Name	pushReceived
Since	R10
Direction	Outgoing

Every time your application receives a mobile push (on Android or iOS), it should send a 'pushReceived' message to bbmcore.

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

When your application informs the SDK that it has received a mobile push, the SDK sends this message to bbmcore for you.

Name	Type	Req	Since	Log	Description

Toggle display

[
    {
        "pushReceived": {}
    }
]

Name	requestListAdd
Since	2.0
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
elements	array	Req	2.0	Yes	Holds 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. Type Req Since Log Description object Opt 2.0 No Holds the full state of the items to add to the list.
type	string	Req	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "requestListAdd": {
            "elements": [
                {
                    "calories": 400,
                    "eaten": false,
                    "type": "cheese"
                },
                {
                    "calories": 500,
                    "eaten": true,
                    "type": "roast"
                }
            ],
            "type": "sandwich"
        }
    }
]

Name	requestListAll
Since	2.1
Direction	Outgoing

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

Name	Type	Req	Since	Log	Description
type	string	Req	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "requestListAll": {
            "type": "chat"
        }
    }
]

Name	requestListChange
Since	2.0
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
cookie	string	Opt	2.1	Yes	Holds an optional cookie that was generated by your application and included in this request.
elements	array	Req	2.1	Yes	Holds 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. Type Req Since Log Description object Opt 2.1 No Holds the primary key, along with a subset of other attributes that should be changed.
id	string	Opt	2.1	No	Identifier 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.
type	string	Req	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "requestListChange": {
            "cookie": "23SJFSDF3",
            "elements": [
                {
                    "id": "42",
                    "localData": {
                        "associatedResource": "RGF0YSBvZiB0aGUgYXBwJ3MgY2hvb3NpbmcuCg=="
                    }
                }
            ],
            "type": "appMessage"
        }
    }
]

Name	requestListElements
Since	2.1
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
cookie	string	Opt	2.1	Yes	Holds 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.
elements	array	Req	2.1	Yes	Specifies the primary keys for the elements being requested. The following table describes the type of each array element. Type Req Since Log Description object Opt 2.1 No Holds the primary keys of the items to fetch.
type	string	Req	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "requestListElements": {
            "cookie": "23SJFSDF3",
            "elements": [
                {
                    "id": 209
                },
                {
                    "id": 210
                }
            ],
            "type": "chat"
        }
    }
]

Name	requestListMatching
Since	3.0
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
cookie	string	Opt	3.0	Yes	Holds 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.
criteria	object	Req	3.0	Yes	Specifies 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').
type	string	Req	3.0	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "requestListMatching": {
            "cookie": "cxZVVuD9WM231Sw3",
            "criteria": {
                "regId": "10000"
            },
            "type": "user"
        }
    },
    {
        "requestListMatching": {
            "cookie": "GdVAwVeEjkHayFv611vL6Ovxh",
            "criteria": {
                "chatId": "12",
                "tag": "Remove"
            },
            "type": "chatMessage"
        }
    }
]

Name	requestListRemove
Since	2.0
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
elements	array	Req	2.0	Yes	Holds the list elements. Each element only includes the primary key. The following table describes the type of each array element. Type Req Since Log Description object Opt 2.0 No Holds the primary key of the elements to remove.
type	string	Req	2.1	Yes	Determines which list the elements belong to. This must be a list type defined elsewhere in the protocol.

Toggle display

[
    {
        "requestListRemove": {
            "elements": [
                {
                    "id": "7"
                },
                {
                    "id": "12"
                }
            ],
            "type": "appMessage"
        }
    }
]

Name	requestPin
Since	2015.06
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
cookie	string	Req	2015.06	Yes	An opaque value supplied by your application that will be echoed back in the response.
regIds	array	Req	2015.12	No	The 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. Type Req Since Log Description number (int64) Req 2015.12 No An individual regId.

Toggle display

[
    {
        "requestPin": {
            "cookie": "123456ABCDEF",
            "regIds": [
                123456
            ]
        }
    },
    {
        "requestPin": {
            "cookie": "123456ABCDEF",
            "regIds": [
                1,
                2,
                3,
                4,
                5,
                6
            ]
        }
    }
]

Name	retryServerRequests
Since	2017.02
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description

Toggle display

[
    {
        "retryServerRequests": {}
    }
]

Name	search
Since	2015.06
Direction	Outgoing

Search bbmcore's local data for chat messages and chat subjects. This searches for the following types of results, in priority order. When the maximum number of results have been found, searching stops.

1. Messages in chats whose 'content' matches the search text.
2. Chats whose subject matches the search text.

Your application will receive a 'searchResult' in response.

When a 'search' request does not include the 'chatId' field, all chats (in all states) are examined and all result types are possible, but no more than one 'Message' type result will be returned for each matching chat. Each 'Message' result indicates the most recently received matching message in its chat.

When a 'search' request includes the 'chatId' field, only that single chat is examined and multiple 'Message' type results can be returned. Other result types will not be present. Each 'Message' result indicates one matching message in the specified chat, with more recently received messages listed first.

Name	Type	Req	Since	Log	Description
chatId	string	Opt	R8	Yes	Search a single chat for 'Message' type matches only. See this request's description for details on how this alters the search operation and results.
cookie	string	Req	2015.06	Yes	The cookie value that will be included in the 'searchResult' response.
suggestedMaxResults	number (uint64)	Opt	2015.06	Yes	Iff present, then no more than this many results will be returned. The result size can be limited to an internal unspecified maximum that is at least 50.
text	string	Req	2015.06	No	The text of the query for case-insensitive substring search. This string must contain at least one Unicode code point or an empty result set will be returned.

Toggle display

[
    {
        "search": {
            "cookie": "search-1",
            "text": "foo"
        }
    },
    {
        "search": {
            "cookie": "search-2",
            "suggestedMaxResults": 50,
            "text": "foobar"
        }
    },
    {
        "search": {
            "chatId": "123",
            "cookie": "search-3",
            "text": "foo"
        }
    }
]

Name	searchResult
Since	2015.06
Direction	Incoming

This carries the results of a 'search' request.

Name	Type	Req	Since	Log	Description
cookie	string	Req	2015.06	Yes	The cookie value that was provided in the 'search' request.
elements	array	Req	2015.06	No	The results of the search. The following table describes the type of each array element. Type Req Since Log Description object Opt 2015.06 No The list of matches that resulted from the search, in order of the priority described for 'search'. Name Type Req Since Log Description chatId chat key Req R4 No Holds the ID of the matching 'chat'. messageId chatMessage key Opt 2015.12 Yes When present, this holds the ID of the matching message. This is always an foreign key into 'chatMessage'. type string Req 2015.06 Yes The type of search result. This is where the 'text' in the 'search' request was found. This field is an enumeration. Member Description Message The chat contains a message whose 'content' matched the search. The 'chatId' field identifies the chat. The 'messageId' field will be a foreign key into 'chatMessage' indicating the matching message. Subject The chat has a 'subject' that matched the search. The 'chatId' field identifies the chat. The 'messageId' field will not be present.

Toggle display

[
    {
        "searchResult": {
            "cookie": "search-1",
            "elements": [
                {
                    "chatId": "17",
                    "type": "DisplayName",
                    "userUri": "bbmpim://user/id/3"
                },
                {
                    "chatId": "18",
                    "messageId": "7",
                    "type": "DisplayName",
                    "userUri": "bbmpim://user/id/3"
                },
                {
                    "chatId": "123",
                    "messageId": "456",
                    "type": "Message"
                },
                {
                    "chatId": "25894",
                    "type": "Subject"
                }
            ]
        }
    }
]

Name	setupError
Since	2.1
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
error	string	Req	2.1	Yes	The type of error encountered. This field is an enumeration. Member Description 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.

Toggle display

[
    {
        "setupError": {
            "error": "PermanentServerError"
        }
    },
    {
        "setupError": {
            "error": "TemporaryServerError"
        }
    }
]

Name	setupRetry
Since	R4
Direction	Outgoing

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

Name	Type	Req	Since	Log	Description

Toggle display

[
    {
        "setupRetry": {}
    }
]

Name	statsCommitted
Since	2015.04
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description

Toggle display

[
    {
        "statsCommitted": {}
    }
]

Name	syncError
Since	R4
Direction	Incoming

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

Name	Type	Req	Since	Log	Description
error	string	Req	R4	Yes	The type of endpoint sync error encountered. This field is an enumeration. Member Description Failure The endpoint sync failed. IncorrectPasscode The provided passcode was incorrect. Timeout The endpoint sync timed out before it could be completed.

Toggle display

[
    {
        "syncError": {
            "error": "IncorrectPasscode"
        }
    }
]

Name	syncPasscodeChange
Since	R6
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
passcode	string	Req	R6	No	The passcode to use when re-protecting the identity's existing sync data.

Toggle display

[
    {
        "syncPasscodeChange": {
            "passcode": "newSecret"
        }
    }
]

Name	syncPasscodeChangeResult
Since	R6
Direction	Incoming

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

Name	Type	Req	Since	Log	Description
result	string	Req	R6	Yes	The result of attempting to set a new passcode. This field is an enumeration. Member Description 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.

Toggle display

[
    {
        "syncPasscodeChangeResult": {
            "result": "Success"
        }
    },
    {
        "syncPasscodeChangeResult": {
            "result": "TemporaryFailure"
        }
    }
]

Name	syncStart
Since	R4
Direction	Outgoing

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.

• If the 'syncPasscodeState' is 'None', then your application must wait until 'syncPasscodeState' changes to another value.
• If the 'syncPasscodeState' is 'New', then bbmcore has not found any existing sync data in KMS for this identity and it must create new sync data. Your application must send 'syncStart' with an 'action' of 'New' and supply the 'passcode' that will be used to protect and upload the new sync data to KMS.
• If the 'syncPasscodeState' is 'Existing', then bbmcore has found existing sync data in the KMS and your application must do one of the following.
  1. Your application can send 'syncStart' with an 'action' of 'Existing' to supply a 'passcode' to use when unprotecting the existing sync data. The 'setupState' will move to 'state' 'SyncStarted' during the attempt.
     • If the attempt to unprotect the sync data works, endpoint sync has finished and the 'setupState' will move to 'state' 'Ongoing'.
     • If the attempt doesn't work, 'setupState' will move back to 'state' 'SyncRequired' and a 'syncError' response will be sent by bbmcore indicating the reason for the error. Your application can take one of these actions again.
  2. Your application can send 'syncStart' with an 'action' of 'New' to delete all existing sync data from KMS and start again with newly generated sync data protected by the new 'passcode'. In response, bbmcore will move the 'setupState' to 'state' 'SyncStarted'. All other endpoints will be automatically deregistered and will have to go through setup again during which they will have to provide the new 'passcode' value (as an 'Existing' action).
     • If successful, the 'setupState' will move to 'state' 'Ongoing'.
     • If unsuccessful, the 'setupState' will return to 'state' 'SyncRequired' and a 'syncError' response will be sent by bbmcore indicating the reason for the error.

Name	Type	Req	Since	Log	Description
action	string	Opt	R6	Yes	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. Member Description 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.
passcode	string	Req	R4	No	This is the passcode used to protect sync data in the BlackBerry Key Management Service.

Toggle display

[
    {
        "syncStart": {
            "passcode": "ABC123"
        }
    },
    {
        "syncStart": {
            "action": "New",
            "passcode": "NewSecret"
        }
    },
    {
        "syncStart": {
            "action": "Existing",
            "passcode": "OldSecret"
        }
    }
]

Name	userKeysChanged
Since	R6
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
userUri	user key	Req	R6	Yes	The URI of the user whose keys have changed.

Toggle display

[
    {
        "userKeysChanged": {
            "userUri": "bbmpim://user/id/123"
        }
    }
]

Name	userKeysImport
Since	R3
Direction	Outgoing

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.

Name	Type	Req	Since	Log	Description
keys	array	Req	R3	Yes	The list of user keys to set. The following table describes the type of each array element. Type Req Since Log Description object Req R3 Yes The keys for the user. Name Type Req Since Log Description encryptionPublicKey string Req R3 No The unpadded base64url-encoded encryption public key. regId string Req R3 Yes The regId of the user the keys are for. If no user with the given regId exists, one will be created. signingPublicKey string Req R3 No The unpadded base64url-encoded signing public key.

Toggle display

[
    {
        "userKeysImport": {
            "keys": [
                {
                    "encryptionPublicKey": "ZW5jcnlwdGlvblB1YmxpY0tleTEyMw",
                    "regId": "123",
                    "signingPublicKey": "c2lnbmluZ1B1YmxpY0tleTEyMw"
                },
                {
                    "encryptionPublicKey": "ZW5jcnlwdGlvblB1YmxpY0tleTMyMQ",
                    "regId": "321",
                    "signingPublicKey": "c2lnbmluZ1B1YmxpY0tleTMyMQ"
                }
            ]
        }
    }
]

Name	userKeysImportFailure
Since	R4
Direction	Incoming

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.

Name	Type	Req	Since	Log	Description
regIds	array	Req	R4	Yes	The list of regIds that failed to import. The following table describes the type of each array element. Type Req Since Log Description string Req R4 Yes The regId that failed to import.

Toggle display

[
    {
        "userKeysImportFailure": {
            "regIds": [
                "123",
                "321"
            ]
        }
    }
]

Name	wipe
Since	2016.06
Direction	Outgoing

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

Name	Type	Req	Since	Log	Description

Toggle display

[
    {
        "wipe": {}
    }
]

// 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]}}

Type	appMessage
Since	R4
Primary key	id
Actions	requestListAll, requestListChange, requestListElements, requestListRemove
Events	listAdd, 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.

Name	Type	Req	Since	Log	Description
data	object	Req	R4	No	The 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.
externalId	string	Req	R4	Yes	The id of your application message, as specified by the system that injected it.
id	string	Req	R4	Yes	The local id of your application message.
localData	object	Req	R4	Yes	This 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'.
postTime	number (int64)	Req	R4	Yes	The time, in milliseconds since 1970 UTC, at which the message was posted for delivery.

Message	requestListRemove
Since	R4

Use this to remove application messages.

Message	requestListChange
Since	R4
Attributes	localData

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

Toggle display

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

Type	chat
Since	2017.02
Primary key	chatId
Actions	requestListAll, requestListChange, requestListElements, requestListMatching
Events	listAdd, 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.

Name	Type	Req	Since	Log	Description
chatId	string	Req	2017.02	Yes	The 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.
data	object	Req	R6	No	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).
flags	string	Req	2017.02	Yes	Compact 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 Name Letter Since Description 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. missingChatKey M R13 The chat has at least one message that chat keys are missing for. 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.
invitePolicy	string	Opt	R4	Yes	The 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. Member Description AdminsOnly Only chat admins may invite participants to the chat. ParticipantsOnly Only chat participants may invite participants to the chat.
keyState	string	Opt Synced	R3	Yes	The 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. Member Description 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.
lastActivity	number (uint64)	Req	2017.02	Yes	This holds the timestamp, in seconds since 1970, 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 and that message does not have the 'neverCountUnread' flag set, 'lastActivity' is set to the 'timestamp' of that message. 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.
lastMessage	number (uint64)	Req	2017.02	Yes	The 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.
localData	object	Req	2017.02	No	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.
mailboxId	string	Req	R3	Yes	The identifier used externally to uniquely identify this chat. Empty when not known.
numMessages	number (uint64)	Req	2017.02	Yes	The 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.
numUnread	number (uint64)	Req	R5	Yes	The number of incoming messages in the chat that the local user has yet to mark as Read. This count does not include messages that have 'neverCountUnread' flag set.
privateData	object	Req	R7	No	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).
restorePoint	number (uint64)	Req	2017.02	Yes	The 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.
state	string	Req	2017.02	Yes	The state of the chat. This field is an enumeration. Member Description 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 can remove it explicitly with 'chatLeave' (and in some cases, with 'chatHide'). 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 its message history. Content added via 'chatMessageSend' will be queued to be sent and will still be added to the 'chatMessage' list and reported via 'listAdd'. Note that no 'listAdd' event occurs for a 'chatMessage' restored or received while a chat is in this state. When the chat 'state' becomes 'Ready', your application must ask bbmcore for any existing messages. 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 and reported via 'listAdd'. Note that no 'listAdd' event occurs for a 'chatMessage' restored or received while a chat is in this state because such activity cannot happen while the chat lacks keys.
subject	string	Req	2017.02	No	Holds the user-readable subject of the chat. This field has a maximum size of 128 code points.

Message	requestListChange
Since	R2
Attributes	subject, 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

Message	requestListMatching
Description	Use requestListMatching to lookup subsets of this list.
Criteria	Name Type Since Description mailboxId string R5 Match the single chat with the specified mailboxId. When this criterion is specified, all other criteria are ignored. keyState string R3 Match all chats with the given 'keyState'. Returns an empty list if no match is found, or any errors occur.

Toggle display

[
    {
        "listAdd": {
            "elements": [
                {
                    "avatar": "",
                    "chatId": "38267",
                    "data": {},
                    "flags": "O",
                    "keyState": "Export",
                    "lastActivity": 1098730987,
                    "lastMessage": 15,
                    "localData": {},
                    "mailboxId": "mbx123",
                    "numMessages": 10,
                    "numUnread": 0,
                    "orgId": "9029820000",
                    "privateData": {
                        "pinned": false
                    },
                    "restorePoint": 0,
                    "state": "Ready",
                    "subject": "All your base"
                },
                {
                    "avatar": "",
                    "chatId": "6",
                    "data": {
                        "appContextId": "miZPa8ef1Xj5Vl7YmSyYVxKdbJDBIMNK",
                        "avatar": "https://avatar.server/8GWl2rOF"
                    },
                    "expiry": 3600,
                    "flags": "AP",
                    "invitePolicy": "AdminsOnly",
                    "keyState": "Synced",
                    "lastActivity": 10987300000,
                    "lastMessage": 10293873870,
                    "localData": {
                        "someData": "someValue"
                    },
                    "mailboxId": "",
                    "numMessages": 1000,
                    "numUnread": 23,
                    "privateData": {
                        "chatNickname": "Friends from Work",
                        "notificationPriority": "High",
                        "pinned": false
                    },
                    "restorePoint": 500,
                    "state": "Waiting",
                    "subject": "Are belong to us"
                }
            ],
            "type": "chat"
        }
    },
    {
        "listAll": {
            "type": "chat"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "avatar": "",
                    "chatId": "38267",
                    "data": {},
                    "flags": "O",
                    "keyState": "Export",
                    "lastActivity": 1098730987,
                    "lastMessage": 15,
                    "localData": {},
                    "mailboxId": "mbx123",
                    "numMessages": 10,
                    "numUnread": 0,
                    "orgId": "9029820000",
                    "privateData": {
                        "pinned": false
                    },
                    "restorePoint": 0,
                    "state": "Ready",
                    "subject": "All your base"
                },
                {
                    "avatar": "",
                    "chatId": "6",
                    "data": {
                        "appContextId": "miZPa8ef1Xj5Vl7YmSyYVxKdbJDBIMNK",
                        "avatar": "https://avatar.server/8GWl2rOF"
                    },
                    "expiry": 3600,
                    "flags": "AP",
                    "invitePolicy": "AdminsOnly",
                    "keyState": "Synced",
                    "lastActivity": 10987300000,
                    "lastMessage": 10293873870,
                    "localData": {
                        "someData": "someValue"
                    },
                    "mailboxId": "",
                    "numMessages": 1000,
                    "numUnread": 23,
                    "privateData": {
                        "chatNickname": "Friends from Work",
                        "notificationPriority": "High",
                        "pinned": false
                    },
                    "restorePoint": 500,
                    "state": "Waiting",
                    "subject": "Are belong to us"
                }
            ],
            "last": true,
            "type": "chat"
        }
    },
    {
        "listRemove": {
            "elements": [
                {
                    "chatId": "38267"
                },
                {
                    "chatId": "6"
                }
            ],
            "type": "chat"
        }
    },
    {
        "listElements": {
            "type": "chat"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "avatar": "",
                    "chatId": "38267",
                    "data": {},
                    "flags": "O",
                    "keyState": "Export",
                    "lastActivity": 1098730987,
                    "lastMessage": 15,
                    "localData": {},
                    "mailboxId": "mbx123",
                    "numMessages": 10,
                    "numUnread": 0,
                    "orgId": "9029820000",
                    "privateData": {
                        "pinned": false
                    },
                    "restorePoint": 0,
                    "state": "Ready",
                    "subject": "All your base"
                },
                {
                    "avatar": "",
                    "chatId": "6",
                    "data": {
                        "appContextId": "miZPa8ef1Xj5Vl7YmSyYVxKdbJDBIMNK",
                        "avatar": "https://avatar.server/8GWl2rOF"
                    },
                    "expiry": 3600,
                    "flags": "AP",
                    "invitePolicy": "AdminsOnly",
                    "keyState": "Synced",
                    "lastActivity": 10987300000,
                    "lastMessage": 10293873870,
                    "localData": {
                        "someData": "someValue"
                    },
                    "mailboxId": "",
                    "numMessages": 1000,
                    "numUnread": 23,
                    "privateData": {
                        "chatNickname": "Friends from Work",
                        "notificationPriority": "High",
                        "pinned": false
                    },
                    "restorePoint": 500,
                    "state": "Waiting",
                    "subject": "Are belong to us"
                }
            ],
            "last": true,
            "type": "chat"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "chatId": "38267",
                    "data": {},
                    "keyState": "Export",
                    "localData": {},
                    "subject": "All your base"
                },
                {
                    "chatId": "6",
                    "data": {
                        "appContextId": "miZPa8ef1Xj5Vl7YmSyYVxKdbJDBIMNK",
                        "avatar": "https://avatar.server/8GWl2rOF"
                    },
                    "invitePolicy": "AdminsOnly",
                    "keyState": "Synced",
                    "localData": {
                        "someData": "someValue"
                    },
                    "subject": "Are belong to us"
                }
            ],
            "type": "chat"
        }
    }
]

Type	chatMessage
Since	2017.02
Primary key	chatId, messageId
Actions	requestListChange, requestListElements, requestListMatching
Events	listAdd, 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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	2017.02	Yes	The unique identifier of the chat to which this message belongs.
content	string	Opt	2017.02	No	Holds the text content of the message, when the 'tag' has such a concept; otherwise omitted.
data	object	Opt	2017.02	Yes	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'. Name Type Req Since Log Description Admin object Opt R4 Yes Information 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'. Name Type Req Since Log Description promotion boolean Req R4 Yes True if the user has been promoted to admin. False if they have been demoted. userUri user key Req R4 Yes Identifies the participant that has been updated. Remove object Opt R4 Yes Information about a participant removal. Sent by the user who made the removal. Name Type Req Since Log Description userUri user key Req R4 Yes Identifies the participant that has been removed. forwarded boolean Opt False R11 Yes Iff present and true, then this message is considered a forwarded message. It can be present for any 'tag' and is independent from other fields in 'data'. A forwarded message is a message that was obtained from one chat and sent in another chat.
externalId	string	Opt	R13	Yes	The identifier used externally to uniquely identify this chat message, base64-encoded with the RFC 4648 Section 4 (default) alphabet and padding. This field is present iff this chat message has such an identifier when this BBMDS message was emitted. Bbmcore does not emit 'listChange' or 'listElement' messages when this identifier becomes known for a message that previously lacked one.
file	string	Opt	2017.02	No	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.
fileSize	number (uint64)	Opt	R7	No	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.
fileState	string	Opt	2017.02	Yes	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. Member Description 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.
flags	string	Req	2017.02	Yes	Compact 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 Name Letter Since Description control C R9 This message was flagged by the sending application as being for control purposes versus for display purposes. This flag is useful for introducing new custom message types (typically with a new 'tag' value) that older endpoints do not understand. Some applications, such as Instant Messaging applications, will want to inform the user that some message was received even when that type of message is unknown to the endpoint. For example, an Instant Messaging application might show "This item is not supported." when an unknown type of message is received in a chat. This lets users know they received something, but their client can't display it. This flag is meant to allow a sender to prevent the display of such placeholders for messages that the receiver doesn't understand. When an endpoint receives a message that it does not understand and the message has this flag set, it should ignore the message and not even attempt to display a placeholder. The flag indicates that the receiving endpoint is safe to assume that the message was never meant to be displayed in any versions of the application. In this way, any older endpoint that knows about this flag and behaves accordingly can be told which messages are worth displaying placeholders for and which messages are "control" messages that it can completely ignore even when those messages (and their 'tag' values) were not yet invented when the older endpoint was made. There is a subtle distinction between understanding and supporting a message. Receivers that do understand a received message should ignore this flag and decide how to handle it based on what they do and don't want to support. Changes should be designed so that receivers that partially understand a received message, and, for example, know its 'tag' and how to display its 'content' but which don't know all of the 'data' fields should be able to use what they can from the message and still behave properly. It is only receivers that do not even understand the message that should consider this flag. When sending a newly introduced message type, consider whether receivers that are completely ignorant of the message should display a placeholder or not. If and only if they never should, then set this flag. If your application has no concept of placeholders, this flag is irrelevant. Bbmcore does not set or act upon this flag. 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. neverCountUnread N R9 This message never contributes to the 'chat' 'numUnread' count and never sets the 'chat' 'lastActivity' timestamp. Your application can set this on messages it sends that are not displayed by other endpoints. Doing so helps the 'chat' 'numUnread' count reflect the number of messages that the user has not read. This flag has no effect on the 'state' of a chat message or the behaviour of 'chatMessageRead'. For example, messages with this flag will be 'Delivered' when received and can be marked as 'Read'. 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.
localData	object	Opt	R5	No	This 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.
messageId	string (uint64)	Req	2017.02	Yes	The 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.
recall	string	Opt None	2017.02	Yes	This field indicates the recall state of the message. This field is an enumeration. Member Description 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.
ref	array	Opt	R5	Yes	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. Type Req Since Log Description object Req R5 Yes Each element of the 'ref' array represents a single reference to another 'chatMessage'. Name Type Req Since Log Description messageId chatMessage key Req R5 Yes The 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. tag string Req R5 Yes Your 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. Member Description Edit This message edits the referenced message. To allow edits from the original sender only, use the following behaviour. If the 'senderUri' matches that of the referenced message, this message's 'content' and/or other fields (depending on what makes sense in your application) should be displayed in place of the 'content' from the original message or any previously received messages with an 'Edit' ref. If the 'senderUri' does not match that of the referenced message, this 'ref' must be ignored (and possibly even removed with 'chatMessageRefRemove') and the message must be treated as if was not an edit. If this message also has a 'refBy' with tag 'Edit', that referencing message must be ignored. An 'Edit' can not itself be edited. Instead, send a new message with an 'Edit' 'ref' to the original message that is to be edited. Quote This message quotes the referenced message. Thread This message belongs to a thread that has the referenced message as its parent.
refBy	array	Opt	R5	Yes	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. Type Req Since Log Description object Req R5 Yes Each element of the 'refBy' array represents one or more references from another 'chatMessage'. Name Type Req Since Log Description count number (uint64) Req R5 Yes The 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'. newestRef chatMessage key Req R5 Yes The 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. tag string Req R5 Yes Your application-specified tag that indicates what kind of reference it is. This field is an enumeration. Member Description Edit This message has been edited by the referring message. To allow edits from the original sender only, use the following behaviour. If the 'senderUri' matches that of the referring message, that message's 'content' and/or other fields (depending on what makes sense in your application) should be displayed in place of the 'content' from this original message or any previously received messages with an 'Edit' ref. If the 'senderUri' of the referencing message does not match, this 'refBy' must be ignored (and possibly even removed with 'chatMessageRefRemove') and it must be treated as if it were not an edit. If this message also has a 'ref' with tag 'Edit', the referencing message indicated by this 'refBy' must be ignored. An 'Edit' can not itself be edited. Instead, send a new message with an 'Edit' 'ref' to the original message that is to be edited. Quote This message has been quoted by the referring message. Thread This message belongs to a thread that has the referring messages as its children.
senderUri	user key	Req	2017.02	Yes	Holds the user URI of the sender of this message. See the URIs section for information on the URI format.
state	string	Req	2017.02	Yes	This field indicates the overall delivery state of the message. This field is an enumeration. Member Description 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.
stateIsPartial	boolean	Req	2017.02	Yes	This indicates whether or not the state applies to some (true) or all (false) recipients.
tag	string	Req	2017.02	Yes	Indicates the type of content this message represents. This field is an enumeration. Member Description 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'.
thumb	string	Opt	2017.02	No	A path to a small file that is carried in the message.
timestamp	number (uint64)	Req	2017.02	Yes	The time at which this message was posted to the BlackBerry Infrastructure, in seconds since 1970.

Message	requestListChange
Since	R5
Attributes	localData

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

Message	requestListMatching
Description	Use requestListMatching to lookup subsets of this list.
Criteria	Name Type Since Description chatId string 2017.02 Filters the requested list by the 'chatId' attribute. This field is required, and at least one of the 'tag' or 'ref' fields must also be present. tag string 2017.02 When present, the requested list is filtered by the 'tag' attribute. 'Text' is not a supported value for this criteria. senderUri string R9 When present, the requested list is filtered by the 'senderUri' attribute. ref object R5 When 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.

Message	listResync
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	Name Type Since Description chatId string 2017.02 Elements of this list with a 'chatId' matching the 'chatId' of this message, have changed or been removed.

Toggle display

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

Type	chatMessageFileProgress
Since	R5
Primary key	chatId, messageId
Actions	requestListElements
Events	listAdd, 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'.)

Name	Type	Req	Since	Log	Description
bytes	number (uint64)	Req	R5	Yes	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.
chatId	chat key	Req	R5	Yes	Holds the id of the chat that contains the attachment's message.
messageId	chatMessage key	Req	R5	Yes	Holds the id of the message (within that chat referred to by 'chatId') whose attachment's transfer progress is being reported.
total	number (uint64)	Req	R5	Yes	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.

Toggle display

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

Type	chatParticipant
Since	R4
Primary key	chatId, userUri
Actions	requestListElements, requestListMatching
Events	listAdd, listChange, listElements, listRemove

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

Name	Type	Req	Since	Log	Description
chatId	string	Req	R4	Yes	The id of the chat this participant is a member of.
flags	string	Req	R4	Yes	Compact 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 Name Letter Since Description admin A R4 The participant is an admin for the chat. This only applies to chats without the 'oneToOne' flag.
state	string	Req	R4	Yes	The current state of the participant. This field is an enumeration. Member Description 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.
userUri	user key	Req	R4	Yes	The URI of the user this participant represents.

Message	requestListMatching
Description	Use requestListMatching to lookup subsets of this list.
Criteria	Name Type Since Description chatId string R4 When 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. userUri string R5 Must be used in combination with state. When provided, returns all participants from any chat if they match the given userUri and state. state string R5 Must be used in combination with userUri.

Toggle display

[
    {
        "listAdd": {
            "elements": [
                {
                    "chatId": "2398734",
                    "flags": "",
                    "state": "Active",
                    "userUri": "bbmpim://user/id/123"
                },
                {
                    "chatId": "77",
                    "flags": "A",
                    "state": "Pending",
                    "userUri": "bbmpim://user/id/321"
                }
            ],
            "type": "chatParticipant"
        }
    },
    {
        "listRemove": {
            "elements": [
                {
                    "chatId": "2398734",
                    "userUri": "bbmpim://user/id/123"
                },
                {
                    "chatId": "77",
                    "userUri": "bbmpim://user/id/321"
                }
            ],
            "type": "chatParticipant"
        }
    },
    {
        "listElements": {
            "type": "chatParticipant"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "chatId": "2398734",
                    "flags": "",
                    "state": "Active",
                    "userUri": "bbmpim://user/id/123"
                },
                {
                    "chatId": "77",
                    "flags": "A",
                    "state": "Pending",
                    "userUri": "bbmpim://user/id/321"
                }
            ],
            "last": true,
            "type": "chatParticipant"
        }
    }
]

Type	global
Since	2.1
Primary key	name
Actions	requestListChange, requestListElements
Events	listChange, 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.

Name	Type	Req	Since	Log	Description
name	string	Req	2.1	Yes	String 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.
value	any	Req	2.1	Yes	Value of the variable. The type depends on the variable name, so ignore what 'type' is documented for this attribute here.

Message	requestListChange
Since	2.1
Attributes	value

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.

Toggle display

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

Type	stat
Since	R5
Primary key	name
Actions	requestListAll
Events	listAll, 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.

Name	Type	Req	Since	Log	Description
count	array	Req	R5	Yes	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. Type Req Since Log Description number (uint64) Req R5 Yes The count of this statistic (or this part of the statistic). This will always contain at least one element.
name	string	Req	R5	Yes	The name of the statistic.
part	array	Opt	R5	Yes	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. Type Req Since Log Description string Req R5 Yes The name of this part of the statistic. If the 'part' array is present, it will always contain at least one part name.

Toggle display

[
    {
        "listAll": {
            "type": "stat"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "count": [
                        1
                    ],
                    "name": "setup"
                },
                {
                    "count": [
                        77
                    ],
                    "name": "setup.err"
                },
                {
                    "count": [
                        12,
                        1,
                        2
                    ],
                    "name": "mailbox.addMember",
                    "part": [
                        "ok",
                        "500",
                        "400"
                    ]
                },
                {
                    "count": [
                        42
                    ],
                    "name": "mailbox.removeMember",
                    "part": [
                        "ok"
                    ]
                },
                {
                    "count": [
                        7,
                        102,
                        4
                    ],
                    "name": "msg",
                    "part": [
                        "Picture",
                        "Text",
                        "File"
                    ]
                },
                {
                    "count": [
                        1,
                        2,
                        4
                    ],
                    "name": "msg.thumb.Picture",
                    "part": [
                        "4K",
                        "8K",
                        "64K"
                    ]
                },
                {
                    "count": [
                        1,
                        2,
                        2,
                        1,
                        1
                    ],
                    "name": "msg.file.Picture",
                    "part": [
                        "256K",
                        "2M",
                        "3M",
                        "4M",
                        "8M"
                    ]
                },
                {
                    "count": [
                        2,
                        1,
                        1
                    ],
                    "name": "msg.file.File",
                    "part": [
                        "128K",
                        "48M",
                        "128M"
                    ]
                }
            ],
            "last": true,
            "type": "stat"
        }
    },
    {
        "listElements": {
            "type": "stat"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "count": [
                        1
                    ],
                    "name": "setup"
                },
                {
                    "count": [
                        77
                    ],
                    "name": "setup.err"
                },
                {
                    "count": [
                        12,
                        1,
                        2
                    ],
                    "name": "mailbox.addMember",
                    "part": [
                        "ok",
                        "500",
                        "400"
                    ]
                },
                {
                    "count": [
                        42
                    ],
                    "name": "mailbox.removeMember",
                    "part": [
                        "ok"
                    ]
                },
                {
                    "count": [
                        7,
                        102,
                        4
                    ],
                    "name": "msg",
                    "part": [
                        "Picture",
                        "Text",
                        "File"
                    ]
                },
                {
                    "count": [
                        1,
                        2,
                        4
                    ],
                    "name": "msg.thumb.Picture",
                    "part": [
                        "4K",
                        "8K",
                        "64K"
                    ]
                },
                {
                    "count": [
                        1,
                        2,
                        2,
                        1,
                        1
                    ],
                    "name": "msg.file.Picture",
                    "part": [
                        "256K",
                        "2M",
                        "3M",
                        "4M",
                        "8M"
                    ]
                },
                {
                    "count": [
                        2,
                        1,
                        1
                    ],
                    "name": "msg.file.File",
                    "part": [
                        "128K",
                        "48M",
                        "128M"
                    ]
                }
            ],
            "last": true,
            "type": "stat"
        }
    }
]

Type	typing
Since	R4
Primary key	userUri, chatId
Actions	requestListAll, requestListElements
Events	listAdd, 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.

Name	Type	Req	Since	Log	Description
chatId	chat key	Req	R4	Yes	Holds the id of the chat in which the user is typing.
messageId	chatMessage key	Opt	R6	Yes	If 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.
tag	string	Opt	R6	Yes	Your 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.
userUri	user key	Req	R4	Yes	Holds the unique identifier of the user that is currently typing.

Toggle display

[
    {
        "listAdd": {
            "elements": [
                {
                    "chatId": "239789432",
                    "userUri": "bbmpim://user/id/1"
                },
                {
                    "chatId": "17",
                    "tag": "VoiceNote",
                    "userUri": "bbmpim://user/id/5"
                },
                {
                    "chatId": "17",
                    "messageId": "90",
                    "tag": "Edit",
                    "userUri": "bbmpim://user/id/5"
                }
            ],
            "type": "typing"
        }
    },
    {
        "listAll": {
            "type": "typing"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "chatId": "239789432",
                    "userUri": "bbmpim://user/id/1"
                },
                {
                    "chatId": "17",
                    "tag": "VoiceNote",
                    "userUri": "bbmpim://user/id/5"
                },
                {
                    "chatId": "17",
                    "messageId": "90",
                    "tag": "Edit",
                    "userUri": "bbmpim://user/id/5"
                }
            ],
            "last": true,
            "type": "typing"
        }
    },
    {
        "listRemove": {
            "elements": [
                {
                    "chatId": "239789432",
                    "userUri": "bbmpim://user/id/1"
                },
                {
                    "chatId": "17",
                    "userUri": "bbmpim://user/id/5"
                },
                {
                    "chatId": "17",
                    "userUri": "bbmpim://user/id/5"
                }
            ],
            "type": "typing"
        }
    },
    {
        "listElements": {
            "type": "typing"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "chatId": "239789432",
                    "userUri": "bbmpim://user/id/1"
                },
                {
                    "chatId": "17",
                    "tag": "VoiceNote",
                    "userUri": "bbmpim://user/id/5"
                },
                {
                    "chatId": "17",
                    "messageId": "90",
                    "tag": "Edit",
                    "userUri": "bbmpim://user/id/5"
                }
            ],
            "last": true,
            "type": "typing"
        }
    }
]

Type	user
Since	2.0
Primary key	uri
Actions	requestListChange, requestListElements, requestListMatching
Events	listAdd, 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'.

Name	Type	Req	Since	Log	Description
keyState	string	Opt Synced	R3	Yes	The current state of the user's keys. A new protected user is created in the 'Import' state. This field is an enumeration. Member Description 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.
pin	string	Opt	R4	No	Holds the user's PIN as an 8-character lowercase hexadecimal string. This field will be omitted when the user has no PIN.
regId	string (int64)	Opt	2014.10	No	Holds 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.
uri	string	Req	2.1	Yes	Holds the unique identifier for the user. See the URIs section for information on the URI format.

Message	requestListMatching
Description	Use requestListMatching to lookup subsets of this list.
Criteria	Name Type Since Description regId string (int64) 2014.10 Match 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. pin string R3 Match 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. keyState string R3 Match 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.

Toggle display

[
    {
        "listAdd": {
            "elements": [
                {
                    "avatarHash": "450235345",
                    "category": "Colleagues",
                    "displayName": "J. Binks",
                    "flags": "EPR",
                    "isContact": true,
                    "keyState": "Import",
                    "maxVcardSize": 15,
                    "nickname": "J. Binks",
                    "personalMessage": "Busy writing scripts",
                    "personalMessageTimestamp": "98739872",
                    "uri": "bbmpim://dbid/93"
                },
                {
                    "avatarHash": "150235345",
                    "category": "",
                    "displayName": "G. Smith",
                    "flags": "PQS",
                    "isContact": false,
                    "keyState": "Synced",
                    "maxVcardSize": 194,
                    "nickname": "G. Smith",
                    "personalMessage": "Destroy him, my robots.",
                    "personalMessageTimestamp": "28739872",
                    "uri": "bbmpim://dbid/33"
                },
                {
                    "avatarHash": "34234321",
                    "category": "",
                    "displayName": "H. Solo",
                    "flags": "ER",
                    "isContact": true,
                    "keyState": "Synced",
                    "maxVcardSize": 0,
                    "nickname": "H. Solo",
                    "personalMessage": "I shot first",
                    "personalMessageTimestamp": "2987392",
                    "uri": "bbmpim://dbid/100"
                },
                {
                    "avatarHash": "235345",
                    "category": "",
                    "displayName": "John Smith",
                    "flags": "EPQ",
                    "isContact": false,
                    "keyState": "Synced",
                    "maxVcardSize": 0,
                    "nickname": "John from work",
                    "personalMessage": "Boom goes the dynamite",
                    "personalMessageTimestamp": "3434344",
                    "uri": "bbmpim://dbid/400"
                },
                {
                    "avatarHash": "650235345",
                    "category": "",
                    "displayName": "John Traveller",
                    "flags": "EFPRZ",
                    "isContact": true,
                    "keyState": "Synced",
                    "lastConnectedTime": "1432580033",
                    "maxVcardSize": 0,
                    "nickname": "Johnny",
                    "personalMessage": "",
                    "regId": "123456789012",
                    "uri": "bbmpim://dbid/500"
                },
                {
                    "avatarHash": "9024296666",
                    "category": "Rebels",
                    "displayName": "David",
                    "flags": "EFPR",
                    "isContact": false,
                    "keyState": "Synced",
                    "maxVcardSize": 0,
                    "nickname": "",
                    "org": {
                        "firstName": "David",
                        "id": "a1taxi",
                        "lastName": "Jones",
                        "readOnly": true
                    },
                    "personalMessage": "",
                    "pin": "ca224cbb",
                    "regId": "19024296666",
                    "uri": "bbmpim://dbid/99"
                },
                {
                    "avatarHash": "9024296666",
                    "category": "",
                    "displayName": "JC",
                    "flags": "EFPR",
                    "isContact": false,
                    "keyState": "Synced",
                    "maxVcardSize": 0,
                    "nickname": "",
                    "org": {
                        "department": "Executives",
                        "firstName": "John",
                        "id": "blackberry",
                        "lastName": "Chen",
                        "readOnly": false,
                        "title": "CEO"
                    },
                    "personalMessage": "",
                    "pin": "ffff1111",
                    "regId": "1902429777",
                    "uri": "bbmpim://dbid/99"
                }
            ],
            "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": {
            "elements": [
                {
                    "avatarHash": "450235345",
                    "category": "Colleagues",
                    "displayName": "J. Binks",
                    "flags": "EPR",
                    "isContact": true,
                    "keyState": "Import",
                    "maxVcardSize": 15,
                    "nickname": "J. Binks",
                    "personalMessage": "Busy writing scripts",
                    "personalMessageTimestamp": "98739872",
                    "uri": "bbmpim://dbid/93"
                },
                {
                    "avatarHash": "150235345",
                    "category": "",
                    "displayName": "G. Smith",
                    "flags": "PQS",
                    "isContact": false,
                    "keyState": "Synced",
                    "maxVcardSize": 194,
                    "nickname": "G. Smith",
                    "personalMessage": "Destroy him, my robots.",
                    "personalMessageTimestamp": "28739872",
                    "uri": "bbmpim://dbid/33"
                },
                {
                    "avatarHash": "34234321",
                    "category": "",
                    "displayName": "H. Solo",
                    "flags": "ER",
                    "isContact": true,
                    "keyState": "Synced",
                    "maxVcardSize": 0,
                    "nickname": "H. Solo",
                    "personalMessage": "I shot first",
                    "personalMessageTimestamp": "2987392",
                    "uri": "bbmpim://dbid/100"
                },
                {
                    "avatarHash": "235345",
                    "category": "",
                    "displayName": "John Smith",
                    "flags": "EPQ",
                    "isContact": false,
                    "keyState": "Synced",
                    "maxVcardSize": 0,
                    "nickname": "John from work",
                    "personalMessage": "Boom goes the dynamite",
                    "personalMessageTimestamp": "3434344",
                    "uri": "bbmpim://dbid/400"
                },
                {
                    "avatarHash": "650235345",
                    "category": "",
                    "displayName": "John Traveller",
                    "flags": "EFPRZ",
                    "isContact": true,
                    "keyState": "Synced",
                    "lastConnectedTime": "1432580033",
                    "maxVcardSize": 0,
                    "nickname": "Johnny",
                    "personalMessage": "",
                    "regId": "123456789012",
                    "uri": "bbmpim://dbid/500"
                },
                {
                    "avatarHash": "9024296666",
                    "category": "Rebels",
                    "displayName": "David",
                    "flags": "EFPR",
                    "isContact": false,
                    "keyState": "Synced",
                    "maxVcardSize": 0,
                    "nickname": "",
                    "org": {
                        "firstName": "David",
                        "id": "a1taxi",
                        "lastName": "Jones",
                        "readOnly": true
                    },
                    "personalMessage": "",
                    "pin": "ca224cbb",
                    "regId": "19024296666",
                    "uri": "bbmpim://dbid/99"
                },
                {
                    "avatarHash": "9024296666",
                    "category": "",
                    "displayName": "JC",
                    "flags": "EFPR",
                    "isContact": false,
                    "keyState": "Synced",
                    "maxVcardSize": 0,
                    "nickname": "",
                    "org": {
                        "department": "Executives",
                        "firstName": "John",
                        "id": "blackberry",
                        "lastName": "Chen",
                        "readOnly": false,
                        "title": "CEO"
                    },
                    "personalMessage": "",
                    "pin": "ffff1111",
                    "regId": "1902429777",
                    "uri": "bbmpim://dbid/99"
                }
            ],
            "last": true,
            "type": "user"
        }
    },
    {
        "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"
        }
    }
]

Name	authTokenState
Since	2016.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.

Type	Req	Since	Log	Description
string	Req	2016.03	Yes	The current state of the authToken value in bbmcore. This field is an enumeration. Member Description 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.

Toggle display

[
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "authTokenState",
                    "value": "Needed"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "authTokenState",
                    "value": "Needed"
                }
            ],
            "type": "global"
        }
    },
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "authTokenState",
                    "value": "Ok"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "authTokenState",
                    "value": "Ok"
                }
            ],
            "type": "global"
        }
    }
]

Name	chatMessageFileAutoDownload
Since	R5

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.

Type	Req	Since	Log	Description
boolean	Req	R5	Yes	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.

Message	requestListChange
Since	R5
Attributes	value

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

Toggle display

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

Name	endpointId
Since	R5

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

Type	Req	Since	Log	Description
string	Req	R5	No

Toggle display

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

Name	localPin
Since	2.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.

Type	Req	Since	Log	Description
string	Req	2.1	No

Toggle display

[
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "localPin",
                    "value": "3987bb0a"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "localPin",
                    "value": "3987bb0a"
                }
            ],
            "type": "global"
        }
    },
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "localPin",
                    "value": ""
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "localPin",
                    "value": ""
                }
            ],
            "type": "global"
        }
    }
]

Name	localUri
Since	2.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.

Type	Req	Since	Log	Description
user key	Req	2.2	No

Toggle display

[
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "localUri",
                    "value": "bbmpim://user/id/0"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "localUri",
                    "value": "bbmpim://user/id/0"
                }
            ],
            "type": "global"
        }
    }
]

Name	profileKeysState
Since	R3

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.

Type	Req	Since	Log	Description
string	Req	R3	Yes	The current state of the profile's keys. A new profile is created in the 'NotSynced' state. This field is an enumeration. Member Description 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.

Message	requestListChange
Since	R3
Attributes	value

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

Toggle display

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

Name	registrationToken
Since	R5

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.

Type	Req	Since	Log	Description
string	Req	R5	No	The registration token given to this endpoint during setup, or the empty string. See above.

Toggle display

[
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "registrationToken",
                    "value": "50yjSGScACkfrdPE3CHibuopdF7yQWulFafTepbtOCcALhslpwudzZ7X3cMfwUP9Q8aT52GkwXJ2yqEbSLpkJepHbqwrNOVrirlzoChDXk40mEP6kxqi9uw7uY13UkFz"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "registrationToken",
                    "value": "50yjSGScACkfrdPE3CHibuopdF7yQWulFafTepbtOCcALhslpwudzZ7X3cMfwUP9Q8aT52GkwXJ2yqEbSLpkJepHbqwrNOVrirlzoChDXk40mEP6kxqi9uw7uY13UkFz"
                }
            ],
            "type": "global"
        }
    }
]

Name	setupAccount
Since	2015.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'.

Type	Req	Since	Log	Description
string	Req	2015.04	Yes	Indicates what kind of identity was used for the most recent attempt to set up Spark Communications Services. This field is an enumeration. Member Description 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.

Toggle display

[
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "setupAccount",
                    "value": "None"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "setupAccount",
                    "value": "None"
                }
            ],
            "type": "global"
        }
    },
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "setupAccount",
                    "value": "New"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "setupAccount",
                    "value": "New"
                }
            ],
            "type": "global"
        }
    },
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "setupAccount",
                    "value": "Existing"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "setupAccount",
                    "value": "Existing"
                }
            ],
            "type": "global"
        }
    }
]

Name	setupState
Since	2.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:

Name	Type	Req	Since	Log	Description
progressMessage	string	Opt	2.1	Yes	When 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. Member Description 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.
state	string	Req	2.1	Yes	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. Member Description 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).

Toggle display

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

Name	syncPasscodeState
Since	R6

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.

Type	Req	Since	Log	Description
string	Req	R6	Yes	This state tells your application whether bbmcore requires a passcode during the endpoint sync phase of setup. This field is an enumeration. Member Description 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.

Toggle display

[
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "syncPasscodeState",
                    "value": "None"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "syncPasscodeState",
                    "value": "None"
                }
            ],
            "type": "global"
        }
    },
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "syncPasscodeState",
                    "value": "New"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "syncPasscodeState",
                    "value": "New"
                }
            ],
            "type": "global"
        }
    },
    {
        "listElements": {
            "type": "global"
        }
    },
    {
        "listChunk": {
            "elements": [
                {
                    "name": "syncPasscodeState",
                    "value": "Existing"
                }
            ],
            "last": true,
            "type": "global"
        }
    },
    {
        "listChange": {
            "elements": [
                {
                    "name": "syncPasscodeState",
                    "value": "Existing"
                }
            ],
            "type": "global"
        }
    }
]

Name	syncing
Since	R7

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.

Type	Req	Since	Log	Description
boolean	Req	R7	No

Toggle display

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