Bitrix24 Agent (Lean + Reliable)

Use this skill to deliver correct Bitrix24 integrations with low token usage and production-safe defaults.

Quick Start

Use this flow unless the user asks for a different one:

1. •Pick intent + one minimal pack (core by default).
2. •Run a read probe first.
3. •For writes, use plan then execute with confirmation.

Read probe:

python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current --params '{}'

Safer write flow:

python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.add \
  --params '{"fields":{"TITLE":"Plan demo"}}' \
  --packs core \
  --plan-only

python3 skills/bitrix24-agent/scripts/bitrix24_client.py \
  --execute-plan <plan_id> \
  --confirm-write

Runtime Prerequisites

Required environment:

• •B24_DOMAIN
• •B24_AUTH_MODE = webhook or oauth

Webhook mode:

• •B24_WEBHOOK_USER_ID
• •B24_WEBHOOK_CODE

OAuth mode:

• •B24_ACCESS_TOKEN
• •B24_REFRESH_TOKEN
• •B24_CLIENT_ID and B24_CLIENT_SECRET (for --auto-refresh)

Useful safety/reliability flags:

• •B24_REQUIRE_PLAN=1 for mandatory plan->execute on write/destructive calls
• •B24_PACKS=core,... for default pack set
• •B24_RATE_LIMITER=file with B24_RATE_LIMITER_RATE and B24_RATE_LIMITER_BURST

Default Mode: Lean

Apply these limits unless the user asks for deep detail:

• •Load at most 2 reference files before first actionable step.
• •Start from references/packs.md.
• •Then open only one target file: references/catalog-<pack>.md.
• •Open references/chains-<pack>.md only if the user needs workflow steps.
• •Open references/bitrix24.md only for auth architecture, limits, event reliability, or unknown errors.

Response limits:

• •Use concise output (goal + next action + one command).
• •Do not retell documentation.
• •Do not dump large JSON unless requested.
• •Return only delta if guidance was already given.

Routing Workflow

1. •Determine intent:

• •method call
• •troubleshooting
• •architecture decision
• •event/reliability setup

1. •Normalize product vocabulary:

• •"collabs", "workgroups", "projects", "social network groups" -> collab (and boards for scrum).
• •"Copilot", "CoPilot", "BitrixGPT", "AI prompts" -> platform (ai.*).
• •"open lines", "contact center connectors", "line connectors" -> comms (imopenlines.*, imconnector.*).
• •"feed", "live feed", "news feed" -> collab (log.*).
• •"sites", "landing pages", "landing" -> sites (landing.*).
• •"booking", "calendar", "work time", "time tracking" -> services (booking.*, calendar.*, timeman.*).
• •"orders", "payments", "catalog", "products" -> commerce (sale.*, catalog.*).
• •"consents", "consent", "e-signature", "sign" -> compliance (userconsent.*, sign.*).

1. •Choose auth quickly:

• •one portal/internal integration: webhook
• •app or multi-portal lifecycle: OAuth

1. •Select minimal packs:

• •default core
• •add only required packs: comms, automation, collab, content, boards, commerce, services, platform, sites, compliance, diagnostics

Execution Flow (Safe by Default)

Command template:

python3 skills/bitrix24-agent/scripts/bitrix24_client.py <method> \
  --params '<json>' \
  --packs core

Guardrails to enforce:

• •allowlist via packs and --method-allowlist
• •write gate with --confirm-write
• •destructive gate with --confirm-destructive
• •optional two-phase write with --plan-only and --execute-plan
• •idempotency for writes (auto or --idempotency-key)
• •audit trail unless --no-audit is explicitly needed

Reliability and Performance

Pagination and sync safety:

• •Never stop after first *.list page.
• •Keep deterministic ordering and persist checkpoints after successful page persistence.

Batch rules:

• •Maximum 50 commands per batch.
• •No nested batch.
• •Split oversized batches and parse per-command errors.

Limits and retries:

• •Treat QUERY_LIMIT_EXCEEDED and 5xx as transient.
• •Use exponential backoff with jitter (client default).
• •Use shared rate limiter keyed by portal in multi-worker setups.

Events:

• •Online events are not guaranteed delivery.
• •For no-loss pipelines, use offline flow:
  • •event.offline.get(clear=0)
  • •process idempotently with retry budget
  • •event.offline.error for failed items
  • •event.offline.clear only for successful/DLQ'ed items
• •Use scripts/offline_sync_worker.py as baseline.

Error Handling

Fast mapping:

Escalate to deep reference (references/bitrix24.md) on:

• •unknown auth/permission behavior
• •recurring limit failures
• •offline event loss concerns
• •OAuth refresh race or tenant isolation issues

Quality Guardrails

• •Never expose webhook/OAuth secrets.
• •Enforce least-privilege scopes and tenant isolation.
• •Keep writes idempotent where possible.
• •Validate application_token in event handlers.
• •Prefer REST v3 where compatible; fallback to v2 where needed.

Reference Loading Map

1. •references/packs.md for pack and loading strategy.
2. •references/catalog-<pack>.md for method shortlist.
3. •references/chains-<pack>.md for implementation chains.
4. •references/bitrix24.md for protocol-level troubleshooting and architecture decisions.

Useful search shortcuts:

rg -n "^# Catalog|^# Chains" references/catalog-*.md references/chains-*.md
rg -n "WRONG_AUTH_TYPE|insufficient_scope|QUERY_LIMIT_EXCEEDED|expired_token" references/bitrix24.md
rg -n "offline|event\\.bind|event\\.offline|application_token" references/bitrix24.md

Scripts

• •scripts/bitrix24_client.py: method calls, packs, allowlist, confirmations, plans, idempotency, audit, rate limiting, retries.
• •scripts/offline_sync_worker.py: offline queue polling, bounded retries, DLQ handling, safe clear flow, graceful shutdown.