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

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

Business process activities

Register your own activities for the Bitrix24 business process designer. An activity is an external handler that appears in the business process designer and is called during the process: it receives input parameters, runs its logic on the application side, and returns the result to the process.

Activities can be read, registered, updated, and deleted only with the vibe_app_… authorization key — the vibe_api_… API key does not work with these methods. Only a Bitrix24 account administrator can manage activities.

Bitrix24 API: bizproc.activity.* Scope: bizproc

Register an activity

POST /v1/bizproc-activities

Registers a new activity for the Bitrix24 business process designer. Fields are passed flat at the JSON root — without a fields wrapper. Can only be called with an authorization key together with the Authorization: Bearer header.

Request fields (body)

Field Type Required Description
code string Yes Unique activity code. Allowed characters: a-z, A-Z, 0-9, ., -, _. Serves as the identifier in the update and delete paths
name string | object Yes Activity name. A string or a localized object like {"en": "...", "de": "..."}
handler string Yes Activity handler URL. The domain matches the application domain
description string | object No Activity description. A string or a localized object
authUserId number No ID of the user whose token is passed to the application when the activity is called. List: GET /v1/users
useSubscription string No Whether to wait for the application's response before continuing the process: Y or N
properties object No Activity input parameters — fields that are filled in when configuring the activity in the designer
returnProperties object No Activity output parameters — values the activity returns to the process
documentType array No Document type the activity applies to — module, object, type. Values: Document types
filter object No INCLUDE / EXCLUDE rules by document type
usePlacement string No Whether to open the activity settings in a slider panel: Y or N
placementHandler string No URL of the settings slider panel. Required when usePlacement: "Y"

Examples

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-activities" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "notify_manager",
    "name": { "en": "Notify manager", "de": "Manager benachrichtigen" },
    "handler": "https://your-app.example.com/bizproc/notify"
  }'

JavaScript — authorization key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bizproc-activities', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'notify_manager',
    name: { en: 'Notify manager', de: 'Manager benachrichtigen' },
    handler: 'https://your-app.example.com/bizproc/notify',
  }),
})

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": "notify_manager"
  }
}

Error response example

403 — the request was sent with an API key:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_REQUIRED",
    "message": "bizproc-activities 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 activities
401 TOKEN_MISSING The authorization key was 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 activity is not registered — repeat the request
422 BITRIX_ERROR Bitrix24 rejected the registration — the reason is 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