Empire uses various Messages to communicate system-wide or Participant-specific updates to its users.

On the UI, the various Messages are available under the little ✉️ icon in the top-right corner. They are split into a General System Messages and an Organisation Inbox part. Both are also available via the API, so that the messages can be pulled by your external system to ensure that relevant notifications are received by your organisation in a timely and customised manner.

⚠️ It is recommended to poll the endpoints no more frequently than every 5 seconds - as this should be sufficient to be up to date and also not risk the exceeding of any API rate limits.

General System Messages

General System Messages contains system-wide announcements that might be relevant to all Participants. Such messages can be about:

• Auctions being published and moving statuses
• Nomination Windows opening and closing
• Buy-Now Offers being published
• Nomination Window Overrides defined in the system

The General Messages can be accessed via the getSystemMessages endpoint. When querying this endpoint, please ensure to have all mandatory query parameters correctly selected.

Participant Inbox

The Participant Inbox contains messages related to your organisation specifically, including:

• Changes in Auction statuses that your Organisation has participated in
• Bids submitted by someone in your Organisation
• Nominations submitted by someone in your Organisation
• Curtailment action taken on your Transmission Rights and/or Nominations

The Participant Inbox can be queried via the getParticipantMessages endpoint. This will fetch all messages fitting the search criteria. The getParticipantUnreadMessages endpoint fetches the number of your "unread" messages.

💡 As a Message being in "unread" status is only tracked on an Organisation-level, please keep in mind, that if you implement polling your Participant Inbox frequently, this number will always stay 0 (or a very low number) as each request to the getParticipantMessages endpoint zeroes the "unread" count!

This also results in anyone in your Organisation observing the the small "unread message count" indicator on Empire UI will experience it automatically resetting to zero with the polling frequency.