Lua API: events

This page lists every event that events.on can follow, when it happens, and the fields of the table that the handler gets.

Subscribe a function to an event by its name, then load the scripts with tcli scripts to see an error:

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

A date is a text in ISO 8601 with the offset. A list is a Lua array. A choice (a state, a kind) is its name as a text. Plugins may add more events. How to use them is on Events.

Tilde and the scripts

Event	When	Fields
`startup`	After the scripts were loaded for the first time.	none
`shutdown`	Before the engine stops.	none
`scripts_reloaded`	After the scripts were loaded again by `scripting.reload`.	none
`script_error`	A script failed: a Lua error, a unit stopped for running too long, a script that could not run.	`source`, `message`
`job_failed`	A job ended with an error.	`name`, `kind` (`Queued`, `Recurring` or `Tracked`), `error`
`account_unavailable`	At start, a part of an account could not be created: no plugin for its protocol, or the plugin failed.	`account`, `component`, `reason`
`connection_state_changed`	A connection changed state.	`account`, `previous`, `state` (`Disconnected`, `Connecting`, `Connected` or `Faulted`)

Mail

Event	When	Fields
`mail_received`	A new message arrived in a folder.	`account`, `folder`, `id`, `from`, `from_name`, `subject`, `date`
`mail_sent`	An account sent a message.	`account`, `from`, `subject`, `to` (list), `cc` (list)
`mail_send_failed`	The transport could not send a message. A send that was cancelled raises nothing.	`account`, `from`, `subject`, `to`, `cc`, `reason`
`mail_flags_changed`	A message got new flags.	`account`, `folder`, `id`, `flags` (all of them now, such as `Seen, Flagged`)
`mail_expunged`	Messages marked as deleted were removed from a folder for good.	`account`, `folder`, `ids` (list)
`mail_cache_reset`	The cache of an account was emptied on purpose.	`account`
`pgp_keyring_changed`	The OpenPGP keyring changed through Tilde.	`reason` (`import`, `delete` or `refresh`)

from, to and cc hold the addresses only; from_name is the name of the sender.

Chat

Event	When	Fields
`chat_message`	A message was posted in a joined channel.	the message fields
`chat_mention`	A message that arrived mentions the account.	the message fields
`chat_message_sent`	The account sent a message, from here or, where the network copies it, from another device.	`account`, `channel`, `text`, `action`
`chat_error`	The network refused something after the fact, such as a message that was not delivered.	`account`, `channel`, `error`, `text`
`chat_user_kicked`	Somebody removed a user from a channel (a kick, or a ban on XMPP).	`account`, `channel`, `user`, `by`, `reason`
`chat_user_renamed`	A user in a channel took another nick; once for each shared channel.	`account`, `channel`, `old`, `new`
`chat_channel_joined`	The account entered a channel, also again by itself after a lost connection.	`account`, `channel`
`chat_channel_left`	The account is no longer in a channel: it left, or it was kicked out.	`account`, `channel`
`chat_invited`	Somebody invited the account to a channel it is not in.	`account`, `channel`, `by`
`chat_topic_changed`	The topic of a channel changed, or the network told it as the account entered.	`account`, `channel`, `topic`, `by`
`chat_message_edited`	Somebody corrected a message they wrote.	`account`, `replaced` (the id of the old message), `channel`, `sender`, `text`
`chat_message_retracted`	Somebody took back a message they wrote.	`account`, `channel`, `sender`, `id`
`chat_message_receipt`	The other side says a message of the account reached them or was read.	`account`, `channel`, `id`, `receipt` (`Delivered` or `Read`)
`chat_subscription_request`	Somebody asks to see the presence of the account.	`account`, `user`, `message`

The message fields of chat_message and chat_mention:

Field	Type	Meaning
`account`	text	The id of the account.
`id`	text	The id of the message.
`channel`	text	The id of the channel or of the conversation.
`channel_name`	text	The name of the channel.
`direct`	boolean	True for a conversation between two people.
`sender`	text	The name of the sender.
`text`	text	The text of the message.
`action`	boolean	True for an action (`/me`).
`notice`	boolean	True for a notice.

by is nil when the network does not say who did it. The list of the events is in BuiltInScriptEvents.cs.