Alert keys and options

Alerts that say something is the short version. This page is the rulebook.

Two ways to make an alert#

alert.when#

alert.when(condition, name, message = ..., on = "rises")

indicator "Two conditions"
    edition = 1
    display = price

let fast = tech.ema(close, 12)
let slow = tech.ema(close, 26)
alert.when(
    tech.crosses_above(fast, slow),
    "Bullish cross",
    message = "{{ticker}} bullish cross at {{close}}",
)
alert.when(
    close > tech.highest(high, 50)[1],
    "New 50-bar high",
    message = "{{ticker}} made a new 50-bar high",
    on = "level",
)
plot(fast, name = "Fast")
plot(slow, name = "Slow")

• name is how the condition is listed. It also makes the condition's id; use key = "name" to choose one and was = "old" after a rename, as for inputs.
• on = "rises" (the default) rings on the first bar where the condition holds and then waits for it to turn false and true again. on = "level" rings on every bar where it holds.
• The message is a plain text, the same for every ring, and may use the placeholders below. A message built with an f-text is not an error, but it is not kept: the condition then has no message, so write the text out.

Placeholders#

The server fills these in the message, in alert.when and in a plain text given to alert.send():

{{ticker}} {{exchange}} {{interval}} {{open}} {{high}} {{low}} {{close}} {{volume}} {{price}} {{time}} {{clock.now}} {{alert_name}} {{script_message}} and {{plot("Name")}}, which is the value of the plot with that name on the bar. A placeholder that is not on this list stays as written.

alert.send#

alert.send(message, key = ..., once = ..., cooldown = ...). The message is a text, usually an f-text built from the bar's values.

indicator "Alert with a message"
    edition = 1
    display = price

let top = tech.highest(high, 20)[1]
if close > top
    alert.send(
        f"{symbol.ticker} closed above the 20-bar high {top:price}",
        key = "breakout",
        once = "bar_close",
    )
plot(top, name = "20-bar high")

key#

Every alert.send() call has a key that names it. If you give none, the key is made from the place of the call in the script. A key you write is cleaned to the ASCII letters A-Z a-z, the digits and _ . : - (any other character becomes _), and it may have at most 28 characters: a longer key is replaced by a generated one, so keep it short. A key with a character that is not ASCII, such as one in Persian or Arabic letters, keeps its cleaned form (at most its first 20 characters), then . and six characters made from the whole key, so two such keys never become the same key and the same key is the same from run to run; the server accepts Latin keys only, so the letters themselves are not kept. A key in Latin letters stays readable. Two calls with the same key are one key and share their once and cooldown; two calls with different keys ring separately, even on the same bar.

indicator "Two keys"
    edition = 1
    display = price

if close > open
    alert.send("up bar", key = "up", once = "bar_close")
if close < open
    alert.send("down bar", key = "down", once = "bar_close")
plot(close)

Write a key you can recognise. The key is how a message is filed and how repeated rings are told apart.

once#

once says when a key may ring again.

The message is the only argument given by place; once and cooldown are written by name. Any other value for once is an error:

indicator "An unknown once"
    edition = 1

if close > open
    alert.send("up", key = "up", once = "sometimes")
plot(close)

cooldown#

cooldown = n keeps a key silent until n bars have passed since it rang: with cooldown = 12 it can ring on bar 0, then not before bar 12. It adds to once: both must allow the ring.

key, once and cooldown must be written in the script, as a text or a number. A value read from an input or computed on the way is refused.

Messages with JSON#

Webhooks usually carry a JSON body, which is full of braces. In a plain text the braces are just characters, and placeholders still work:

indicator "A JSON body"
    edition = 1
    display = price

if close > open
    alert.send(
        '{"symbol":"{{ticker}}","side":"buy","price":' + text.of(close) + "}",
        key = "hook",
        once = "bar_close",
    )
plot(close)

In an f-text a literal brace is written twice, so a JSON body built from values is:

indicator "A JSON body from values"
    edition = 1
    display = price

if close > open
    alert.send(
        f'{{"symbol":"{symbol.ticker}","price":{close:.2f}}}',
        key = "hook",
        once = "bar_close",
    )
plot(close)

A helper that builds JSON from a record, alert.send(json(...)), is not available yet.

Limits#

• A script may ring at most 20 times on one bar and 5,000 times in one run; the chart keeps only the newest records of a long run.
• A message is cut at 4,096 characters, with a warning.
• A key has at most 28 characters; a longer one is replaced by a generated key.

Where the rings go#

In this release nothing is delivered: an alert on your own script cannot be created (see the warning at the top). In the message of an alert, the placeholder {{script_message}} stands for the text of the alert.send() call.

See also: Alerts that say something, Text and number formatting, Limits and budgets.