October 31, 2019

Introducing variables in alerts

We are excited to present the latest changes and improvements we made to alerts — messages with variables are now supported. You can use prices, indicator values, bar time and others as variables. You’ll be able to see the latest change when an alert is triggered and a notification is sent. 

Specific placeholders for variables will need to be used so that the most recent values are returned. See the list of placeholders below. They are specified in the dialog where alerts are created and modified, in the part of the message where you want to receive the corresponding value when an alert is triggered.

For example, you can create an alert for NASDAQ:AAPL ticker symbol and include the following in a message:

{{exchange}}:{{ticker}}, Price = {{close}}, Volume = {{volume}}

When an alert is triggered you will be able to see those values instead of placeholders that were shown before.

Below is the list of available placeholders.

1. {{ticker}} — returns the ticker (such as AAPL or BTCUSD).

2. {{exchange}} — exchange for the symbol (such as NASDAQ, NYSE or AMEX). Delayed data includes a DL or DLY parameter,  e.g. NYMEX_DL.

3. {{close}}, {{open}}, {{high}}, {{low}}, {{time}}, {{volume}} — corresponding values on the bar where the alert was triggered. Alerts for indicators, drawing objects and exotic types of charts depend on the time frame, while alerts for prices are always calculated based on a 1-minute time frame. {{time}} is the bar time in UTC in the yyyy-MM-ddTHH: mm: ssZ format. For example, 2019-08-27T09: 56: 00Z. The remaining values are fixed point numbers. For example, 1245.25.

4. {{timenow}} —  exact time when the alert was triggered. It’s formatted the same way as bar time {{time}}. It is accurate to seconds regardless of the selected time frame.

5. {{plot_0}}, {{plot_1}}, … {{plot_19}} — corresponding series of an indicator that is used to set an alert. The indicator series are values that you see on a chart. For example, the built-in Volume indicator has two series – Volume and Volume average. You can create an alert on the indicator and include the following in a message: 

Volume: {{plot_0}}, Volume average: {{plot_1}}

You’d see corresponding values when an alert is triggered.

Note: plots are numbered starting from zero. 

The same rules apply to scripts written in Pine. Series are counted based on their calling order in the code. See the list of functions below. Their series can be used in notification messages:

  • plot;
  • plotshape;
  • plotchar;
  • plotarrow;
  • plotbar;
  • plotcandle.

If the series argument of such functions contains a Boolean value, 0 or 1 will be substituted in the notification message. Keep in mind that certain functions — plotcandle and plotbar — display 4 series each, and every one of them will be taken into account in the numbering logic.

However, this method of accessing plots is not always convenient. To make things easier, we added support for calling plots using their names. To do this, use the placeholder:

{{plot("Name")}}

Where Name is the name of the series.

For built-in indicators, the only names that are supported are the ones that are used in the English version. In the example with the Volume indicator for accessing series using their names, you would include the following in the message:

Volume: {{plot("Volume")}}, Volume average: {{plot("Volume MA")}}

Similarly, for Pine Script to access the series you should specify the name from the title argument of the corresponding function (supported for all plot functions except plotcandle and plotbar), and the language will no longer matter. If you do not have access to the code, the name can be seen in the style settings.

For example, to access the values of this script:

//@version=4
study("My script")
plot(close, title="series")

Include this in the alert message:

{{plot("series")}}

The same name is shown in the script settings:

When using several indicators in a single alert, you can refer to the values of the first one – the one indicated in the first drop-down list. See example below.

When an alert includes these settings you can only refer to the MA values. To access the values of the script “My script”, you need to select it in the first drop-down list.

You can also specify new placeholders in the message argument of the alertcondition function. For example:

//@version=4
study("My script")
alertcondition(close>open, message="price {{ticker}} = {{close}}")

The message from the argument is automatically pulled into the message window in the alert creation dialog.
Please note that when creating an alert with a condition from the alertcondition function, the value substitution will only work for v4 scripts or higher.

Values from triggered alerts can be used together with webhooks by sending variable values from a message to the desired addresses. This opens up even more possibilities for those of you who use alerts.