# Cumulocity Real-time notification API **Canonical:** https://apis.io/apis/cumulocity/cumulocity-real-time-notification-api-api/ **Provider:** Cumulocity — https://apis.io/providers/cumulocity/ **Base URL:** mqtt://{tenant}.cumulocity.com:1883 **Documentation:** https://cumulocity.com/docs/device-integration/mqtt/ Cumulocity Real-time notification API is one of 62 APIs that [Cumulocity](https://apis.io/providers/cumulocity/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification. This API exposes 4 JSON Schema definitions. Tagged areas include Real-time notification API. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, a JSON-LD context, an AsyncAPI specification, and 4 JSON Schemas. # Real-time operations Real-time notification services of Cumulocity have their own subscription channel name format and URL. The real-time notifications are available for [Alarms](#tag/Alarm-notification-API), [Device control](#tag/Device-control-notification-API), [Events](#tag/Event-notification-API), [Inventory](#tag/Inventory-notification-API) and [Measurements](#tag/Measurement-notification-API). Note that when using long-polling, all POST requests must contain the Accept header, otherwise an empty response body will be returned. All requests are sent to the /notification/realtime endpoint. > **ⓘ Info:** The long-polling interface is designed as a mechanism for custom applications to poll infrequent events from Cumulocity. The long-polling interface is not designed as a mechanism to stream large data volumes (>100kB/sec) or frequent data (>50 events/sec) out of Cumulocity. The usage of long-polling is not supported for such use cases. > **⚠️ Important:** Real-time notification is based on the Bayeux protocol where idle clients will have their sessions terminated after a set interval, defaulting to 2 hours. > An idle client is one that has not received any messages from the server, nor polled the `/meta/connect` endpoint. > To avoid session termination clients should poll `/meta/connect` and follow the instructions for [Long-running connections](#tag/Real-time-notification-API/). > Additional information regarding the Bayeux protocol can be found in the CometD documentation under [Appendix C: The Bayeux Protocol Specification 1.0](https://docs.cometd.org/current3/reference/#_bayeux). ## Handshake A real-time notifications client initiates the connection negotiation by sending a message to the `/meta/handshake` channel. In response, the client receives a `clientId` which identifies a conversation and must be passed in every non-handshake request. > **ⓘ Info:** The number of parallel connections that can be opened at the same time by a single user is limited. After exceeding this limit when a new connection is created, the oldest one will be closed and the newly created one will be added in its place. This limit is configurable and managed per installation. Its default value is 10 connections per user, subscription channel and server node. When using WebSockets, a property `ext` containing an authentication object must be sent. In case of basic authentication, the token is used with Base64 encoded credentials. In case of OAuth authentication, the request must have the cookie with the authorization name, holding the access token. Moreover, the XSRF token must be forwarded as part of the handshake message. ### Request example ```http POST /notification/realtime Authorization: Content-Type: application/json [ { "channel": "/meta/handshake", "version": "1.0" } ] ``` ### Response example A successful response looks like: ```json [ { "channel": "/meta/handshake", "clientId": "69wzith4teyensmz6zyk516um4yum0mvp", "minimumVersion": "1.0", "successful": true, "supportedConnectionTypes": [ "long-polling", "smartrest-long-polling", "websocket" ], "version": "1.0" } ] ``` When an error occurs, the response looks like: ```json [ { "channel": "/meta/handshake", "error": "403::Handshake denied", "successful": false } ] ``` ## Subscribe A notification client can send subscribe messages and specify the desired channel to receive output messages from the Cumulocity server. The client will receive the messages in succeeding connect requests. Each REST API that uses the real-time notification service has its own format for channel names. See [Device control](#tag/Device-control-notification-API) for more details. ### Request example ```http POST /notification/realtime Authorization: Content-Type: application/json [ { "channel": "/meta/subscribe", "clientId": "69wzith4teyensmz6zyk516um4yum0mvp", "subscription": "/alarms/" } ] ``` ### Response example ```json [ { "channel": "/meta/subscribe", "clientId": "69wzith4teyensmz6zyk516um4yum0mvp", "subscription": "/alarms/", "successful": true } ] ``` ## Unsubscribe To stop receiving notifications from a channel, send a message to the channel `/meta/unsubscribe` in the same format as used during subscription. ### Request example Example Request: ```http POST /notification/realtime Authorization: Content-Type: application/json [ { "channel": "/meta/unsubscribe", "clientId": "69wzith4teyensmz6zyk516um4yum0mvp", "subscription": "/alarms/" } ] ``` ### Response example ```json [ { "channel": "/meta/unsubscribe", "subscription": "/alarms/", "successful": true } ] ``` ## Connect After a Bayeux client has discovered the server's capabilities with a handshake exchange and subscribed to the desired channels, a connection is established by sending a message to the `/meta/connect` channel. This message may be transported over any of the transports returned by the server in the handshake response. Requests to the connect channel must be immediately repeated after every response to receive the next batch of notifications. ### Request example ```http POST /notification/realtime Authorization: Content-Type: application/json [ { "channel": "/meta/connect", "clientId": "69wzith4teyensmz6zyk516um4yum0mvp", "connectionType": "long-polling", "advice": { "timeout": 5400000, "interval": 3000 } } ] ``` ### Response example ```json [ { "channel": "/meta/connect", "data": null, "advice": { "interval": 3000, "timeout": 5400000 }, "successful": true } ] ``` ## Disconnect To stop receiving notifications from all channels and close the conversation, send a message to the `/meta/disconnect` channel. ### Request example ```http POST /notification/realtime Authorization: Content-Type: application/json [ { "channel": "/meta/disconnect", "clientId": "69wzith4teyensmz6zyk516um4yum0mvp" } ] ``` ### Response example ```json [ { "channel": "/meta/disconnect", "successful": true } ] ``` ## Long-running connections To keep a long-running connection alive when there are no new notifications to deliver, the server will periodically send an empty `/meta/connect` response to the client. The client should send a new `/meta/connect` request immediately after receiving such a response, to ensure that the connection remains active and future notifications are delivered. ## Operations (1) | Method | Path | Summary | |---|---|---| | POST | `/notification/realtime` | Responsive communication | ## Machine-readable artifacts (18) - **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/openapi/cumulocity-real-time-notification-api-api-openapi.yml - **Documentation** — https://cumulocity.com/api/core/ - **Documentation** — https://cumulocity.com/docs/concepts/domain-model/ - **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-schema/cumulocity-managed-object-schema.json - **JSONLD** — https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-ld/cumulocity-context.jsonld - **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-schema/cumulocity-measurement-schema.json - **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-schema/cumulocity-event-schema.json - **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-schema/cumulocity-alarm-schema.json - **Documentation** — https://cumulocity.com/docs/device-integration/device-integration-introduction/ - **Documentation** — https://cumulocity.com/docs/microservice-sdk/ - **Documentation** — https://cumulocity.com/docs/reference/notifications/ - **AsyncAPI** — https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/asyncapi/cumulocity-notification2-asyncapi.yml - **Documentation** — https://cumulocity.com/api/datahub/ - **Documentation** — https://cumulocity.com/docs/datahub/datahub-overview/ - **Documentation** — https://cumulocity.com/api/dtm/ - **Documentation** — https://cumulocity.com/docs/digital-twin-manager/dtm-overview/ - **Documentation** — https://cumulocity.com/api/edge/ - **Documentation** — https://cumulocity.com/docs/edge/edge-overview/ ## Other Cumulocity APIs (12) - [Cumulocity MQTT and SmartREST API](https://apis.io/apis/cumulocity/cumulocity-mqtt-api/) - [Cumulocity MQTT Service API](https://apis.io/apis/cumulocity/cumulocity-mqtt-service-api/) - [Cumulocity Alarms API](https://apis.io/apis/cumulocity/cumulocity-alarms-api/) - [Cumulocity Application Binaries API](https://apis.io/apis/cumulocity/cumulocity-application-binaries-api/) - [Cumulocity Applications API](https://apis.io/apis/cumulocity/cumulocity-applications-api/) - [Cumulocity Asset Instances API](https://apis.io/apis/cumulocity/cumulocity-asset-instances-api/) - [Cumulocity Asset Models API](https://apis.io/apis/cumulocity/cumulocity-asset-models-api/) - [Cumulocity Binaries API](https://apis.io/apis/cumulocity/cumulocity-binaries-api/) - [Cumulocity Bulk Operations API](https://apis.io/apis/cumulocity/cumulocity-bulk-operations-api/) - [Cumulocity Cloud Sync API](https://apis.io/apis/cumulocity/cumulocity-cloud-sync-api/) - [Cumulocity Current User API](https://apis.io/apis/cumulocity/cumulocity-current-user-api/) - [Cumulocity Device Credentials API](https://apis.io/apis/cumulocity/cumulocity-device-credentials-api/) ## Tags Real-time notification API --- Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/cumulocity/cumulocity-real-time-notification-api-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/cumulocity/.