Sequence Steps Hook

Use this hook to add a new kind of step to the sequence editor.

How it works

1. Your manifest declares a step.
2. When the plugin is on in a channel, the step appears in Add Step in that channel’s sequences.
3. The admin adds it and fills in its settings.
4. When a person reaches the step, Broadcast calls your function.

Full example: stop if tagged

This step ends a person’s run through the sequence if they have a certain tag.

manifest.json:

{
  "id": "local.stop-if-tagged",
  "name": "Stop if tagged",
  "version": "1.0.0",
  "requires": { "broadcast": ">=3.0.0 <4.0.0", "pluginApi": "1" },
  "permissions": {
    "subscribers": "read"
  },
  "hooks": {
    "sequenceSteps": [
      {
        "name": "stop_if_tagged",
        "label": "Stop if tagged",
        "settings": {
          "tag": { "type": "string", "label": "Stop for people with this tag" }
        }
      }
    ]
  }
}

dist/main.js:

export default definePlugin({
  sequenceSteps: {
    async stop_if_tagged({ config, subscriber_id }, ctx) {
      const subscriber = await ctx.broadcast.subscribers.get(subscriber_id);
      const hasTag = subscriber.tags.includes(config.tag);

      // continue: false ends this person's run through the sequence.
      return { continue: !hasTag };
    },
  },
});

What you get

{
  "name": "stop_if_tagged",
  "config": { "tag": "customer" },
  "subscriber_id": 12,
  "subscriber_email": "ada@example.com",
  "sequence_id": 3,
  "step_id": 41
}

config holds the values the admin typed in this step. Two copies of the step in a sequence can have different values.

What you return

Common mistakes

You expect numbers in config. The step form shows a text box for each setting, so each value is a string. Use Number(config.days).

You forget that a retry can repeat your work. If your step posts a message and then throws, the retry posts it again. Do the risky work last.

You rename a step. A step in a sequence stores its name. If a new version drops that name, the step is skipped. Keep old names, and add new ones.

You expect the step to wait for a plugin that is off. If the plugin is off or removed, Broadcast skips the step and the person moves on.