Message Subscriptions
*Information taken from Zaptec Integration Document
An installation can be configured with an AMQP (Azure Service Bus) message subscription. 3rd parties can connect to subscriptions to receive continuous push notifications when charging station’s state changes.
State observations are details such as charge mode, charge current, session energy etc. A list of observations provided to messaging subscriptions can be found in the integration document under State observation reference.
Message subscriptions must be activated per installation. This is done through the “Message subscription” option under advanced installation settings in Zaptec Portal. Please note that subscriptions are automatically removed after 14 days without use.
Enabling a subscription will configure an Azure Service Bus Topic for your installation. Messages received from installation chargers will be broadcast to this topic.
There is a wide range of options available for receiving messages from Azure Service Bus
In addition to using Microsoft’s Service Bus libraries, it is also possible to consume messages using the standard protocol AMQP 1.0 detailed here
Credentials
After messaging subscription is enabled connection details can be retrieved either:
-
For production purposes:
Connection details must be retrieved from this API method:
https://api.zaptec.com/help/index#!/Installation/Installation_GetMessagingConnectionDetails; accessible by users with installation owner or service roles.
Note: As connection credentials and host can change at any time, it is important to query message subscription connection details from our API whenever you are connecting! -
For development or testing purposes:
Connection details can be manually retrieved in Zaptec Portal advanced
installation settings; accessible by users with installation owner or service role
Example of message subscription connection details in Zaptec Portal below:
Connection details can be combined as a Service Bus connection string:
Endpoint=sb://{Host}/;SharedAccessKeyName={UserName};SharedAccessKey={Pass word};EntityPath={Topic}
Messages are published to a topic, but can only be received from the topic subscription.
Depending on the library used to connect to the service bus topic, you may need to combine the topic and subscription name in your connection settings. The full name of the topic subscriptions is: {Topic}/subscriptions/{Subscription}
Note: Message subscriptions will be disabled after 14 days without messages being sent to the subscription (e.g. chargers are offline), or without messages being consumed.
If your subscription has been disabled you need to manually re-enable this though Zaptec Portal or by requesting credentials from our public API
Please note that connection details will be reset when subscription is disabled.
Note: Message TTL is 5 minutes. Meaning that any state observation not consumed within 5 minutes will be lost.
Message Format
Messages are provided as JSON-serialized ChargerState objects https://api.zaptec.com/help/index#!/Charger/Charger_ChargerState
containing:
- ChargerId
The UUID of the charger providing the message
- StateId
The ID of the changed state observation – list of supported state observation Id’s can be found in chapter State observation
- Timestamp
The UTC timestamp when the state observation was changed, provided as an ISO 86013 string
- ValueAsString
The new state value, serialized as a string
Boolean:true=1,false=0