Messages are core events signalling trade, order activity as well as warnings about exposure, etc. In some commercial setups it is actually a requirement that a third party application displays these messages to the user, and registers that the user has seen/acknowledged them. 

The messages can be retrieved by requesting a list of pending messages, but since many of them (such as order confirmations) are time critical to the end user, the resource also supports subscription. Most messages will stay for an indeterminate period until confirmed. It is an applications responsibility to let the user acknowledge that messages have been received.

The messages are primarily intended for communicating important information to the user. Therefore all messages have a core set of properties, such as MessageHeader and MessageBody, which the third party application can simply display to the user, without the application understanding the precise meaning of the message. A third party application should not rely on parsing the contents of the MessageBody to extract values from it, as texts are translated and their formatting may change without notice.

Recently we have started to introduce structured information in message specific fields, but this is an ongoing effort.

Properties of a Message

All messages have a few shared properties:

Of particular interest is:

• MessageHeader and MessageBody are used for display to the user. They are translated into the language defined by the users language setting.
• MessageId identifies the unique message and is also used for acknowledging that it has been seen by the end user.
• MessageType determines the meaning of the message. You may also use this to determine which extra fields (if any) are provided in addition to those in the base message.

Message Types

Currently the following types are available: 

Acknowledging Messages

When a message is received whether that is through a request for a list or as an event due to a subscription, it is recommended to show the message to the end-user and let him acknowledge that he has seen the message. It has the effect of both removing the message and logging the fact that the end-user has seen the message, An acknowledge is done through a put request to the underlying message.

Appendix: Meaning and contents of individual message types

Account Depreciation

Message to indicate that an account has depreciated beyond a limit as specified by MIFID II regulations. Only sent for configured client segments.

Additional Fields

Sample Message

An example of an account depreciation message:

{
    "AccountId": "ATSEACCOUNT",
    "DateTime": "2017-09-11T15:59:21.000000Z",
    "DepreciationPct": 21.5,
    "DisplayName": "",
    "MessageBody": "",
    "MessageHeader": "Account depreciation",
    "MessageId": "875192084_0",
    "MessageType": "AccountDepreciation",
    "ReportingPeriodStart": "2017-07-03T09:23:10.000000Z"
} 

Margin Call

Message to indicate that some margin utilization threshold has been breached. Margin calls can either come in the form of a warning or as a margin stop out indicating that the account is now being stopped out.

Additional Fields

None.

Sample Message

An example of a margin call provided as the users account breaches a configured limit for receiving a margin utilization warning (in this case 80%).

{
    "DateTime": "2017-02-17T11:54:01.883000Z",
    "DisplayName": "",
    "MessageBody": "\r\n\r\nOn 17 Feb 2017 at 11:54:01 (GMT)\r\n\r\nPlease be advised that you are now utilizing 80.6% of your available margin.\r\n\r\n\r\n",
    "MessageHeader": "Margin Usage",
    "MessageId": "1238325560_69048872",
    "MessageType": "MarginCall"
}

Mifid

Message to indicate that the clients Mifid status has changed.

Additional Fields

None.

Sample Message

{
    "DateTime": "2018-02-12T00:00:00.000000Z",
    "DisplayName": "",
    "MessageBody": "Client classification changed for Product Area Mutual Funds from Professional to Retail",
    "MessageHeader": "Product Area Classification Change",
    "MessageId": "875236381_0",
    "MessageType": "Mifid"
} 

Notification

Message sent from broker to client, typically about important trading related event.

Additional Fields

None.

Sample Message

{
    "DateTime": "2018-02-16T00:00:00.000000Z",
    "DisplayName": "",
	"DisplayType": "Popup",
    "MessageBody": "As a result of today's UK decision to leave EU, we will continue to hold margins at current levels for the time being.
    "MessageHeader": "Dealer Broadcast",
    "MessageId": "875236381_4",
    "MessageType": "Notification"
} 

Position Depreciation

Message to indicate that a position has depreciated beyond a limit as specified by MIFID II regulations. Only sent for configured client segments.

Additional Fields

Sample Message

An example of a position depreciation message:

{
    "AccountId": "ATSEACCOUNT",
    "AssetType": "Stock",
    "DateTime": "2017-08-16T16:30:21.000000Z",
    "DepreciationPct": 19.5,
    "DisplayAndFormat": {
      "BarrierFormat": "Normal",
      "Currency": "DKK",
      "Decimals": 2,
      "Description": "Vestas Wind Systems A/S",
      "Format": "Normal",
      "OrderDecimals": 2,
      "StrikeFormat": "Normal",
      "Symbol": "VWS:xcse"
    },
    "DisplayName": "",
    "ExecutionTimeOpen": "2017-07-03T09:23:10.000000Z",
    "MessageBody": "",
    "MessageHeader": "Position depreciation",
    "MessageId": "875135463_0",
    "MessageType": "PositionDepreciation",
    "OpenPrice": 615.75,
    "Uic": 15611
}

Price Alert

Message to indicate that a price alert has been triggered.

Additional Fields

Sample Message

An example of a position depreciation message:

{
    "AssetType": "Stock",
    "Comment": "",
    "DateTime": "2018-01-24T14:25:58.000000Z",
    "DisplayAndFormat": {
      "BarrierFormat": "Normal",
      "Currency": "GBP",
      "Decimals": 2,
      "Description": "Great Portland Estates Plc",
      "Format": "Normal",
      "OrderDecimals": 2,
      "StrikeFormat": "Normal",
      "Symbol": "GPOR:xlon"
    },
    "DisplayName": "",
    "MessageBody": "Price alert was triggered",
    "MessageHeader": "PriceAlert",
    "MessageId": "875236289_0",
    "MessageType": "PriceAlert",
    "Operation": "trg",
    "Operator": ">=",
    "PriceAlertData": {
      "AssetType": "Stock",
      "Comment": "",
      "Operation": "trg",
      "Operator": ">=",
      "PriceAlertId": "77637",
      "PriceVariable": "Traded",
      "TriggerPrice": 650,
      "Uic": 4198
    },
    "PriceAlertId": "77637",
    "PriceVariable": "Traded",
    "TriggerPrice": 650,
    "Uic": 4198
}

Trade Confirmation

Message to indicate changes to orders or positions.

Additional Fields

Sample Message

An example of a trade confirmation message provided when placing a limit order.

{
    "AccountId": "339070INET",
    "DateTime": "2017-02-17T10:54:04.867000Z",
    "DisplayName": "",
    "MessageBody": "You placed order to buy 25,000 GBPUSD spot @ 1.24130 limit G.T.C. .\r\nFront office order id: 49066054\r\nAccount: 339070INET",
    "MessageHeader": "Order placed",
    "MessageId": "873066395_0",
    "MessageType": "TradeConfirmation",
	"OrderId": "52323005"
}

See also the live sample on Trade messages (with source).