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

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

Timeline comments

Manage CRM timeline comments: record operator notes, negotiation history and other context for deals, leads, contacts, companies and other entities. Each comment is attached to a specific CRM record via the entityType + entityId pair.

Bitrix24 API: crm.timeline.comment.* Scope: crm

Add comment

POST /v1/timelines

Creates a new timeline comment attached to a CRM record. Use it to record notes on deals, leads, contacts and companies.

Request fields (body)

Field Type Required Description
FieldentityType Typestring Requiredyes DescriptionType of the parent CRM record: deal, lead, contact, company or DYNAMIC_<entityTypeId> for smart processes. For example, DYNAMIC_174 for a smart process with entityTypeId: 174 from GET /v1/smart-processes
FieldentityId Typenumber Requiredyes DescriptionParent record ID. The source depends on the type: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies, GET /v1/items/:entityTypeId (smart process items)
Fieldcomment Typestring Requiredyes DescriptionComment text. An empty string is rejected with the error BITRIX_ERROR Empty comment message
FieldFILES Typearray Requiredno DescriptionComment attachments. Each element is an array of two strings [fileName, base64Content]. The field type in the Bitrix24 schema is attached_diskfile

When created via the API, the author (authorId) is taken from the API key owner, and the creation date (createdAt) is set by the server.

Attaching files. The FILES field is an array of [fileName, base64Content] pairs, one pair per file. The file content is passed as a base64-encoded string. The file is uploaded to Bitrix24 Drive and linked to the comment.

In the create response and when reading the comment (GET /v1/timelines/:id), attached files are returned in the FILES field — an object where the key is the Drive file ID and the value holds the metadata:

JSON 
"FILES": {
  "9317": {
    "id": 9317,
    "date": "2026-04-24T12:34:05+00:00",
    "type": "file",
    "name": "report.pdf",
    "size": 11,
    "image": false,
    "authorId": 1,
    "authorName": "John Smith",
    "urlPreview": null,
    "urlShow": "https://example.bitrix24.com/disk/downloadFile/9317/?&ncc=1&filename=report.pdf",
    "urlDownload": "https://example.bitrix24.com/disk/downloadFile/9317/?&ncc=1&filename=report.pdf"
  }
}

The urlShow and urlDownload addresses point to the Bitrix24 account's Drive and cannot be authorized with a key. Download the file through GET /v1/timelines/:commentId/files/:fileRef/download.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/timelines \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 741,
    "comment": "First contact: the client showed interest in the offer"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/timelines \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 741,
    "comment": "First contact: the client showed interest in the offer"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timelines', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityType: 'deal',
    entityId: 741,
    comment: 'First contact: the client showed interest in the offer',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timelines', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityType: 'deal',
    entityId: 741,
    comment: 'First contact: the client showed interest in the offer',
  }),
})

const { success, data } = await res.json()

curl — comment with a file

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/timelines \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 741,
    "comment": "Report attached",
    "FILES": [["report.pdf", "JVBERi0xLjQKJ..."]]
  }'

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created comment
Fielddata.id Typenumber DescriptionID of the created comment
Fielddata.entityType Typestring DescriptionType of the parent record
Fielddata.entityId Typenumber DescriptionParent record ID
Fielddata.comment Typestring DescriptionComment text
Fielddata.authorId Typenumber DescriptionAuthor ID — when created via the API, matches the key owner
Fielddata.createdAt Typedatetime DescriptionCreation date, ISO 8601 in UTC
Fielddata.FILES Typeobject DescriptionAttached files — only if any were passed. The key is the Drive file ID and the value holds the file metadata, shown in the "Attaching files" section above
Fieldmeta.warnings Typearray DescriptionPresent when the body carries fields that are neither in the comment schema nor in the field list of GET /v1/timelines/fields, for example a misspelled name. The warning code is UNRECOGNIZED_WRITE_FIELD: such a field may not have been stored. The response status is 201 On a route that wraps the field map itself, an object under fields is rejected with 400 NESTED_FIELDS_ENVELOPE when the schema does not declare fields; pass fields flat at the JSON root.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 66303,
    "entityId": 741,
    "entityType": "deal",
    "comment": "First contact: the client showed interest in the offer",
    "authorId": 1,
    "createdAt": "2026-04-24T12:34:05.000Z"
  }
}

Error response example

422 — the required comment was not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Empty comment message"
  }
}

Errors

HTTP Code Description
HTTP400 CodeREADONLY_FIELD DescriptionThe body carries a field that cannot be set on create: authorId, id or createdAt. Bitrix24 derives the author from the credentials the call is made with — to have the comment come from a specific user, make the call on that user's behalf
HTTP400 CodeINVALID_FILES_SHAPE DescriptionThe FILES field was not an array of [[fileName, base64Content]] pairs
HTTP422 CodeBITRIX_ERROR DescriptionValidation failed: empty comment, invalid entityType
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

See also