# Plugins

> What a Broadcast plugin is, what it can and cannot do, and how the pieces fit together. Start here if you have never written a plugin.

Source: https://sendbroadcast.net/docs/plugins

> Coming in Broadcast 3.0. Until then, this page applies only to the Upcoming (edge) build.

A plugin adds a feature to your Broadcast server. You write it in JavaScript, and Broadcast runs it for you.

Here are some things a plugin can do:

- Post a message to Slack when someone subscribes.
- Add a tag to each new subscriber.
- Add a poll to an email, and count the answers.
- Run a referral program.
- Add a step such as "Post to Slack" to your sequences.
- Show a report page inside Broadcast.

You do not need to know Ruby or how Broadcast works inside. If you can write a JavaScript function, you can write a plugin. This section assumes you have never written a plugin, used a sandbox or read a manifest. It explains each of those words when it needs them.

Tip

**New here?** Read this page, then follow [Your First Plugin](https://sendbroadcast.net/docs/plugins-first-plugin). It takes about 20 minutes and you end with a plugin that works.

## The four words you need

**Plugin.** A folder of files, packed into one file that ends in `.broadcast-plugin`.

**Manifest.** A file named `manifest.json`. It is the label on the box. It says what the plugin is called, what it wants to listen to and what it wants to be allowed to do. Broadcast reads it before any code runs.

**Hook.** A place where Broadcast calls your code. For example, the `onEvent` hook runs when something happens, such as a new signup. You write a function, and Broadcast calls it at the right time.

**Sandbox.** A closed room for your code. Your plugin runs in its own process, away from Broadcast. It cannot see the database, the disk or the server settings. It can only talk to Broadcast through one object, named `ctx`. Everything it asks for is checked.

## How the pieces fit

This picture shows what happens when a person subscribes and a plugin adds a tag:

```text
 Your Broadcast server
+------------------------------------------------------------+
|                                                            |
|  Broadcast app                    Plugin sandbox           |
|  +----------------------+         +---------------------+  |
|  | 1. Ada subscribes.   |         |                     |  |
|  |                      | event   | 2. Your onEvent     |  |
|  |    Is a plugin on    | ------> |    function runs.   |  |
|  |    in this channel?  |         |                     |  |
|  |                      |  ctx    | 3. It asks: add the |  |
|  | 4. Is this plugin    | <------ |    tag "new" to     |  |
|  |    allowed to do     |         |    subscriber 12.   |  |
|  |    that? Yes.        |         |                     |  |
|  |    Add the tag.      | ------> | 5. It gets the      |  |
|  |                      | answer  |    answer.          |  |
|  +----------+-----------+         +----------+----------+  |
|             |                                |             |
|        Your database                   Network gate        |
|      (no plugin can reach it)     (declared hosts only)    |
+------------------------------------------------------------+
```

There are three things to see here:

1. Broadcast calls your code. Your code does not run all the time.
2. Your code never touches the database. It asks through `ctx`, and Broadcast does the work.
3. Your code can reach the internet only through a gate. The gate lets it reach only the hosts that the manifest names.

## What a plugin can do

| A plugin can... | With... |
|---|---|
| Run code when something happens | The [events hook](https://sendbroadcast.net/docs/plugins-hook-events) |
| Run code on a timetable | The [schedules hook](https://sendbroadcast.net/docs/plugins-hook-schedules) |
| Add a step to the sequence editor | The [sequence steps hook](https://sendbroadcast.net/docs/plugins-hook-sequence-steps) |
| Add values to emails | [Merge tags](https://sendbroadcast.net/docs/plugins-hook-merge-tags) and [Liquid filters](https://sendbroadcast.net/docs/plugins-hook-liquid-filters) |
| Change a broadcast for each person, just before it is sent | The [before send hook](https://sendbroadcast.net/docs/plugins-hook-before-send) |
| Let a person click a link in an email and run plugin code | [Public actions](https://sendbroadcast.net/docs/plugins-hook-public-actions) |
| Add its own API address | The [API endpoints hook](https://sendbroadcast.net/docs/plugins-hook-api-endpoints) |
| Give the AI assistant a new tool | The [AI tools hook](https://sendbroadcast.net/docs/plugins-hook-ai-tools) |
| Show its own pages inside Broadcast | [Plugin Pages](https://sendbroadcast.net/docs/plugins-pages) |
| Keep its own data | [Storage](https://sendbroadcast.net/docs/plugins-concepts#storage) |
| Add rules to the segment editor | [Plugin Events and Segment Rules](https://sendbroadcast.net/docs/plugins-segment-rules) |

## What a plugin can never do

No permission unlocks these things. They are not possible for any plugin, and this list is the same for code you trust and code you do not:

- Run SQL or read the database.
- Read files, or read server settings and environment variables.
- Start other programs.
- Resubscribe a person, or remove a suppression.
- Skip double opt-in.
- Change who an email goes to, or remove the unsubscribe link.
- Change a topic, because a topic is a subscriber's consent.
- Load more code while it runs. There is no `eval`, and no `import` from the network.

## Who does what

A plugin passes through two kinds of people, and they can be the same person.

The **author** writes the code. If you read this section, that is you.

The **admin** decides what runs. An admin is a user with sudo access. The admin reads the permissions and the code, clicks **Deploy**, and then turns the plugin on in each channel that needs it.

Nothing runs until both of those steps are done. Plugins are installed once on the server, and they are turned on for each channel. So the same plugin can be on in one channel and off in another, with different settings.

Note

Plugins are for self-hosted Broadcast servers, and a server needs the plugin runtime. Go to **Application > Plugins** to check it. The page says **The plugin runtime is running** when it is ready.

## Where to go next

1. [Your First Plugin](https://sendbroadcast.net/docs/plugins-first-plugin): build a plugin from an empty folder.
2. [Plugin Core Concepts](https://sendbroadcast.net/docs/plugins-concepts): learn the manifest, hooks, `ctx`, permissions, settings and storage.
3. [Plugin Hooks](https://sendbroadcast.net/docs/plugins-hooks): pick the hook for your idea.
4. [Build a Poll](https://sendbroadcast.net/docs/plugins-build-a-poll) and [Build a Referral Program](https://sendbroadcast.net/docs/plugins-build-a-referral-program): see how two complete plugins are built.
5. [Plugin Reference](https://sendbroadcast.net/docs/plugins-reference): look up every field, function, permission and limit.