BlackBerry Spark Communications Platform Guide


The BlackBerry Spark Communications Platform provides a framework to develop real-time, end-to-end secure messaging capabilities in your own product or service.

The Spark security model ensures that only the sender and intended recipients can see each chat message sent, and ensures that messages aren't modified in transit between the sender and recipient. Spark also provides the framework for other forms of collaboration and communication, such as push notifications, secure voice and video calls, and file sharing. You can even extend and create new types of real-time services and use cases by defining your own custom application protocols and data types.

Architecture Overview

A Spark solution is divided into the following four parts:

Architecture Overview

Application and Spark

The Spark SDK is included in your application to provide real-time, end-to-end secure messaging capabilities. The Spark SDK has APIs that allow the application to authenticate the user, and provide a rich secure communications platform.

Identity Provider and User Management Service

Spark does not manage user identities or the social network relationships for the application. The user "accounts" within Spark represent users only within the BlackBerry Infrastructure. Applications can re-use their existing user accounts and social network by associating their application accounts to the Spark accounts.

For more detailed and technical information on the Identity Provider or the User Management Service see Identity Management and User Management Service.


Spark provides secure messaging and encryption for chats, voice calls, and video calls. The Spark SDK encrypts and signs data before it leaves the endpoint.

Encryption and signing keys need to be stored and shared securely in order to keep your user's data private. Most applications can use the BlackBerry Key Management Service (KMS) to manage these keys. Applications that need complete control over the keys can provide their own Cloud Key Storage solution. Whichever option is right for your application, Spark makes it easy to integrate key management into your solution.

Push Service

Push notifications are an important feature of a real-time applications because they allow users to be engaged with the application and be notified of everything from incoming chat messages to incoming voice or video calls. Spark is built to support push notifications and can generate push notifications on your behalf, or use your already existing push system. For more detailed and technical information see Push Notifications.


Spark offers many powerful features to help you build rich applications easily.

Access Control and Identity

Spark works with your user identity and management systems to provide strong authentication and authorization. The user accounts in Spark represent users in the BlackBerry Infrastructure only. Spark leverages OAuth and OpenID Connect so it can easily authenticate and associate your users with their Spark accounts.

Read more about identity management.

End-To-End Encryption

Spark was designed to comply with the following three security principles:

Read more about encryption.

Messaging Publish-Subscribe

Within Spark, chats are entities that can be created and manipulated. A chat is a shared space that allows many endpoints to contribute content in a series of individual chat messages. Typically, these messages represent user-visible content, but they can also contain arbitrary machine-readable information that your application can consume. Chat messages can be both published by and subscribed to by many users and endpoints for real-time delivery and updates.

Read more about the publish-subscribe model.

Identity Asserted Publishing and Subscribing

Spark controls access so that only authorized participants of a chat can publish and/or subscribe to content. Chats have administrative rights that can be assigned to other participants to control who can add more participants or make other changes.

Read more about the Spark security model.

Custom Protocols and Extensions

While it's typical to think of chats and their messages in terms of Instant Messaging (IM), the APIs of the Spark SDK are general purpose and highly extensible. A chat does not need to represent an IM conversation. Fundamentally, a chat is a shared space where you can publish custom content to the subscribers in real time. You can use this to create anything from a shared whiteboard to a fleet-tracking location service to whatever you can imagine.

Read more about different ways to use Spark.

Rich Chat Experiences

Spark makes it easy for your application to offer a fully-featured instant messaging experience with:

Read more about rich chat experiences.

Chat Message History

Participants post messages to the chat. When a message is posted to the chat, it appears below all of the earlier messages already in the chat. This series of messages is referred to as the message history. Each chat has its own message history which is accessible only to participants of the chat.

Read more about chat messages.

Guaranteed Delivery

Spark ensures that a chat message will get from its sender to the participants of the chat while still offering immediate delivery to online endpoints. The Spark SDK and BlackBerry Infrastructure work together to reconcile their views of a chat's message history and recover any messages that failed initial delivery. When messages can't be posted to chats, senders know with clear and definitive error reporting.

Chat Message Status

Spark reports the delivery status of chat messages they are first queued, then sent, then delivered, and read. External delivery status is tracked separately for each participant in each chat across all endpoints.

Chat Message Attachments

Each message in a chat can optionally carry two different kinds of attachments.

Read more about chat message attachments.

Chat Message References

The Chat Message References feature allows you to move beyond a linear view of the chat history to create richer relationships between chat messages. For example, you can use Chat Message References to implement any or all of the following features.

These are just examples. You can implement many custom behaviours and features using Chat Message References by setting up rich relationships between content.

Read more about Chat Message References.

Connection Management

Real-world endpoints aren't always connected. Wi-Fi and mobile network connections are not completely reliable, and endpoints aren't always able to maintain a perfect link to the Internet. Spark was built to expect imperfect connections while optimizing behavior to improve battery life.

Offline Delivery

When Spark SDK endpoints reconnect, they automatically reconcile their data with the BlackBerry Infrastructure, catch up, and receive all the traffic that was sent to them while they were offline.

Multiple Points of Presence

Spark allows your application to have multiple instances running and connected at the same time for the same user. This ability is referred to as having Multiple Points of Presence, or MPoP.

Read more about multiple points of presence.

Web Workers

The Spark SDK for JavaScript can run as a background task inside a Web Worker while your main web application stays in the foreground. This lets your web application be responsive even while the SDK is busy.

Even when the Spark SDK for JavaScript does not run in a Web Worker, it still offloads expensive work such as network communication and cryptography to asynchronous tasks that don't block the JavaScript main loop.

Read more about using Spark in web applications.

Mobile Push Notification: Direct or by Proxy

Spark servers support push notifications to the Spark SDK mobile clients. When new chat messages and incoming calls are pending delivery to the clients, the server can send a push notification with one of the following mechanisms:

Read more about mobile push notifications.

Peer-to-Peer Data Streams

With Spark, you can create true peer-to-peer connections that securely carry encrypted custom application data between two endpoints. These high-bandwidth connections allow you to create secure, real-time, and custom media streams or send application-specific protocol messages between endpoints for any purpose.

Read more about peer-to-peer data streams.