Events

events.on(name, fn) runs a function each time something happens in Tilde: a mail arrives, a chat message comes, a job fails, the scripts load. This page shows a first handler, says how a handler runs and lists the events by name. The fields of each event are in the Lua events reference.

A first handler

events.on("startup", function()
  log.info("scripts loaded")
end)

events.on("mail_received", function(e)
  log.info("new mail from {From} in {Folder}: {Subject}", e.from, e.folder, e.subject)
end)

events.on("chat_mention", function(e)
  log.info("{Sender} mentioned me in {Channel}", e.sender, e.channel)
end)

events.on("job_failed", function(e)
  log.warning("job {Name} failed: {Error}", e.name, e.error)
end)

events.on("script_error", function(e)
  log.warning("{Source} failed: {Message}", e.source, e.message)
end)

tcli scripts loads this and prints scripts loaded, because startup is the only event it raises: it connects no account. The mail and chat events need the accounts, so they reach a handler in tt and in tcli watch. log.info goes to the log file when log_to_file is on (see Logging and jobs).

How a handler runs

• The handler gets one table with the fields of the event, for example e.subject. A field that has no value is left out, so it is nil. A date is a text in ISO 8601, and a list is a table that starts at 1. The events startup, shutdown and scripts_reloaded have no table.
• Several handlers for one event run in the order you added them, one at a time, and one at a time with all other Lua work.
• A handler cannot change or stop what happened. It runs after the event.
• A handler that fails is reported as a script_error, and the next handler still runs.
• An unknown event name is an error, and the message lists the known names.
• A reload of the scripts drops every handler. scripts_reloaded then goes to the handlers the new scripts added. startup goes only to the first load, and shutdown to the handlers when Tilde stops, for up to 5 seconds.
• Scripts load after the accounts start. An event that was published before that, such as the first connection_state_changed of an account or an account_unavailable, does not reach a handler.

The events

Group	Events
Scripts	startup, shutdown, scripts_reloaded, script_error (fields source and message)
Mail	mail_received, mail_sent, mail_send_failed, mail_flags_changed, mail_expunged, mail_cache_reset
Accounts and jobs	account_unavailable, connection_state_changed, job_failed, pgp_keyring_changed
Chat messages	chat_message, chat_mention, chat_message_sent, chat_message_edited, chat_message_retracted, chat_message_receipt
Chat rooms and people	chat_channel_joined, chat_channel_left, chat_invited, chat_topic_changed, chat_user_kicked, chat_user_renamed, chat_subscription_request, chat_error

The source of a script_error says what failed: init.lua, keybind.lua, the name of an event, command NAME, jobs.every NAME, jobs.enqueue #N or timers.after #N. A failure inside a script_error handler does not raise it again.

A C# plugin can add events with their own names: see Commands, Lua modules and events.

Take care with loops

A handler that does what it listens for can loop. A job_failed handler that queues a job which fails raises job_failed again, and again. Tilde does not break such a loop, so count the tries or stop after a few.