plugin_install

Install a JavaScript plugin and load it straight away. You can send the plugin’s manifest and code in the request, or give a git URL for the server to clone. See plugins for how plugins work and what main.js can do.

Request

Inline install:

{
  "cmd": "plugin_install",
  "name": "hello",
  "manifest": {
    "description": "Say hello and answer !ping",
    "version": "0.1.0",
    "slash": [
      {
        "name": "hello",
        "description": "Say hello"
      }
    ],
    "events": ["message_new"]
  },
  "main": "function onSlash(p) { return {response: \"hello, \" + p.user.username + \"!\"}; }"
}

Install from git:

{
  "cmd": "plugin_install",
  "name": "hello",
  "git_url": "https://github.com/example/originchats-hello.git"
}

Field	Type	Required	Description
name	string	Yes	Plugin name and folder name. 1 to 64 letters, digits, _, or -. Must not be installed already.
manifest	object	For inline installs	The plugin’s plugin.json. See the manifest fields below.
main	string	For inline installs	The plugin’s main.js source. Must not be blank; at most 524,288 characters (512 KiB).
git_url	string	For git installs	Repository to clone. Must start with https:// or git@. If present, manifest and main are ignored.

Manifest fields:

Field	Type	Required	Description
description	string	Yes	Short description. Can’t be blank.
version	string	Yes	Version label, such as 0.1.0. Can’t be blank.
slash	array	No	Slash command definitions, at most 16, with unique names. They use the same fields as slash_register.
events	array of strings	No	Commands the plugin’s onEvent runs before, such as message_new. At most 32.
enabled	boolean	No	Defaults to true. false installs the plugin without loading it.
name	string	Git only	Git: required and must equal the request’s name. Inline: ignored and set to the request’s name.

How each install works:

• Inline. The server checks the manifest and source, then writes plugin.json and main.js to plugins/<name>/ in the database directory. If a check fails, nothing is written.
• Git. The server runs a shallow git clone into plugins/<name>/ in the database directory, with a two-minute limit. The repository must have plugin.json at its root whose name matches. If the clone fails or that check fails, the folder is removed.

Afterwards you can update a git plugin by running git pull in its folder and then plugin_reload.

Response

{
  "cmd": "plugin_install",
  "val": true,
  "plugin": "hello"
}

When the plugin loads and declares slash commands, every authenticated connection receives a slash_add event listing them:

{
  "cmd": "slash_add",
  "commands": [
    {
      "name": "hello",
      "description": "Say hello",
      "options": [],
      "whitelistRoles": null,
      "blacklistRoles": null,
      "ephemeral": false,
      "registeredBy": "plugin:hello"
    }
  ]
}

The install is recorded in the audit log.

Caution

A git install only checks the manifest name before keeping the folder. The full manifest and main.js are checked when the plugin loads. If that fails you get an error, but the plugin stays installed and unloaded. Fix the files and run plugin_reload, or remove it with plugin_uninstall.

Permissions

Requires manage_server. It is blocked while you are timed out.

Errors

val	When
Invalid plugin name	name has characters other than letters, digits, _, and -.
Provide manifest and main, or git_url	Neither an inline plugin nor git_url was sent.
Plugin '<name>' is already installed	A folder with that name already exists.
Manifest description must be a non-empty string	description is missing or blank.
Manifest version must be a non-empty string	version is missing or blank.
Manifest enabled must be a boolean	enabled is set to something other than a boolean.
A plugin may register at most 16 slash commands	slash has more than 16 entries.
Invalid slash command: <detail>	A slash entry fails the definition rules, for example Invalid slash command: /hello has invalid options.
Duplicate slash command '<name>'	Two slash entries share a name.
A plugin may subscribe to at most 32 events	events has more than 32 entries.
Plugin events must be non-empty command names	An events entry isn’t a non-blank string.
Plugin main.js must not be empty	main is blank, or a cloned repository has no main.js.
Plugin main.js exceeds the 512 KiB limit	The source is too long.
Git URL must start with https:// or git@	git_url uses another scheme.
Git clone failed or plugin.json is missing	The clone failed or timed out, or has no plugin.json.
Cloned plugin has an invalid manifest	The cloned plugin.json can’t be parsed or its name doesn’t match.
Unable to create plugin directory	The server couldn’t create the folder.
Unable to save plugin manifest	The server couldn’t write plugin.json.
Unable to save plugin source	The server couldn’t write main.js.
Validation message	A field has the wrong type, for example name: Expected length at most 64.

See also

• Plugins
• plugin_reload
• plugin_uninstall