Alerts
Introduction
TradingView alerts run 24x7 on our servers and do not require users to be logged in to execute. Alerts are created from the charts user interface (UI). You will find all the information necessary to understand how alerts work and how to create them from the charts UI in the Help Center’s About TradingView alerts page.
Some of the alert types available on TradingView (generic alerts, drawing alerts and script alerts on order fill events) are created from symbols or scripts loaded on the chart and do not require specific coding in Pine scripts. Any user can create these types of alerts from the charts UI.
Other types of alerts (script alerts triggering on alert() function calls, and alertcondition() alerts) require specific Pine code to be present in a script to create an alert event before script users can create alerts from them using the charts UI. Additionally, while script users can create script alerts triggering on order fill events from the charts UI on any strategy loaded on their chart, Pine coders can specify explicit order fill alert messages in their script for each type of order filled by the broker emulator.
This page covers the different ways Pine programmers can code their scripts to create alert events from which script users will in turn be able to create alerts from the charts UI. We will cover:
- How to use the alert() function to alert() function calls in studies or strategies, which can then be included in script alerts created from the charts UI.
- How to add custom alert messages to be included in script alerts triggering on the order fill events of strategies.
- How to use the alertcondition() function to generate, in studies only, alertcondition() events which can then be used to create alertcondition() alerts from the charts UI.
Keep in mind that:
- No alert-related Pine code can create a running alert in the charts UI; it merely creates alert events which can then be used by script users to create running alerts from the charts UI.
- Alerts only trigger in the realtime bar. The operational scope of Pine code dealing with any type of alert is therefore restricted to realtime bars only.
- When an alert is created in the charts UI, TradingView saves a mirror image of the script and its inputs, along with the chart’s main symbol and timeframe to run the alert on its servers. Subsequent changes to your script’s inputs or the chart will thus not affect running alerts previously created from them. If you want any changes to your context to be reflected in a running alert’s behavior, you will need to delete the alert and create a new one in the new context.
Background
The different methods Pine coders can use today to create alert events
in their script are the result of successive enhancements deployed
throughout Pine’s evolution. The
alertcondition()
function, which works in studies only, was the first feature allowing
Pine programmers to create alert events. Then came order fill alerts for
strategies, which trigger when the broker emulator creates order fill
events. Order fill events require no special code for script users to
create alerts on them, but by way of the alert_message
parameter for
order-generating strategy.*()
functions, programmers can customize the
message of alerts triggering on order fill events by defining a
distinct alert message for any number of order fulfillment events.
The alert() function is the most recent addition to Pine. It more or less supersedes alertcondition(), and when used in strategies, provides a useful complement to alerts on order fill events.
Which type of alert is best?
For Pine coders, the alert() function will generally be easier and more flexible to work with. Contrary to alertcondition(), it allows for dynamic alert messages, works in both studies and strategies and the programmer decides on the frequency of alert() events.
While alert() calls can be generated on any logic programmable in Pine, including when orders are sent to the broker emulator in strategies, they cannot be coded to trigger when orders are executed (or filled) because after orders are sent to the broker emulator, the emulator controls their execution and does not report fill events back to the script directly.
When a script user wants to generate an alert on a strategy’s order
fill events, he must include those events when creating a script alert
on the strategy in the “Create Alert” dialog box. No special code is
required in scripts for users to be able to do this. The message sent
with order fill events can, however, be customized by programmers
through use of the alert_message
parameter in order-generating
strategy.*()
function calls. A combination of
alert()
calls and the use of custom alert_message
arguments in
order-generating strategy.*()
calls should allow Pine coders to
generate alert events on most conditions occurring in their script’s
execution.
The alertcondition() function remains in Pine for backward compatibility, but it can also be used advantageously to generate distinct alerts available for selection as individual items in the “Create Alert” dialog box’s “Condition” field.
Script alerts
When a script user creates a script alert using the “Create Alert” dialog box, the events able to trigger the alert will vary depending on whether the alert is created from a study or a strategy.
A script alert created from a study will trigger when:
- The study contains alert() calls.
- The code’s logic allows a specific alert() call to execute.
- The frequency specified in the alert() call allows the alert to trigger.
A script alert created from a strategy can trigger on alert() function calls, on order fill events, or both. The script user creating an alert on a strategy decides which type of events he wishes to include in his script alert. While users can create a script alert on order fill events without the need for a strategy to include special code, it must contain alert() calls for users to include alert() function calls in their script alert.
‘alert()’ function events
The alert() function has the following signature:
message
A “series string” representing the message text sent when the alert triggers. Because this argument allows the “series” form, it can be generated at runtime and differ bar to bar, making it dynamic.
freq
An “input string” specifying the triggering frequency of the alert. Valid arguments are:
alert.freq_once_per_bar
: Only the first call per realtime bar triggers the alert (default value).alert.freq_once_per_bar_close
: An alert is only triggered when the realtime bar closes and an alert() call is executed during that script iteration.alert.freq_all
: All calls during the realtime bar trigger the alert.
The
alert()
function can be used in both studies and strategies. For an
alert()
call to trigger a script alert configured on alert() function calls,
the script’s logic must allow the
alert()
call to execute, and the frequency determined by the freq
parameter must allow the alert to trigger.
Note that by default, strategies are recalculated at the bar’s close,
so if the
alert()
function with the frequency alert.freq_all
or
alert.freq_once_per_bar
is used in a strategy, then it will be called
no more often than once at the bar’s close. In order to enable the
alert()
function to be called during the bar construction process, you need to
enable the calc_on_every_tick
option.
Using all ‘alert()’ calls
Let’s look at an example where we detect crosses of the RSI centerline:
If a script alert is created from this script:
- When RSI crosses the centerline up, the script alert will trigger with the “Go long…” message. When RSI crosses the centerline down, the script alert will trigger with the “Go short…” message.
- Because no argument is specified for the
freq
parameter in the alert() call, the default value ofalert.freq_once_per_bar
will be used, so the alert will only trigger the first time each of the alert() calls is executed during the realtime bar. - The message sent with the alert is composed of two parts: a constant string and then the result of the tostring() call which will include the value of RSI at the moment where the alert() call is executed by the script. An alert message for a cross up would look like: “Go long (RSI is 53.41)“.
- Because a script alert always triggers on any occurrence of a call to alert(), as long as the frequency used in the call allows for it, this particular script does not allow a script user to restrict his script alert to longs only, for example.
Note that:
- Contrary to an alertcondition() call which is always placed at column 0 (in the script’s global scope), the alert() call is placed in the local scope of an if branch so it only executes when our triggering condition is met. If an alert() call was placed in the script’s global scope at column 0, it would execute on all bars, which would likely not be the desired behavior.
- An alertcondition() could not accept the same string we use for our alert’s message because of its use of the tostring() call. alertcondition() messages must be constant strings.
Lastly, because alert() messages can be constructed dynamically at runtime, we could have used the following code to generate our alert events:
Using selective ‘alert()’ calls
When users create a script alert on alert() function calls, the alert will trigger on any call the script makes to the alert() function, provided its frequency constraints are met. If you want to allow your script’s users to select which alert() function call in your script will trigger a script alert, you will need to provide them with the means to indicate their preference in your script’s inputs, and code the appropriate logic in your script. This way, script users will be able to create multiple script alerts from a single script, each behaving differently as per the choices made in the script’s inputs prior to creating the alert in the charts UI.
Suppose, for our next example, that we want to provide the option of triggering alerts on only longs, only shorts, or both. You could code your script like this:
Note how:
- We create a compound condition that is met only when the user’s selection allows for an entry in that direction. A long entry on a crossover of the centerline only triggers the alert when long entries have been enabled in the script’s Inputs.
- We offer the user to indicate his repainting preference. When he does not allow the calculations to repaint, we wait until the bar’s confirmation to trigger the compound condition. This way, the alert and the marker only appear at the end of the realtime bar.
- If a user of this script wanted to create two distinct script alerts
from this script, i.e., one triggering only on longs, and one only
on shorts, then he would need to:
- Select only “Detect Longs” in the inputs and create a first script alert on the script.
- Select only “Detect Shorts” in the Inputs and create another script alert on the script.
In strategies
alert() function calls can be used in strategies the same way as in studies. While script alerts on strategies will use order fill events to trigger alerts when the broker emulator fills orders, alert() can be used advantageously to generate other alert events in strategies.
This strategy creates alert() function calls when RSI moves against the trade for three consecutive bars:
If a user created a script alert from this strategy and included both
order fill events and alert() function calls in his alert, the alert
would trigger whenever an order is executed, or when one of the
alert()
calls was executed by the script on the realtime bar’s closing
iteration, i.e., when
barstate.isrealtime
and
barstate.isconfirmed
are both true. The alert() function events in the script would only
trigger the alert when the realtime bar closes because
alert.freq_once_per_bar_close
is the argument used for the freq
parameter in the
alert()
calls.
Order fill events
When a script alert is created from a study, it can only trigger on alert() function calls. However, when a script alert is created from a strategy, the user can specify that order fill events also trigger the script alert. An order fill event is any event generated by the broker emulator which causes a simulated order to be executed. It is the equivalent of a trade order being filled by a broker/exchange. Orders are not necessarily executed when they are placed. In a strategy, the execution of orders can only be detected indirectly and after the fact, by analyzing changes in built-in variables such as strategy.opentrades or strategy.position_size. Script alerts configured on order fill events are thus useful in that they allow the triggering of alerts at the precise moment of an order’s execution, before a script’s logic can detect it.
Pine coders can customize the alert message sent when specific orders
are executed. While this is not a pre-requisite for order fill events
to trigger, custom alert messages can be useful because they allow
custom syntax to be included with alerts in order to route actual orders
to a third-party execution engine, for example. Specifying custom alert
messages for specific order fill events is done by means of the
alert_message
parameter in functions which can generate orders:
strategy.close(),
strategy.entry(),
strategy.exit()
and
strategy.order().
The argument used for the alert_message
parameter is a “series
string”, so it can be constructed dynamically using any variable
available to the script, as long as it is converted to string format.
Let’s look at a strategy where we use the alert_message
parameter in
both our
strategy.entry()
calls:
Note that:
- We use the
stop
parameter in our strategy.entry() calls, which creates stop-buy and stop-sell orders. This entails that buy orders will only execute once price is higher than the [high] on the bar where the order is placed, and sell orders will only execute once price is lower than the [low] on the bar where the order is placed. - The up/down arrows which we plot with plotchar() are plotted when orders are placed. Any number of bars may elapse before the order is actually executed, and in some cases the order will never be executed because price does not meet the required condition.
- Because we use the same
id
argument for all buy orders, any new buy order placed before a previous order’s condition is met will replace that order. The same applies to sell orders. - Variables included in the
alert_message
argument are evaluated when the order is executed, so when the alert triggers.
When the alert_message
parameter is used in a strategy’s
order-generating strategy.*()
function calls, script users must
include the {{strategy.order.alert_message}}
placeholder in the
“Create Alert” dialog box’s “Message” field when creating script
alerts on order fill events. This is required so the alert_message
argument used in the order-generating strategy.*()
function calls is
used in the message of alerts triggering on each order fill event.
When only using the {{strategy.order.alert_message}}
placeholder in
the “Message” field and the alert_message
parameter is present in
only some of the order-generating strategy.*()
function calls in your
strategy, an empty string will replace the placeholder in the message of
alerts triggered by any order-generating strategy.*()
function call
not using the alert_message
parameter.
While other placeholders can be used in the “Create Alert” dialog
box’s “Message” field by users creating alerts on order fill
events, they cannot be used in the argument of alert_message
.
‘alertcondition()’ events
The alertcondition() function allows programmers to create individual alertcondition events in Pine studies. One study may contain more than one alertcondition() call. Each call to alertcondition() in a script will create a corresponding alert selectable in the “Condition” dropdown menu of the “Create Alert” dialog box.
While the presence of alertcondition() calls in a Pine strategy script will not cause a compilation error, alerts cannot be created from them.
The alertcondition() function has the following signature:
condition
A “series bool” value (true
or false
) which determines when
the alert will trigger. It is a required argument. When the value is
true
the alert will trigger. When the value is false
the alert
will not trigger. Contrary to
alert()
function calls,
alertcondition()
calls must start at column zero of a line, so cannot be placed in
conditional blocks.
title
A “const string” optional argument that sets the name of the alert condition as it will appear in the “Create Alert” dialog box’s “Condition” field in the charts UI. If no argument is supplied, “Alert” will be used.
message
A “const string” optional argument that specifies the text message to display when the alert triggers. The text will appear in the “Message” field of the “Create Alert” dialog box, from where script users can then modify it when creating an alert. As this argument must be a “const string”, it must be known at compilation time and thus cannot vary bar to bar. It can, however, contain placeholders which will be replaced at runtime by dynamic values that may change bar to bar. See this page’s Placeholders section for a list.
The
alertcondition()
function does not include a freq
parameter. The frequency of
alertcondition() alerts is determined by users in the “Create Alert”
dialog box.
Using one condition
Here is an example of code creating alertcondition() events:
Because we have two alertcondition() calls in our script, two different alerts will be available in the “Create Alert” dialog box’s “Condition” field: “Long Alert” and “Short Alert”.
If we wanted to include the value of RSI when the cross occurs, we could
not simply add its value to the message
string using tostring(r)
, as
we could in an
alert()
call or in an alert_message
argument in a strategy. We can, however,
include it using a placeholder. This shows two alternatives:
Note that:
- The first line uses the
{{plot_0}}
placeholder, where the plot number corresponds to the order of the plot in the script. - The second line uses the
{{plot("[plot_title]")}}
type of placeholder, which must include thetitle
of the plot() call used in our script to plot RSI. Double quotes are used to wrap the plot’s title inside the{{plot("RSI")}}
placeholder. This requires that we use single quotes to wrap themessage
string. - Using one of these methods, we can include any numeric value that is plotted by our study, but as strings cannot be plotted, no string variable can be used.
Using compound conditions
If we want to offer script users the possiblity of creating a single alert from a study using multiple alertcondition() calls, we will need to provide options in the script’s inputs through which users will indicate the conditions they want to trigger their alert before creating it.
This script demonstrates one way to do it:
Note how the alertcondition() call is allowed to trigger on one of two conditions. Each condition can only trigger the alert if the user enables it in the script’s inputs before creating the alert.
Placeholders
These placeholders can be used in the message
argument of
alertcondition()
calls. They will be replaced with dynamic values when the alert
triggers. They are the only way to include dynamic values (values that
can vary bar to bar) in
alertcondition()
messages.
Note that users creating alertcondition() alerts from the “Create Alert” dialog box in the charts UI are also able to use these placeholders in the dialog box’s “Message” field.
{{exchange}}
{{interval}}
{{open}}
, {{high}}
, {{low}}
, {{close}}
, {{volume}}
{{plot_0}}
, {{plot_1}}
, […], {{plot_19}}
{{plot("[plot_title]")}}
This placeholder can be used when one needs to refer to a plot using
the title
argument used in a
plot()
call. Note that double quotation marks ("
) must be used inside
the placeholder to wrap the title
argument. This requires that a
single quotation mark ('
) be used to wrap the message
string:
{{ticker}}
{{time}}
yyyy-MM-ddTHH:mm:ssZ
, so for example: 2019-08-27T09:56:00Z
.
{{timenow}}
{{time}}
. The precision is to the nearest second, regardless of
the chart’s timeframe.
Avoiding repainting with alerts
The most common instances of repainting traders want to avoid with alerts are ones where they must prevent an alert from triggering at some point during the realtime bar when it would not have triggered at its close. This can happen when these conditions are met:
- The calculations used in the condition triggering the alert can vary
during the realtime bar. This will be the case with any calculation
using
high
,low
orclose
, for example, which includes almost all built-in indicators. It will also be the case with the result of any security() call using a higher timeframe than the chart’s, when the higher timeframe’s current bar has not closed yet. - The alert can trigger before the close of the realtime bar, so with any frequency other than “Once Per Bar Close”.
The simplest way to avoid this type of repainting is to configure the triggering frequency of alerts so they only trigger on the close of the realtime bar. There is no panacea; avoiding this type of repainting always entails waiting for confirmed information, which means the trader must sacrifice immediacy to achieve reliability.
Note that other types of repainting such as those documented in our Indicator repainting section may not be preventable by simply triggering alerts on the close of realtime bars.