Zaptec Service bus subscriptions

Message Subscriptions

A Zaptec User Group can be configured with an AMQP (Azure Service Bus) message subscription. Third parties can connect to the subscription to receive continuous push notifications when the state of chargers changes within installations the User Group has access to.

State observations include details such as charge mode, charge current, session energy, and other charger state changes. A list of observations provided to message subscriptions can be found in the State Observation Reference.

To use message subscriptions, you need a User Group with the appropriate permissions, either Owner or Service, for the relevant installations. Access to the User Group and activation of message subscriptions must be requested through your country’s Zaptec business representative or via Zaptec Support. You can create a Support request through the help desk.

Subscriptions are automatically removed after 14 days without use.

Enabling a subscription will configure an Azure Service Bus Topic for your user group. Messages received from installed chargers will be broadcast to this topic.

There are multiple options for receiving messages from Azure Service Bus.

In addition to using Microsoft’s Service Bus libraries, messages can be consumed using the standard protocol AMQP 1.0, detailed here.

Credentials

Once a messaging subscription is enabled, connection details can be retrieved through:

For production purposes: Connection details must be retrieved from this API method: API call (accessible by users with installation owner roles).

curl -X 'GET' \
  'https://api.zaptec.com/api/userGroups/<usergroupId>/messagingConnectionDetails' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer <bearer_token>'

As connection credentials and host can change at any time, always query the API for updated connection details before connecting.

For development or testing purposes: Connection details can be manually retrieved in the Zaptec Portal user group (accessible by owners of the user group).

Example: Message Subscription Connection Details

Connection details can be combined into a Service Bus connection string:

Endpoint=sb://{Host}/;SharedAccessKeyName=USERNAME;SharedAccessKey={Password};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 subscription is:

{Topic}/subscriptions/{Subscription}

Observation Subscription Limit. Please be aware, observation messages from an installation can only be sent to a maximum of two service bus subscriptions simultaneously.

This means if an installation has access enabled for more than two user groups, and all these groups have message subscriptions active, only two of the configured subscriptions will receive the observation messages. The system does not guarantee which two subscriptions will receive the messages if more than two are active.

Message subscriptions will be disabled after 14 days without messages being sent (e.g., chargers offline) or without messages being consumed.

Connection details will be reset when a subscription is disabled.

Message TTL is 5 minutes. Any state observation not consumed within this period will be lost.

Message Format

Messages contain a JSON-serialized ChargerState object. Charger state reference

Please note that the AMQP message body is currently delivered as a serialized string containing the JSON payload, not as a raw JSON object. Non-.NET clients may need to decode the body as a string before parsing the contained JSON.

Each message contains:

ChargerId: The UUID of the charger providing the message.
StateId: The ID of the changed state observation. A list of supported state observation IDs can be found in the State observation chapter.
Timestamp: The UTC timestamp when the state observation was changed, provided as an ISO 8601 string.
ValueAsString: The new state value, serialized as a string.

Boolean: true = 1, false = 0