لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/bizproc-activities.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

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
Fieldcode Typestring RequiredYes DescriptionUnique activity code. Allowed characters: a-z, A-Z, 0-9, ., -, _. Serves as the identifier in the update and delete paths
Fieldname Typestring | object RequiredYes DescriptionActivity name. A string or a localized object like {"en": "...", "de": "..."}
Fieldhandler Typestring RequiredYes DescriptionActivity handler URL. The domain matches the application domain
Fielddescription Typestring | object RequiredNo DescriptionActivity description. A string or a localized object
FieldauthUserId Typenumber RequiredNo DescriptionID of the user whose token is passed to the application when the activity is called. List: GET /v1/users
FielduseSubscription Typestring RequiredNo DescriptionWhether to wait for the application's response before continuing the process: Y or N
Fieldproperties Typeobject RequiredNo DescriptionActivity input parameters — fields that are filled in when configuring the activity in the designer
FieldreturnProperties Typeobject RequiredNo DescriptionActivity output parameters — values the activity returns to the process
FielddocumentType Typearray RequiredNo DescriptionDocument type the activity applies to — module, object, type. Values: Document types
Fieldfilter Typeobject RequiredNo DescriptionLimits which documents the activity is available for. Without the field, the activity is available for all documents.
INCLUDE lists the conditions under which the activity is available, EXCLUDE those under which it is not. A condition is a document type prefix, for example ["crm", "CCrmDocumentDeal"], or a Bitrix24 edition: "b24" for cloud, "box" for on-premise.
Example: {"INCLUDE": [["crm", "CCrmDocumentDeal"], ["crm", "CCrmDocumentLead"]]}.
Write the keys in uppercase: with lowercase keys the field is accepted but restricts nothing. A value that is not an object returns 422 BITRIX_ERROR
FieldusePlacement Typestring RequiredNo DescriptionWhether to open the activity settings in a slider panel: Y or N
FieldplacementHandler Typestring RequiredNo DescriptionURL 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 — OAuth application

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

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionAddressable 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
HTTP403 CodeOAUTH_REQUIRED DescriptionThe request was sent with an API key. Only an authorization key can register activities
HTTP401 CodeTOKEN_MISSING DescriptionThe authorization key was sent without the Authorization: Bearer header
HTTP401 CodeWRONG_AUTH_SCHEME DescriptionThe authorization key was sent in the Authorization: Bearer header. The key goes in X-Api-Key, while Authorization: Bearer carries the session token
HTTP401 CodeINVALID_SESSION DescriptionThe session token has expired or is invalid — authorize again
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the bizproc scope
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionA required field is missing — code, name, or handler
HTTP400 CodeSERVER_APP_MISMATCH Descriptionhandler 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
HTTP409 CodeBIZPROC_MODULE_NOT_ENABLED DescriptionBusiness Processes are not available on the account: the module is not included in the plan, or it is switched off in account settings. Ask an account administrator to enable Business Processes — until then the method answers the same way for any number of retries
HTTP503 CodeBIZPROC_CALLBACK_RESOLVE_FAILED DescriptionThe platform could not match the handler to a server. The activity is not registered — retry the request
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 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