Rules for chat

This page shows how to write a rule that reacts to the chat messages that arrive: it marks the conversation read, or calls a Lua function. Rules are written in init.lua, like the rules for mail.

A first rule

rules.chat("my-mentions",
  { mention = true, channel = "#dev" },
  { mark_read = true })

rules.chat(name, conditions, actions) has the same shape as rules.mail. This rule matches a message in #dev that calls you by your nick, and marks the conversation read.

A chat rule works on the messages that arrive while Tilde runs, in tt or in tcli watch. tcli watch shows a RuleApplied line for each message a rule fired on. tcli rules cannot apply a chat rule to a folder: it says so and exits with 2.

Conditions

Every condition that you give must hold. A text matches when the field contains it, ignoring case. A list of texts matches when any element does.

Key	Tests	Accepts
from	the name or the id of the sender	a string or a list
channel	the id or the name of the channel	a string or a list
account	the id of the account, ignoring case	a string or a list
text	the text of the message	a string or a list
direct	a direct message (true) or a message in a room (false)	a boolean
mention	a message that calls you by nick (true) or not (false)	a boolean

mention = true never matches a direct message: only the messages of a room are marked as mentions.

Actions

Key	Does
mark_read	marks the conversation read
stop	no rule after this one is looked at
run	calls a Lua function with the message

mark_read marks the conversation read in the list of what waits for you: its unread messages and mentions go away. Where the network keeps the read state (XMPP direct messages), the network is told. On IRC and in XMPP rooms the read state stays on this device.

A chat rule has no move and no flag. Rules are looked at in the order they were defined, and stop works as it does for mail: see Rules for mail.

Call a function

rules.chat("deploys", { channel = "#ops", text = "deploy" }, {
  run = function(msg)
    log.info("deploy talk in {Place}", msg.place)
  end,
})

The function gets a table with kind ("chat"), account, id, place (the channel), from, text (the text of the message), direct, mention and flags (empty for chat). It runs after the other steps, in the order of the rules, and the call is queued. A function that fails is reported as a script error and does not stop the next function or the next rule.

What a rule does not see

• A message that is replayed from the history of a room, when you enter it again, matches no rule: it is old news. Only XMPP rooms mark their history. An IRC bouncer that replays a buffer looks like live traffic.
• A mention arrives twice in Tilde, as a message and as a mention. The rules follow the message only, so a rule runs once.
• A mention that arrives as the correction of an XMPP message reaches only the mention event, so a chat rule does not see it.
• Rules also run on IRC notices. A run function that answers should check that it is not answering a bot.

When a rule is refused

rules.chat refuses a rule with an unknown key, a wrong type, a blank string, an empty list, or no condition or no action. The error names the rule and the key, never the value, and the rule is not registered. A rule name is unique across mail and chat: a chat rule with the name of a mail rule is refused, and one with the name of a chat rule replaces it. Run tcli scripts to see the error with its line.

The chat accounts are on Chat accounts, and the list of unread messages and mentions that Tilde keeps is on What waits for me.