> For the complete documentation index, see [llms.txt](https://guide.traderevolution.com/traderevolution-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.traderevolution.com/traderevolution-api/traderevolution-apis/client-api/subscirption-to-alerts-data.md).
# Subscirption to alerts data
This page describes mechanism of receiving alerts data via websocket
### Connection
In order to receive the *alerts* data, the connection should be opened to `wss://sandbox-api.traderevolution.com/traderevolution/v1/stream/`**.**
{% hint style="warning" %}
Please note that the URL specified for connection is default, but it can be customized according to the customer's requirements.
{% endhint %}
There is a "Ping-Pong" mechanism for WebSocket connections. To maintain active WebSocket connections and detect client inactivity, the following message format is used:
```json
{"event": "PING", "t": 1731538318526}
{"event": "PONG", "t": 1731538318526}
```
### Subscribing to alert events
The request body must contain the following parameters:
**Body**
| Name | Type | Description |
|---|
event | string | Should be always subscribe in this case. |
requestId | integer | Request identifier generated by the client side. Will be used in the response. |
payload | object | An object that contains subscription information. See table below. |
**Payload object**
| Parameter | Value |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `st*` | The subscription type is specified here. The `alerts` value should be used in this case. |
| `accountId` | Optional. Defines the account for which alert updates will be received. If omitted, updates for all user accounts are returned. |
**Request body example**
```json
{
"event": "subscribe",
"requestId": 123,
"payload": {
"st": "alerts",
"accountId": 123123
}
}
```
**Response**
The server will return the following parameters in a response:
* `event` - always returns “subscribe”.
* `requestId` - id of the request to which the response was sent.
* `s` - subscription status: `ok` - if successful, or `error` - if the subscription failed.
* `errmsg` - returns an error message in case the subscription fails.
{% tabs %}
{% tab title="200" %}
```json
{
"event": "subscribed",
"requestId": 123,
"s": "ok"
}
```
{% endtab %}
{% tab title="400" %}
```json
{
"event": "subscribe",
"requestId": 123,
"s": "error",
"errmsg": "Error"
}
```
{% endtab %}
{% endtabs %}
Immediately after a successful subscription, the server sends all currently active alerts for the subscribed account(s). Each alert is sent as an individual message with `event` equal to `created`. This allows the client to initialize its local state before processing live updates.
{% hint style="warning" %}
For users with multiple accounts, a separate subscription should be created for each account. Each subscription receives its own initial snapshot.
{% endhint %}
#### Alert response structure
An object with the following parameters is returned for alert subscriptions:
| Parameter | Value |
| ----------- | -------------------------------------------------------------------------------- |
| `d` | Considered below in more details. |
| `s` | Subscription status indicator: `ok` or `error` in case the subscription fails. |
| `errmsg` | This parameter contains the text of the error which occurred when ***s=error***. |
| `st` | Always returned as `sessionSwitch` here. |
| `sessionId` | Identifier of this session. |
**Object d structure**
| Name | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event` | Indicates the actual type of alert event. Possible values: *created*, *modified*, *executed*, *expired*, *deleted*, *stopped\_by\_user*, *stopped\_by\_system*, *restarted*. |
| `alertId` | Shows the alert identifier. |
| `tradableInstrumentId` | TradableId of the instrument for which an alert was created. |
| `instrumentName` | Shows the name of the instrument for which an alert was created. |
| `alertType` | Shows the type of the alert. Possible values are: *bid*, *ask*, *last*, *change\_percent*, *volume.* |
| `condition` | Shows the condition of the alert. Possible values are: *greater*, less, *greater\_or\_equal*, *less\_or\_equal.* |
| `value` | Shows the price value for which an alert was created. |
| `importance` | Shows the importance value of alert. Possible values are: *high*, *medium*, *low*. |
| `afterExecute` | Indicates the alert behaviour after it's execution. Possible values are: *stop*, *remove*. |
| `action` | Action that will be performed after alert execution. Possible values are: *notify*, *place\_order\_and\_notify*. |
| `notificationType` | Shows which notification will be sent after alert's execution. Possible values:
1 - custom 1;
2 - custom 2;
3 - email;
4 - push.
|
| `alertMessage` | Alert message. |
| `expiration` | Alert expiration time in Unix timestamp format (milliseconds). |
| `status` | Shows the status of alert. |
| `orderParameters` | Order parameters used for orders creation when `action` is set to *place\_order\_and\_notify*. The parameters can be found [here](https://guide.traderevolution.com/traderevolution-api/traderevolution-apis/client-api/trading#submit-order). |
| `createdAt` | Alert creation time in Unix timestamp format (milliseconds). |
**Response example**
```json
{
"s": "ok",
"st": "alerts",
"accountId": 123123,
"d": {
"event": "created",
"alertId": 456,
"tradableInstrumentId": 100,
"instrumentName": "EUR/USD",
"alertType": "bid",
"condition": "greater_or_equal",
"value": 1.09786,
"importance": "high",
"afterExecute": "remove",
"action": "place_order_and_notify",
"notificationType": [
1,
2,
3
],
"alertMessage": "Alert: EUR/USD Bid >= 1.09786",
"expiration": 1738108799000,
"status": "active",
"orderParameters": {
"side": "buy",
"type": "market",
"qty": 0.01,
"stopLoss": 11,
"takeProfit": 22,
"trStopOffset": 5
},
"createdAt": 1737456600000
}
}
```
### Unsubscribing from alert events
To stop receiving alert updates, send an unsubscribe request using the same payload as for the subscription, with `"event": "unsubscribe"`.
The request body must contain the following parameters:
**Body**
| Name | Type | Description |
|---|
event | string | Should be always unsubscribe in this case. |
requestId | integer | Request identifier generated by the client side. |
payload | object | An object that contains unsubscription information. See table below. |
**Payload object**
| Parameter | Value |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `st*` | The unsubscription type is specified here. The `alerts` value should be used in this case. |
| `accountId` | Optional. Defines the account for which alert updates will be received. If omitted, updates for all user accounts are returned. |
**Request body example**
```json
{
"event": "unsubscribe",
"requestId": 124,
"payload": {
"st": "alerts",
"accountId": 123123
}
}
```
**Response**
{% tabs %}
{% tab title="200" %}
```json
{
"event": "unsubscribed",
"requestId": 123,
"s": "ok"
}
```
{% endtab %}
{% tab title="400" %}
```json
{
"event": "subscribe",
"requestId": 123,
"s": "error",
"errmsg": "Error"
}
```
{% endtab %}
{% endtabs %}
**Possible errors**
The following errors may be returned if the subscription or unsubscription request cannot be completed:
* `Unauthorized`
* `No permissions to this account`
* `Account not found`
* `Invalid subscription type`