For AI agents: markdown of this page — /docs-content-en/entities/activities/configurable.md documentation index — /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. Suited for integrations that show a card for a call, request, delivery, or other external event in the timeline of a deal, lead, contact, or company.

This section covers only create, read, and update. Delete and list go through the common activities API: DELETE /v1/activities/:id and GET /v1/activities.

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

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 its appearance.

Request fields (body)

Field Type Req. Description
ownerTypeId number yes CRM 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
ownerId number yes ID of the entity in whose timeline the activity is created
fields object yes Activity fields
fields.typeId string no Activity type. Defaults to CONFIGURABLE. A custom type is registered in Bitrix24 as configurable in the context of the same application
fields.completed boolean no Activity is closed. Accepts true/false, 1/0, Y/N
fields.deadline string no Due date, ISO 8601. Incompatible with fields.isIncomingChannel
fields.pingOffsets number[] no Offsets in minutes relative to fields.deadline at which reminders are generated
fields.isIncomingChannel boolean no Activity created from an incoming channel. Accepts true/false, 1/0, Y/N
fields.responsibleId number no ID of the responsible employee. List: GET /v1/users
fields.badgeCode string no Activity badge code on the kanban
fields.originatorId string no ID of the external data source
fields.originId string no ID of the record in the external source
layout object yes Activity styling in the timeline
layout.icon.code string yes Activity icon code
layout.header.title string yes Activity title
layout.body.logo.code string yes Logo code in the body. Bitrix24 rejects a body without logo
layout.body.blocks object no Named body blocks
layout.footer.buttons object no Footer buttons

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 address from the uri field
  • openRestApp — opening the application with the actionParams parameters
  • restEvent — an event to the application by id, for menu items

Examples

Examples are given only for an OAuth application.

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
success boolean Always true on success
data.activity.id number ID 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
400 VALIDATION_ERROR ownerTypeId, ownerId, fields, or layout not provided
422 BITRIX_ERROR Bitrix24 rejected the request: empty layout, layout.body.logo not filled, call outside application context, incoming activity with deadline
403 SCOPE_DENIED The key lacks the crm scope
401 TOKEN_MISSING The authorization key was passed without a session token in the Authorization: Bearer header

Full list of common API errors — Errors.

Known specifics

Only in application context. An authorization key vibe_app_* with a session token in the Authorization: Bearer header is required. A personal API key vibe_api_* is rejected by Bitrix24 with ERROR_WRONG_CONTEXT.

See also