Automation rules

Register your own automation rules to automate Bitrix24. An automation rule is an external handler that appears both in the Automation rules section 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)

Examples

Only an OAuth application key can register an automation rule — both examples send an OAuth application 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 — OAuth application

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 — OAuth application

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

Response example

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

Error response example

403 — the request was sent with an API key:

{
  "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

The full list of common API errors — Errors.

Known specifics

A handler on a Black Hole subdomain gets reliable delivery. The platform takes over delivery of the calls and stores the address of its own receiver in Bitrix24 instead of the one you passed. Such a handler can only be registered with a single request, and the delivery itself is switched on per Bitrix24 account — Activity and automation rule callback delivery.

See also

• Update an automation rule
• Delete an automation rule
• Activity and automation rule callback delivery
• Keys and authorization