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

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

Configurable activities

A configurable activity is a record in the timeline of a CRM entity with its own styling: an icon, a title, body blocks, and buttons. The layout structure defines its appearance. It suits integrations that show a card for a call, request, delivery, or other external event in the timeline of a deal, lead, contact, or company.

Bitrix24 API: crm.activity.configurable.* Scope: crm

Deleting and listing configurable activities go through the common activities API: DELETE /v1/activities/:id and GET /v1/activities.

Create activity

POST /v1/activity-configurable

Creates a configurable activity in the timeline of a CRM entity. fields defines the activity's field set; layout defines its appearance.

Request fields (body)

Field Type Required Description
FieldownerTypeId Typenumber Requiredyes DescriptionCRM entity type:
1 — lead
2 — deal
3 — contact
4 — company
7 — quote
31 — invoice
≥128 — smart process, the type ID is in GET /v1/smart-processes
FieldownerId Typenumber Requiredyes DescriptionID of the entity in whose timeline the activity is created. The source depends on ownerTypeId: GET /v1/leads, GET /v1/deals, GET /v1/contacts, GET /v1/companies, GET /v1/quotes, GET /v1/invoices, GET /v1/items/:entityTypeId
Fieldfields Typeobject Requiredyes DescriptionActivity fields
Fieldfields.typeId Typestring Requiredno DescriptionActivity type. Defaults to CONFIGURABLE. A custom type is registered in Bitrix24 as configurable in the context of the same application
Fieldfields.completed Typeboolean Requiredno DescriptionActivity is closed. Accepts true/false, 1/0, Y/N
Fieldfields.deadline Typestring Requiredno DescriptionDue date, ISO 8601. Incompatible with fields.isIncomingChannel
Fieldfields.pingOffsets Typenumber[] Requiredno DescriptionOffsets in minutes relative to fields.deadline at which reminders are generated
Fieldfields.isIncomingChannel Typeboolean Requiredno DescriptionActivity created from an incoming channel. Accepts true/false, 1/0, Y/N
Fieldfields.responsibleId Typenumber Requiredno DescriptionID of the responsible employee. List: GET /v1/users
Fieldfields.badgeCode Typestring Requiredno DescriptionActivity badge code on the Kanban board
Fieldfields.originatorId Typestring Requiredno DescriptionID of the external data source
Fieldfields.originId Typestring Requiredno DescriptionID of the record in the external source
Fieldlayout Typeobject Requiredyes DescriptionActivity appearance in the timeline
Fieldlayout.icon.code Typestring Requiredyes DescriptionActivity icon code
Fieldlayout.header.title Typestring Requiredyes DescriptionActivity title
Fieldlayout.body.logo.code Typestring Requiredyes DescriptionLogo code in the body. Without logo, the request fails with 422 BITRIX_ERROR
Fieldlayout.body.blocks Typeobject Requiredno DescriptionNamed body blocks
Fieldlayout.footer.buttons Typeobject Requiredno DescriptionButtons in the bottom section of the activity

A block in layout.body.blocks has a type and properties. Main block types:

  • text — value
  • link — link with an action
  • lineOfBlocks — a row of nested blocks
  • withTitle — block with a caption

The action of links and buttons is defined by the type field:

  • redirect — navigation to the URL from the uri field
  • openRestApp — opening the application with the parameters from actionParams
  • restEvent — an event to the application by id, for menu items

Examples

Examples are given only for an OAuth application: a personal key does not work here. OAuth application requirements — Configurable activities.

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/activity-configurable \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerTypeId": 1,
    "ownerId": 999,
    "fields": { "typeId": "CONFIGURABLE", "completed": true, "responsibleId": 1, "badgeCode": "CUSTOM" },
    "layout": {
      "icon": { "code": "call-completed" },
      "header": { "title": "Incoming call" },
      "body": {
        "logo": { "code": "call-incoming" },
        "blocks": {
          "phone": { "type": "text", "properties": { "value": "+12025550123" } }
        }
      },
      "footer": {
        "buttons": {
          "startCall": {
            "title": "About the client",
            "type": "primary",
            "action": { "type": "openRestApp", "actionParams": { "clientId": 456 } }
          }
        }
      }
    }
  }'

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/activity-configurable', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ownerTypeId: 1,
    ownerId: 999,
    fields: { typeId: 'CONFIGURABLE', completed: true, responsibleId: 1, badgeCode: 'CUSTOM' },
    layout: {
      icon: { code: 'call-completed' },
      header: { title: 'Incoming call' },
      body: {
        logo: { code: 'call-incoming' },
        blocks: {
          phone: { type: 'text', properties: { value: '+12025550124' } },
        },
      },
      footer: {
        buttons: {
          startCall: {
            title: 'About the client',
            type: 'primary',
            action: { type: 'openRestApp', actionParams: { clientId: 456 } },
          },
        },
      },
    },
  }),
})

const { data } = await res.json()
console.log('Activity ID:', data.activity.id)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe result — the activity in the activity field
Fielddata.activity.id Typenumber DescriptionID of the created activity

Response example

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

Error response example

422 — logo not filled in the body:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "The logo field in BodyDto must be filled in."
  }
}

Errors

HTTP Code Description
HTTP400 CodeVALIDATION_ERROR DescriptionownerTypeId, ownerId, fields, or layout not provided. Message: ownerTypeId, ownerId, fields, and layout are required
HTTP422 CodeBITRIX_ERROR DescriptionRequest with a personal key vibe_api_*. The b24Code field of the response carries ERROR_WRONG_CONTEXT: the method works only with an authorization key vibe_app_* and a session token
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request: empty layout, layout.body.logo not filled, incoming activity with deadline
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe authorization key was passed without a session token in the Authorization: Bearer header

Full list of common API errors — Errors.

See also