Message Broker V2.4

Changes are related to the camera detection event types and face resource messages.

This is the server-to-server communication description.

With the server to server API, it is possible to receive (both camera, user and face resource) events through a message queue. The messages are JSON encoded and are sent over WebSockets with the STOMP protocol.

📘

Before start using this API, we at CameraManager need to setup and configure the message queue before you can use this. The configuration and some more explanation need to be discussed beforehand.

Each message type has to be configured separately, and hence request for the same has to be made separately.

Camera detection event types
There are following event types supported by the new version of the Message Broker:

• audioDetected
• vmdDetected
• pirDetected
• doorbellDetected
• cameraOnline
• cameraOffline
• audioCategorized
• objectDetected
• objectInAreaDetected
• objectTripwireDetected
• personDetected
• personInAreaDetected
• personTripwireDetected
• animalDetected
• faceDetected
• faceRecognized

Events on the event_full_v24 exchange has the same structure as the JSON response of the Events API - without the stream URLs. For details on the response, please refer to the documentation of the API here: https://developer.cameramanager.com/reference/getevents

To get messages related to the events you can subscribe to a topic using following exchange name and routing key:

/exchange/{system name}_{message_type}/{partnerId}.{acountId}.{cameraId}.{action}.{eventTypes}

Note:
exchange_name = {system name}_{message_type}
routing_key = {partnerId}.{acountId}.{cameraId}.{action}.{eventTypes}

Fields explanation

Example for event_full_v24 message type:

/exchange/somesystem_event_full_v24/12345.12345.32.create.objectDetected.faceDetected
{
    "eventId": 15720517375,
    "type": "faceDetected",
    "source": {
        "type": "camera",
        "sourceId": 32,
        "accountId": 12345
    },
    "timestamp": "2021-05-04T07:10:03.371+0000",
    "namespace": "namespace.cm",
    "boundingBox": [
        .3,
        .42,
        .68,
        .12
    ],
    "confidence": 1.0
}

Face resource messages

JSON Structure

{
  "accountId": <account_id>,
  "faceId": <face_id>,
  "timestamp": <timestamp>,
  "action": <action>
}

Fields explanation

To get messages related to faces you can subscribe to a topic using following exchange name and routing key:

/exchange/{system name}_{message_type}/{partnerId}.{acountId}.{action}

Note:
exchangename = {system name}{message_type}
routing_key = {partnerId}.{acountId}.{action}

Examples

/exchange/somesystem_face_v24/12345.09876.create
{
  "accountId": 12345,
  "faceId": "b6e27147-f649-448e-8056-792d2d9654f1",
  "timestamp": "2020-11-17T14:03:01.221+0000",
  "action": "create"
}
  
/exchange/somesystem_face_v24/12345.09876.update
{
  "accountId": 12345,
  "faceId": "b6e27147-f649-448e-8056-792d2d9654f1",
  "timestamp": "2020-11-17T14:03:01.221+0000",
  "action": "update"
}
 
/exchange/somesystem_face_v24/12345.09876.delete
{
  "accountId": 12345,
  "faceId": "b6e27147-f649-448e-8056-792d2d9654f1",
  "timestamp": "2020-11-17T14:03:01.221+0000",
  "action": "delete"
}

Topic filtering
Although it can be useful to subscribe to a specific topic, normally wildcards will be used to receive events from a wide range. A topic is built up out of multiple words separated by . (dot) characters,

The following wildcards are accepted:

* (star) can substitute for exactly one word.

# (hash) can substitute for zero or more words.

For example, an event with routing key 12345.12345.32.create.objectDetected.faceDetected Matches:

12345.12345.32.create.objectDetected.faceDetected : True

12345.12345.32.create.objectDetected.faceDetected.# : True

12345.12345.32.create.objectDetected.# : True

12345.12345.32.create.objectDetected : False

12345.12345.*.create.objectDetected.faceDetected : True

12345...create.objectDetected.faceDetected : True

12345...*.objectDetected.faceDetected : True

*.12345.32.create.# : True

STOMP communication example

Message consumer connects to the Cameramanager server at IP messages.cameramanager.com using WebSockets protocol and STOMP transport.

The consumer is authenticated by using the partner email and its password to be used in the Authorization header like:

[ws://messages.cameramanager.com/stomp/v1] (ws://messages.cameramanager.com/stomp/v1)
or
[wss://messages.cameramanager.com/stomp/v1] (wss://messages.cameramanager.com/stomp/v1)

Authorization: Basic <partner_email>:
(<partner_email>: should be encoded in Base64)

Communication example on STOMP level:
_Client/message consumer messages are marked by red
_Server/message broker messages are marked by grey

.
CONNECTED
session:session-1ft-6Znzeu34Y0bgw9ibaw
heart-beat:60000,30000
version:1.2

.
SUBSCRIBE
destination:/exchange/<exchange_name>/<routing_key> <<< subscribe to the exchange <exchange_name> for a specific routing key
ack:client <<< client will send explicit acknowledgement message
prefetch-count:1 <<< number of prefetch messages

.
MESSAGE
destination/exchange/<exchangename>/123.456.32.create.objectDetected.faceDetected <<< event of type «faceDetected»
message-id:Q/exchange/<exchange_name>@@session-u0pwVrymhyUHmLLwD6ERnQ@@2
redelivered:false
expiration:120000
content-type:application/json
content-length:122

{"accountId":456,"cameraId":32,"eventId":15720517375,"timestamp":"2020-11-17T14:02:28.086+0000","type":"faceDetected","action":"create"}

Note:
You can use all possibilities of the stomp protocol

• subscribe to different queues via the same connection
• open simultaneously multiple connections
• control the way of acknowledgement mechanism: auto/client/client-individual (for further information check stomp documentation at https://stomp.github.io/)