# Automation rules

Register your own automation rules to automate Bitrix24. An automation rule is an external handler that appears both in the automation designer and in the business process designer. It is invoked when automation runs: it receives input parameters, runs its logic on the application side, and returns a result. Bitrix24 recommends automation rules over activities.

Automation rules can be read, registered, updated, and deleted only with an authorization key `vibe_app_…` — an API key `vibe_api_…` cannot be used for these methods. Only a Bitrix24 account administrator can manage automation rules.

Bitrix24 API: `bizproc.robot.*`
Scope: `bizproc`

## Operations

- [Register an automation rule](./bizproc-robots/create.md) — `POST /v1/bizproc-robots`
- [Automation rule list](./bizproc-robots/list.md) — `GET /v1/bizproc-robots`
- [Update an automation rule](./bizproc-robots/update.md) — `PATCH /v1/bizproc-robots/:code`
- [Delete an automation rule](./bizproc-robots/delete.md) — `DELETE /v1/bizproc-robots/:code`
- [Automation rule fields](./bizproc-robots/fields.md) — `GET /v1/bizproc-robots/fields`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `code` | string | Unique automation rule code. Serves as the identifier in the update and delete paths |
| `handler` | string | Automation rule handler URL. The domain must match the application domain |
| `name` | string \| object | Automation rule name. A string or a localized object |
| `properties` | object | Automation rule input parameters — fields that are filled in when the automation rule is configured |
| `returnProperties` | object | Automation rule output parameters — values the rule returns |
| `documentType` | array | Document type the rule applies to — module, object, type. See the table below |
| `authUserId` | number | The user whose token is passed to the application on call. List: `GET /v1/users` |

The full field list — [Automation rule fields](./bizproc-robots/fields.md). All of them are passed on [registration](./bizproc-robots/create.md) and [update](./bizproc-robots/update.md). The automation rule identifier is the string `code`, not a numeric `id`.
### Document types

The `documentType` value is an array of three strings `[module, object, type]`. An automation rule applies only to CRM entities — the set is narrower than for [activities](/docs/entities/bizproc-activities) and [templates](/docs/entities/bizproc-templates).

| Entity | `documentType` |
|----------|----------------|
| Leads | `["crm", "CCrmDocumentLead", "LEAD"]` |
| Deals | `["crm", "CCrmDocumentDeal", "DEAL"]` |
| Quotes | `["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Quote", "QUOTE"]` |
| Invoices | `["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\SmartInvoice", "SMART_INVOICE"]` |
| Smart processes | `["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Dynamic", "DYNAMIC_XXX"]` |

## What to know before you start

1. **An authorization key `vibe_app_…` is required, not an API key `vibe_api_…`.** All five operations require an application context. An API key returns `403 OAUTH_REQUIRED` on any of them. Send the authorization key together with the `Authorization: Bearer <session>` header — see [Keys and authorization](/docs/keys-auth). The session token is issued by OAuth authorization, is valid for 24 hours, and cannot be renewed — after it expires calls return `401 INVALID_SESSION` and you need to authorize again. How to obtain and pass the token — [Passing the key](/docs/keys-auth#passing-the-key).
2. **Administrator only.** Automation rules can be managed only by a user with Bitrix24 account administrator rights. For all other users, Bitrix24 returns an access error.
3. **The identifier is the string `code`.** The update and delete paths take the `code` (string), not a numeric identifier. There is no way to fetch a single automation rule by code — the `get` operation is not available.
4. **The list returns only codes.** [`GET /v1/bizproc-robots`](./bizproc-robots/list.md) returns an array of strings — the codes of registered automation rules, without the other fields.
5. **Handler domain.** The URL in `handler` and `placementHandler` must be on the application domain — Bitrix24 calls the handler at this address during automation.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Activities | [`/v1/bizproc-activities`](/docs/entities/bizproc-activities) | Activities for the business process designer. They appear only in the business process designer, not in the automation designer |
| Process log | [`POST /v1/workflows/activity-log`](/docs/automation/workflows/activity-log) | Writing a handler message to the business process log |

## Typical scenario

1. Register the automation rule via [`POST /v1/bizproc-robots`](./bizproc-robots/create.md): set `code`, `name`, the `handler` on the application domain, the document type `documentType`, and the input `properties`.
2. The automation rule appears in the automation designer and in the business process designer. When automation runs for a document of the given type, Bitrix24 calls the `handler` with the filled-in parameters.
3. With `useSubscription: "Y"` the automation waits for the application's response; with `"N"` it continues immediately.
4. To review the registered automation rules, use [`GET /v1/bizproc-robots`](./bizproc-robots/list.md). Delete an automation rule you no longer need by its code via [`DELETE /v1/bizproc-robots/:code`](./bizproc-robots/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Request rate | shared Vibecode API limit — see [Limits and optimization](/docs/optimization) |

## See also

- [Business process activities](/docs/entities/bizproc-activities)
- [Business process log](/docs/automation/workflows/activity-log)
- [Keys and authorization](/docs/keys-auth)
- [Entity reference](/docs/entities-index)