BlackBerry Spark Communications Services Guide


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

The Spark Communications Services 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. The service 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.

Service Architecture

A Spark Communications Services solution is divided into the following four parts:

Architecture Overview


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

To get started using the SDK, see the the Download & Configure section.

Identity Providers

Spark Communications Services does not manage user identities or the social network relationships for the application. User identities within the SDK and service represent users only within the BlackBerry Infrastructure. Your application reuses its existing user accounts and social network by associating your application accounts to the SDK identities.

To learn how to use the SDK with your application's user accounts, see the Identity Providers and User Management guides.


Spark Communications Services provides secure messaging and encryption for chats, voice calls, and video calls. The 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 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, the SDK makes it easy to integrate key management into your solution.

Push Notifications

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 Communications Services 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 Communications Services offers many powerful features to help you build rich applications easily.

Access Control and Identity

Spark Communications Services works with your user identity and management systems to provide strong authentication and authorization. User identities within the SDK and service represent users only within the BlackBerry Infrastructure. Spark Communications Services leverages OAuth and OpenID Connect so it can easily authenticate and associate your users with their SDK identities.

Read more about identity management.

End-To-End Encryption

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

Read more about security and encryption.

Messaging Publish-Subscribe

Within Spark Communications Services, 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 Communications Services 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 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 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 the SDK.

Rich Chat Experiences

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

Read more about rich chat experiences.

Chat Message History

A central feature of BlackBerry Spark Communications Services is the ability to allow applications to create chats and share rich messaging experiences. A chat is a shared space that allows many endpoints to contribute content in a series of individual messages. Typically, these messages represent user-visible content, but they can also contain arbitrary information that your application can consume.

Read more about chat messages.

Guaranteed Delivery

Spark Communications Services 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 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

The SDK 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 Communications Services was built to expect imperfect connections while optimizing behavior to improve battery life.

Offline Delivery

When 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 Communications Services 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 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 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 the SDK in web applications.

Mobile Push Notification: Direct or by Proxy

The BlackBerry Infrastructure supports push notifications to mobile clients. When new chat messages and incoming calls are pending delivery to the clients, the BlackBerry Infrastructure can send a push notification with one of the following mechanisms:

Read more about mobile push notifications.

Peer-to-Peer Data Streams

With Spark Communications Services, 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.