Alarms

Decide what follows when a member of staff, a whisper, the character's name, a chat module event or any game message reaches one of your bots: the events alarms follow, the default rules, writing your own on the Alarms page with conditions on the event, every reaction, the notifications in Asteroboard or on any web service through a plain HTTP request, and the last alarms.

An alarm follows what happens to your bots: a member of staff speaking to one, warning it, muting it or standing on its map, a player whispering it, its character's name said in a channel, the chat module's events, and any message the game sends it that you choose to hook. Its rules say what follows: a notification in Asteroboard or on any web service, the chat paused, a line said, a package played, the script stopped, a game message sent, the bot disconnected. The rules are one list for the whole Asterobot, and each rule can watch every bot or some.

Alarms work whether the chat module is on or off: they read the same chat the Console shows.

What alarms follow

A member of staff is recognised as the game client does: a line the server marks as an administrator's or says in the staff channel, a warning window, a mute, and on the map, a character whose account role isn't a player's.

Each event says something: who and what, as fields. A rule's conditions and its reactions' texts read them.

The default rules

Until you change them, two rules apply:

The Alarms page shows them with The default rules: saved at the first change: the first time you save, they're written to a file you then own.

The Alarms page

Open Alarms in Asteroboard's menu. The page shows the rules' form on the left and their JSON on the right, both live, as in the chat profile editor. Save sends the rules to Asterobot, which checks them and names the field at fault of anything it refuses; Discard puts back the rules as saved. Leaving the page with unsaved changes asks first.

Add a rule adds one at the end. The rules apply in order; the arrows move one up or down.

When several rules take the same event, each one fires, side by side, and a reaction two rules ask for the same event, with the same settings, is done once. One rule that repeats a reaction, a message, a wait and the same message again, does it each time. A Wait holds back only the rest of its own rule. A rule you switch off or delete during its Wait does nothing more after it, and the bot's console says so.

Match

Add a field adds a condition on one of the event's fields. Every one must hold for the rule to fire; for an "or", write two rules.

A field the event doesn't have fails the condition. For example, a rule taking Staff with reason is mute fires on a mute only.

Game messages

A rule can take any message the game sends the bot: type game: and the message's name in Events, such as game:CharacterLevelUpEvent. Each time the game sends the bot that message, the rule takes it, with the message's fields.

• Names: a message's name and its fields' are the readable ones of the Dofus protocol reference, with underscores: new_level. The bot's Network tool shows which messages the game really sends, with real values. A name the protocol doesn't have is refused when you save.
• Fields: a nested field is written with dots, a list's item with its index: author.name, parameters.0. json is the whole message, as JSON.
• Cost: a message no rule names costs nothing. Only the messages your rules name are read into fields.
• Direction: only what the game sends the bot. The bot's own requests aren't followed.

For example, to be told when a character reaches level 200: Events game:CharacterLevelUpEvent, Match new_level is above 199, Reactions Notify.

Some fields still have short scrambled names, such as galg: Asterobot doesn't know what they hold yet, and their names can change with a game update, so don't build a rule on them.

Reactions

A line to say or whisper is a message template, and reads the alarm's variables besides the character's own: each field of the event, {sender}, {text}, {who}, {channel}, {minutes}..., and {bot}, {character}, {rule}, {event}. The character's own come first: in a line, {name}, {server} and {time} are the character's name, server and time of day. For example {Sorry|Hi} {sender}, I'm busy right now. An alarm's line goes through the guard like any other, but a pause doesn't hold it back.

A console line and a game message's texts read the alarm's variables only: each field of the event, and {bot}, {character}, {server}, {rule}, {event}, and {time}, the event's date and time, such as 2026-10-28T14:05:09+01:00. A variable the event doesn't have is empty there, and braces that name no variable stay as they are.

A reaction that can't be done writes why in the bot's console, Alarm Staff: play failed: no package "@me:hide" is installed, shows in Last alarms, and the rule goes on.

Notifications

A Notify reaction with the Asteroboard destination shows a notification in every open Asteroboard, whichever page is open: "Bot-Name: a member of staff", "Bot-Name: Player-Name whispers", "Bot-Name: Player-Name says the character's name", "Bot-Name: too much spam, the chat waits 5 minutes", and for a trigger's, a script's or a game message's, the event's name, with what was said. A member of staff's stays until you close it. Open goes to the bot's page.

Destinations

Besides Asteroboard, a Notify can reach any web service: a chat app, a push service on your phone, a server of your own. Each destination is a plain HTTP request you write. Add a destination, under the rules on the Alarms page, adds one.

The URL, the headers' values and the body read the alarm's variables, as a console line does: {bot}, {character}, {server}, {rule}, {event}, {time}, and each field of the event, {sender}, {text}, {who}... Each value is escaped for where it lands, so a quote in a whisper never breaks your request:

• In the URL: URL-encoded. Seller A becomes Seller%20A.
• In a JSON body: JSON-escaped, to write between quotes: "text": "{text}". {json}, a game message as JSON, goes in as it is: "message": {json}, and as null for an event that isn't a game message.
• In a form body, with the header Content-Type: application/x-www-form-urlencoded: URL-encoded.
• In a header: on one line.

The body is sent with your Content-Type header when you give one. Without it, a body that is a JSON object or array, its variables aside, is sent as application/json, and anything else as text/plain.

Test

Test sends the destination once, as it stands on the page, saved or not, with a sample event: the bot Asterobot, the event test, the text "This is a test from Asterobot". It shows what the service answered: The service took it with its status, or The service didn't take it with why, such as the service answered 401 Unauthorized and the start of its reply, or no answer within 10 s.

Sending

Each destination's requests leave one at a time, in order, and a service gets 10 seconds to answer. When it doesn't answer, says it has too many requests (429) or has a problem of its own (5xx), the request is sent again after 2, 10 and 30 seconds. Any other answer is final, since the request itself is wrong. A request that fails for good writes why in the bot's console: Alarm Staff: My phone didn't take the request: the service answered 401 Unauthorized.

At most 100 requests wait for one destination. Past that, the Notify fails for that destination, and says so in Last alarms. A request still waiting for its turn after 10 minutes, while the service is down, is dropped unsent, so that the alarms you get when it's back are fresh ones; the bot's console says so.

A URL or a token stays in alarms.json, on your computer. Asterobot never writes them in a console line.

Examples

Each service documents the request it takes: its URL, and the names it gives the fields of its body. Most take one of these three shapes.

A JSON webhook, the URL the app gave you, its body a JSON object:

A push service taking the message as plain text, its title in a header:

A service taking everything in its URL, and a token in a header:

Last alarms

Under the rules and destinations, Last alarms lists the last 100 alarms fired, the latest first, until Asterobot restarts: when, the event and its bot, character and server, its fields, the rule, and each reaction, Done or with the reason it couldn't be, one hover away. A rule with a Wait shows once all its reactions are done. A Notify is Done once its requests are on their way: one that fails later writes why in the bot's console.

The alarms file

The rules are the file alarms.json in Asterobot's data folder (Files and folders). What you save on the Alarms page applies at once; a change you make to the file by hand applies the next time Asterobot starts.

{
  "version": 1,
  "destinations": [
    {
      "name": "My phone",
      "method": "POST",
      "url": "https://push.example.com/my-topic",
      "headers": { "Title": "{bot}: {event}" },
      "body": "{who}{sender} {text}"
    }
  ],
  "rules": [
    { "name": "Staff", "events": ["staff"], "do": [ { "pauseChat": 1800 }, { "notify": [] } ] },
    { "name": "Messages", "events": ["whisper", "mention"], "do": [ { "notify": ["Asteroboard"] } ] },
    {
      "name": "Muted",
      "events": ["staff"],
      "match": { "reason": "mute" },
      "do": [ { "stopScript": {} }, { "wait": 60 }, { "disconnect": { "reconnectAfter": 3600 } } ]
    },
    {
      "name": "Level 200",
      "events": ["game:CharacterLevelUpEvent"],
      "match": { "new_level": { "above": 199 } },
      "do": [ { "notify": ["Asteroboard"] }, { "log": "{character} reached level {new_level}" } ]
    },
    {
      "name": "Answer whispers",
      "events": ["whisper"],
      "bots": ["Farmer-1", "Farmer-2"],
      "every": 600,
      "do": [ { "whisper": { "text": "{Sorry|Hi} {sender}, I'm busy right now" } } ]
    }
  ]
}

A file that can't be used, such as one you edited by hand with a mistake, shows The file can't be used: the default rules apply with the field at fault, and the default rules apply until you fix it.

Lire cette page en français