> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/build-a-custom-automation-plugin.md).

# Build a custom automation plugin

Extend automations with a custom action.

## Your goal

Add a step to an automation that the standard nodes cannot do - trigger an action in one of your systems.

## Expected outcome

A deployed plugin your users can attach to the corresponding node in an automation.

## Which plugin type you need

| You want to                                        | Plugin type                                  | Node it attaches to  |
| -------------------------------------------------- | -------------------------------------------- | -------------------- |
| Trigger an action that is not in the standard list | **Custom action** (`SCENARIO_CUSTOM_ACTION`) | A custom action node |

A custom action plugin follows the creation and deployment procedure in [Build a custom feed plugin](/setup-and-monitor/extend-the-platform/build-a-custom-feed-plugin.md#create-and-deploy), and must read its [instance](/setup-and-monitor/extend-the-platform/plugin-architecture.md#instances) to adapt to its configuration.

## Custom action

A **custom action plugin** can be associated with a custom action node in an automation, letting you trigger an action from within a scenario. Use it for actions not available in the standard list.

### The one endpoint

```
POST myworker/v1/scenario_custom_actions
```

Called any time a UserPoint goes through a custom action node.

| Request field      | Type   | Description                                                                                |
| ------------------ | ------ | ------------------------------------------------------------------------------------------ |
| `user_point_id`    | String | The ID of the UserPoint.                                                                   |
| `custom_action_id` | String | The ID of the custom action plugin instance. **Used to retrieve the instance properties.** |

{% tabs %}
{% tab title="Success" %}

```json
{ "status": "ok" }
```

{% endtab %}

{% tab title="Error" %}

```json
{
  "status": "error",
  "message": "..."
}
```

{% endtab %}
{% endtabs %}

### Read the instance

```
GET https://api.mediarithmics.com/v1/scenario_custom_actions/:id
```

Using `custom_action_id` from the incoming request. The response includes the instance's `name`, `organisation_id`, `group_id`, `artifact_id`, `creation_ts`, `created_by`, `version_id`, and `version_value`.

{% hint style="info" %}
The request gives you a `user_point_id` and nothing else about the user. If your action needs profile or activity data, fetch it - see [Server-side events](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/server-side-events.md#the-userpoint-selector) for the selector syntax.
{% endhint %}

## Common concerns

| Concern               | Guidance                                                                                                                                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **External calls**    | Every host you call must be declared as an external service **and enabled** by mediarithmics.                                                                                                                            |
| **Rate limits**       | Configure a [throttling](/setup-and-monitor/extend-the-platform/plugin-architecture.md#controlling-how-hard-a-plugin-is-called) on the version if the partner has API limits.                                            |
| **Automation limits** | Automations have their own default limits - scenarios, nodes, wait nodes, UserPoints woken per hour. See [Platform limits](/setup-and-monitor/plan-and-integrate/set-up-the-environment/platform-limits.md).             |
| **Logs**              | Add context to every log line so you can filter to one instance, and keep the volume low. See [Build an activity analyzer](/setup-and-monitor/extend-the-platform/build-an-activity-analyzer.md#watch-it-in-production). |

## Verify

* A test UserPoint going through the node reaches your plugin.
* The plugin reads its instance properties rather than a hard-coded configuration.

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Plugin architecture</strong></td><td>Instances, properties, and throttlings.</td><td><a href="/setup-and-monitor/extend-the-platform/plugin-architecture.md">Plugin architecture</a></td></tr><tr><td><strong>Platform limits</strong></td><td>The automation ceilings your plugin runs inside.</td><td><a href="/setup-and-monitor/plan-and-integrate/set-up-the-environment/platform-limits.md">Platform limits</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/extend-the-platform/build-a-custom-automation-plugin.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.