crm.activity.add

What crm.activity.add does

Creates activity records — the interactions layer of CRM. Activities matter because they carry follow-up semantics (responsible, deadline, completed) and because response-time and workload reports are built on them.

Business use cases

• External call systems logging completed calls on leads/deals
• Chat platforms recording conversation sessions as activities
• Field-sales apps logging visits with outcomes
• Creating follow-up to-dos from external triggers (modern portals should prefer crm.activity.todo.add for to-dos)

Typical fields and parameters

• OWNER_ID / OWNER_TYPE_ID — The bound record: type IDs from crm.enum.ownertype (1 lead, 2 deal, 3 contact, 4 company)
• TYPE_ID — 2 = call, 1 = meeting; see crm.enum.activitytype
• SUBJECT — What agents see in the activity list
• COMPLETED — 'Y' for already-done interactions (logged calls); 'N' creates a pending item with a deadline
• RESPONSIBLE_ID — Owner of the activity — feeds workload and response reports
• COMMUNICATIONS — Array binding the phone/contact used — required for call activities to render properly
• DESCRIPTION — Details/outcome notes

Example workflow

1. PBX reports a completed outbound call to +9715…, 4m 12s
2. Record resolved by phone via crm.lead.list / duplicate search
3. crm.activity.add logs a completed call with duration in DESCRIPTION and the agent as RESPONSIBLE_ID
4. The response-time dashboard now counts this as the first touch

Example request

POST .../crm.activity.add.json

{
  "fields": {
    "OWNER_ID": 20517,
    "OWNER_TYPE_ID": 1,
    "TYPE_ID": 2,
    "SUBJECT": "Outbound call — connected (4m12s)",
    "COMPLETED": "Y",
    "DIRECTION": 2,
    "RESPONSIBLE_ID": 7,
    "DESCRIPTION": "Discussed 2BR options; viewing proposed for Friday.",
    "COMMUNICATIONS": [
      { "VALUE": "+971501234567", "ENTITY_ID": 20517, "ENTITY_TYPE_ID": 1 }
    ]
  }
}

Example response

{ "result": 44210, "time": { ... } }

Field mapping notes

• For genuine telephony integration (call cards, recordings, telephony reports), use telephony.externalcall.* instead — crm.activity.add makes list entries, not call-center data
• COMPLETED='N' without a deadline creates permanently pending items — always set deadlines on open activities
• Bitrix24 is deprecating some legacy activity types in favor of crm.activity.todo.* — prefer todo methods for new to-do creation

Security notes

• Activities appear in agents' counters and timelines — a buggy integration spamming activities disrupts the whole team's day; throttle and test carefully

Common errors

• Activity created but not visible on the record — OWNER_TYPE_ID/OWNER_ID mismatch — verify with crm.enum.ownertype
• Call activity missing phone context — COMMUNICATIONS array omitted
• Response-time dashboard not counting the touch — RESPONSIBLE_ID is the service account, not the agent — attribute to the human who acted

Production implementation tips

• Attribute RESPONSIBLE_ID to the real agent, not the integration account — otherwise your metrics credit a robot
• Summarize chat sessions into one activity rather than one per message

Webhook or OAuth app?

Component decision; follows the parent integration.

Full decision guide: webhook vs OAuth app in Bitrix24.

When to use a queue worker

Call events burst at peak hours; queue and batch like everything else.

How Tech Titan can help

Tech Titan builds production Bitrix24 integrations around crm.activity.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.