Skip to main content
Tech Titan

API Method Guide

crm.timeline.comment.add

Module: CRM (timeline)Scope: crm

Direct answer

crm.timeline.comment.add posts a comment to a CRM record's timeline. Pass ENTITY_ID, ENTITY_TYPE ('lead', 'deal', 'contact', 'company'), and COMMENT text. It is how integrations leave a human-readable trail.

What crm.timeline.comment.add does

Writes comments to record timelines — the difference between an integration that silently mutates data and one whose actions agents and managers can see and trust.

Business use cases

  • Logging integration actions: 'Payment AED 4,500 received (txn pay_9f3k2)'
  • Recording repeat portal inquiries on the existing lead
  • Surfacing external system events (contract generated, KYC passed) to agents
  • Migration annotations explaining imported data provenance

Typical fields and parameters

  • ENTITY_ID — The record's ID
  • ENTITY_TYPE — 'lead' | 'deal' | 'contact' | 'company'
  • COMMENT — Text, with limited BB-code style formatting supported
  • AUTHOR_ID — Displayed author — use the service account so integration comments are visually distinct

Example workflow

  1. Webhook processes a repeat Dubizzle inquiry for lead 20517
  2. crm.lead.update refreshes last-inquiry fields
  3. crm.timeline.comment.add posts 'Repeat inquiry: Dubizzle listing D-2231, message: …'
  4. Agent opens the lead and sees the full external history without leaving CRM

Example request

POST .../crm.timeline.comment.add.json

{
  "fields": {
    "ENTITY_ID": 20517,
    "ENTITY_TYPE": "lead",
    "COMMENT": "Repeat inquiry via Dubizzle — listing D-2231.\nMessage: \"Is the 2BR still available?\""
  }
}

Example response

{ "result": 8817, "time": { ... } }
// "result" is the new timeline comment ID.

Field mapping notes

  • Comments are content, not data: anything you will filter or report on belongs in fields; comments are for human context
  • Keep a consistent prefix convention ('[LeadBridge]') so integration comments are scannable and searchable

Security notes

  • Never write secrets, full tokens, or raw payment data into comments — timelines are visible to everyone with record access

Common errors

  • 'Access denied' — Service account cannot see the target record — timeline write requires record read/update rights
  • Comment on the wrong entity — ENTITY_TYPE mismatch (lead ID sent with type 'deal') — validate the pair

Production implementation tips

  • Bundle update + comment in one batch call — atomic-ish and half the requests
  • Rate-limit your own commenting: a chat integration posting every message as a comment will bury the timeline; summarize instead

Webhook or OAuth app?

Component of the parent integration; no independent choice needed.

Full decision guide: webhook vs OAuth app in Bitrix24.

When to use a queue worker

Piggybacks on the parent flow's queue; no special handling beyond that.

How Tech Titan can help

Tech Titan builds production Bitrix24 integrations around crm.timeline.comment.add and its siblings — with authentication, field mapping, queue workers, retry logic, duplicate handling, and structured logs as standard. If this method is on your critical path, bring the requirement to a free audit call and leave with an architecture sketch.

Book Free CRM Audit or DemoAPI Development service

Frequently asked questions

How do I add a note to a lead via the Bitrix24 API?

crm.timeline.comment.add with ENTITY_ID, ENTITY_TYPE 'lead', and your COMMENT text — see the example above.

Should integrations write comments or activities?

Comments for passive context (events, logs); activities (crm.activity.*) for things that represent real interactions or need follow-up semantics — calls, meetings, to-dos.

Need crm.timeline.comment.add working in production?

Bring your integration to a free audit call — you'll leave with an architecture sketch and an honest scope, whether or not you engage us.

Book Free CRM Audit or DemoContact us