sales-skills/sales-bitrix24

Bitrix24 Platform Help

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated platform knowledge.

1. What are you trying to do?

   • A) Add/update/list leads or deals (and map pipelines/stages) via the REST API
   • B) React to CRM changes with outbound webhooks (ONCRMDEALADD/UPDATE, ONCRMLEADADD)
   • C) Pick an auth method — inbound webhook (your own portal) vs OAuth 2.0 (an app)
   • D) Batch many calls / handle rate limits
   • E) Set up CRM structure — pipelines, stages, Smart Process Automation, contact center
   • F) Decide Free vs paid tier, or cloud vs self-hosted on-prem

2. Your portal or someone else's? Automating your account → inbound webhook. Building an app others install → OAuth 2.0.

Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.

Step 2 — Route or answer directly

| If the question is about... | Route to... | |---|---| | Choosing a CRM across vendors (Bitrix24 vs HubSpot/Pipedrive/Zoho/Keap), or CRM/RevOps strategy tradeoffs across tools | /sales-crm-selection {question} | | Generic iPaaS wiring to an ESP/other app | /sales-integration {question} | | Omnichannel/contact-center or marketing strategy | /sales-do {describe the goal} |

When routing, give the exact command, e.g. "This is a selection question — run: /sales-crm-selection free CRM for a solo founder".

Step 3 — Bitrix24 platform reference

Read references/platform-guide.md for the full reference — the module map (CRM vs tasks vs contact center vs sites), the free-vs-paid + cloud-vs-on-prem model, the CRM data model (lead/deal/pipeline shapes), and quick-start recipes (create a deal; subscribe to a deal event; batch).

Read references/bitrix24-api-reference.md for the integration surface — the method-based REST API (https://{portal}.bitrix24.com/rest/{user_id}/{webhook_code}/{method}), inbound vs outbound webhooks, OAuth 2.0 for apps, the core crm.* methods (crm.deal.add/.list/…, crm.lead.*, crm.item.* for SPA), {result,time} responses, batch (50 commands/request), and rate limits.

Answer using only the relevant section. Don't dump the full reference.

Step 4 — Actionable guidance

Focus on the user's specific situation:

• It's RPC, not resource-REST. You call methods (crm.deal.add, crm.lead.list) on a URL, not GET /deals. Each entity has *.add/.update/.get/.list/.delete/.fields.
• Inbound webhook for your own portal. A static URL with a secret code (Developer resources → Incoming webhook), no expiry, scoped by permissions — simplest for automating your account. Use OAuth 2.0 only for multi-tenant/Market apps.
• Pipelines = CATEGORY_ID, stages = STAGE_ID. A deal's funnel is CATEGORY_ID (0 = default) and its column is STAGE_ID (a crm_status) — get valid values from crm.dealcategory.* / crm.status.* before writing.
• Events carry only the ID. Outbound webhooks (ONCRMDEALUPDATE, …) POST {event, data:{FIELDS:{ID}}} + an app token — verify the token, then crm.deal.get for current data; dedupe.
• Batch to survive rate limits. Bitrix24 throttles (~2 req/sec) — use batch (up to 50 commands, with $result[...] chaining) and back off on errors.
• Free-forever is the hook. Unlimited users on the free plan makes it a popular free Keap/Ontraport/Zoho alternative; paid tiers add automation/SPA depth, and on-prem (Self-Hosted) is available if you need to host it.

If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.

Gotchas

Best-effort from research (2026-06) — features/pricing verified against the marketing site + API docs; confirm in-account.

1. Method-based RPC API. No GET /deals; it's crm.deal.list on the webhook/OAuth URL. The verb set (add/update/get/list/delete/fields) is consistent across entities.
2. Inbound webhook ≠ OAuth. Webhook = your portal, static URL + secret, no expiry, but some methods are blocked (telephony, certain app-only ops). OAuth = apps, tokens expire (refresh).
3. Pipelines/stages are IDs. CATEGORY_ID (funnel) + STAGE_ID (crm_status) — using a label or a stage from the wrong funnel fails silently/odd. Read crm.status.*/crm.dealcategory.* first.
4. Rate limits are real. ~2 req/sec sustained + per-method operating-time limits — batch (50/req) and back off, or you'll get throttled.
5. Outbound webhook payload is thin. Only the entity ID arrives — re-fetch via *.get. Verify the application token; dedupe (events can repeat).
6. It's a sprawling suite. CRM is one of many modules; the breadth means a learning curve. For just-CRM selection, weigh vs focused CRMs via /sales-crm-selection.
7. Cloud vs on-prem differ. Self-Hosted unlocks source/extra control + outbound webhooks need an active license; cloud is managed. Pick deliberately.

Related skills

• /sales-crm-selection — Choosing a CRM across vendors (Bitrix24 vs HubSpot/Pipedrive/Zoho/Keap/Ontraport) — selection strategy, free-tier tradeoffs
• /sales-forecast — Pipeline forecasting & RevOps analytics on top of your CRM data
• /sales-data-hygiene — Keeping CRM records clean (dedupe, enrichment, normalization)
• /sales-integration — Wiring Bitrix24 into an ESP/other app via webhooks/OAuth/Zapier
• /sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code

Examples

Example 1: Create a deal in the right pipeline via the API (developer/automation)

User says: "When a form is submitted, how do I create a Bitrix24 deal in a specific pipeline and stage via the API?" Skill does: Walks Recipe 1 — create an Incoming webhook (Developer resources, scope CRM), then POST …/rest/{user_id}/{code}/crm.deal.add with FIELDS:{TITLE, CATEGORY_ID:<pipeline>, STAGE_ID:<crm_status>, OPPORTUNITY, CONTACT_IDS, ASSIGNED_BY_ID}. Stresses fetching valid CATEGORY_ID/STAGE_ID from crm.dealcategory.*/crm.status.* first, that the response result is the new deal ID, and using batch if creating the contact + deal together. Result: Deals land in the correct funnel/stage from the form.

Example 2: React to a deal moving stages (outbound webhook)

User says: "I want my system notified when a Bitrix24 deal is updated." Skill does: Explains Outbound webhook setup (Developer resources → Outgoing webhook): handler URL + event ONCRMDEALUPDATE; Bitrix24 POSTs {event, data:{FIELDS:{ID}}} + an application token. The handler verifies the token, then calls crm.deal.get?ID=… for current fields (the event carries only the ID), and dedupes. Notes on-prem needs an active license. Result: Real-time, verified deal-change notifications.

Example 3: Is the free plan really enough, and cloud or on-prem?

User says: "I'm a solo founder — is Bitrix24 free actually usable, and should I self-host?" Skill does: Confirms the free-forever (unlimited users) plan includes CRM + tasks + contact center basics — a genuine free Keap/Zoho alternative — with paid tiers adding automation/SPA/throughput. Frames cloud (managed) vs on-prem Self-Hosted (you host, more control, license for outbound webhooks), and routes the cross-vendor decision: "run: /sales-crm-selection free all-in-one CRM vs HubSpot free." Result: A grounded free-tier + hosting decision.

Troubleshooting

My API call returns an error / 401

Symptom: Calls to /rest/{user_id}/{code}/{method} fail. Cause: Wrong/secret-rotated webhook code, the webhook lacks the permission scope for that method, or the method is one webhooks can't call (telephony/app-only). Solution: Recreate/copy the Incoming webhook URL exactly (Developer resources), enable the right scopes (e.g. CRM), and confirm the method is webhook-eligible — if not, build an OAuth local app. Test with the docs' request generator / Execute button.

My deals are created but land in the wrong place

Symptom: Deals appear in the default funnel/stage, not the intended one. Cause: CATEGORY_ID (pipeline) and STAGE_ID weren't set, or STAGE_ID belongs to a different funnel. Solution: Read valid funnels via crm.dealcategory.list and their stages via crm.status.list / crm.dealcategory.stage.*, then pass the matching CATEGORY_ID + STAGE_ID on crm.deal.add. A stage id from another funnel won't route correctly.

I'm hitting rate limits / it's slow

Symptom: Throttling errors or slow bulk operations. Cause: Too many sequential calls — Bitrix24 throttles (~2 req/sec + per-method operating-time limits). Solution: Use the batch method (up to 50 commands per request, chaining with $result[...]), page *.list with start, add exponential backoff, and spread bulk jobs. For heavy syncs, prefer batch + selective select fields.