Para agentes de IA: markdown desta página — /docs-content-en/entities/bizproc-robots.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

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)

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 — the fields filled in when configuring the rule
returnProperties object no Automation rule output parameters — the values the rule returns
filter object no INCLUDE / EXCLUDE rules by document type
usePlacement string no Whether to open the 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 string Addressable identifier. Uses the code returned by Bitrix24 when present; otherwise equals the submitted code. Used as :code for PATCH and DELETE

Response example

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

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 An authorization key sent 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 MISSING_REQUIRED_FIELDS A required field is missing — code, name, or handler
400 SERVER_APP_MISMATCH handler points to a Black Hole subdomain that has no server of this app behind it — the subdomain does not exist, or the server belongs to another app. Register the handler with the key of the app the server is linked to
503 BIZPROC_CALLBACK_RESOLVE_FAILED The platform could not match the handler to a server. The automation rule is not registered — repeat the request
422 BITRIX_ERROR Bitrix24 validation error — text in error.message

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