Bitrix24 is the most common CRM among our clients, and we've worked with it for years. But its REST API has a personality: things that look obvious behave non-obviously — and you usually find out in production. Here are the five quirks that ate the most debugging hours.
The five quirks
Each row is real API behavior, not a bug on one particular portal. Collected from production integrations of our agents with Bitrix24.
| Quirk | Symptom | Workaround |
|---|---|---|
| Silent drop of invalid values | crm.deal.update returns success, but the enum field didn't change: values outside the list are silently ignored | Write value IDs, not labels; re-read after critical writes |
| Webhooks with no guarantees | ONCRMDEALUPDATE events arrive batched, delayed and out of order | Treat a webhook as a “something changed” signal: re-fetch state via the API, never trust the payload |
| ~2 requests/sec limit | Everything flies on the demo, then QUERY_LIMIT_EXCEEDED on real traffic | batch up to 50 commands per call + a queue with retries and exponential backoff |
| Pagination with a hidden COUNT | Lists slow down with every page on a large portal: each request recounts the total | start=-1 disables the count; paginate with an ID cursor in the filter instead of start |
| UF_* vs ufCrm* | The same custom field is UF_CRM_… in crm.deal.* and camelCase ufCrm… in smart processes (crm.item.*) | One field-mapping module; no raw field names in business logic |
Why it matters
An AI agent that writes to a CRM is an integration under load. Every silent failure costs trust: if a deal didn't update and nobody noticed, the rep stops believing the agent. And team trust is the pilot's main metric — a second silent failure won't be forgiven.
How we build it now
Idempotent writes with a read-back after critical operations. State reconciliation every few minutes instead of blind faith in webhooks. batch for anything bulk. Field mapping in a single module. And an integration eval run before every deploy — on a test portal, not the client's.
What we'd do differently
The first week of any integration should be read-only. The agent reads, analyzes, suggests — but doesn't write. That's seven days slower and months of cleanup cheaper: half the quirks in that table we'd have caught before they touched live deals.
Our checklist for integrating an agent with Bitrix24 is available on request: andrew@grow2.ai.