For AI agents: markdown of this page — /docs-content-en/entities/bizproc-robots.md documentation index — /llms.txt

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

Register an automation rule

POST /v1/bizproc-robots

Registers a new automation rule in Bitrix24. Fields are passed flat at the JSON root — without a fields wrapper.

Request fields (body)

Field Type Req. Description
code string yes Unique automation rule code. Allowed characters: a-z, A-Z, 0-9, ., -, _. Becomes the automation rule identifier in update and delete paths
name string | object yes Automation rule name. A string or a localized object like {"en": "...", "de": "..."}
handler string yes Handler URL. The domain must match the application domain
documentType array no Document type [module, object, type]. Values:
["crm", "CCrmDocumentLead", "LEAD"] — leads
["crm", "CCrmDocumentDeal", "DEAL"] — deals
["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Quote", "QUOTE"] — quotes
["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\SmartInvoice", "SMART_INVOICE"] — invoices
["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Dynamic", "DYNAMIC_<entityTypeId>"] — smart processes, <entityTypeId> from the entityTypeId field in GET /v1/smart-processes
description string | object no Automation rule description. A string or a localized object
authUserId number no The user whose token is passed to the application when the automation rule is invoked. List: GET /v1/users
useSubscription string no Whether to wait for a response from the application before continuing the rule: Y or N
properties object no Automation rule input parameters — fields that are filled in when configuring the automation rule
returnProperties object no Automation rule output parameters — the values the automation rule returns
filter object no INCLUDE / EXCLUDE rules by document type
usePlacement string no Whether to open automation rule settings in a slider panel: Y or N
placementHandler string no URL of the settings slider panel. Required when usePlacement: "Y"

Examples

Only an authorization key can register an automation rule — both examples send the authorization key and the Authorization: Bearer header. The session token is issued by OAuth authorization, is valid for 24 hours, and cannot be renewed — Passing the key.

curl — authorization key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bizproc-robots" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "deal_notify",
    "name": { "en": "Deal notification", "de": "Deal-Benachrichtigung" },
    "handler": "https://app.example.com/robots/deal-notify",
    "documentType": ["crm", "CCrmDocumentDeal", "DEAL"],
    "useSubscription": "N"
  }'

JavaScript — authorization key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bizproc-robots', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'deal_notify',
    name: { en: 'Deal notification', de: 'Deal-Benachrichtigung' },
    handler: 'https://app.example.com/robots/deal-notify',
    documentType: ['crm', 'CCrmDocumentDeal', 'DEAL'],
    useSubscription: 'N',
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
id boolean true — Bitrix24 confirmed the automation rule registration. This is a success flag, not a numeric identifier. The automation rule identifier is the code you set

Response example

JSON 
{
  "success": true,
  "data": {
    "id": true
  }
}

Error response example

403 — the request was sent with an API key:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_REQUIRED",
    "message": "bizproc-robots require an OAuth app key (vibe_app_*) with an Authorization: Bearer session — a personal vibe_api_* key lacks the per-user OAuth context Bitrix24 needs for these methods. Create an OAuth app (POST /v1/apps) and retry with its key. On this 403 switch keys — do NOT delete or recreate the app (that discards anything already registered under it, e.g. a bizproc robot you just registered)."
  }
}

Errors

HTTP Code Description
403 OAUTH_REQUIRED The request was sent with an API key. Only an authorization key can register automation rules
401 TOKEN_MISSING Authorization key without the Authorization: Bearer header
401 WRONG_AUTH_SCHEME The authorization key was sent in the Authorization: Bearer header. The key goes in X-Api-Key, while Authorization: Bearer carries the session token
401 INVALID_SESSION The session token has expired or is invalid — authorize again
403 SCOPE_DENIED The key lacks the bizproc scope
400 EMPTY_CREATE_BODY The request body is empty — pass at least one field
422 BITRIX_ERROR Bitrix24 validation error — text in error.message

The full list of common API errors — Errors.

See also