# Bitrix24 Agent > Design, implement, debug, and harden integrations between AI agents and Bitrix24 REST API (webhooks, OAuth 2.0, scopes, events, batch, limits, and REST 3.0). Use when asked to connect AI assistants/agents to Bitrix24, automate CRM/tasks/chats, process Bitrix24 events, choose an auth model, or resolve Bitrix24 API errors and performance issues. Use when this capability is needed. - Skill: `tomevault-io/bitrix24-agent` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/bitrix24-agent` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/bitrix24-agent/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/bitrix24-agent --- # 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: ```bash python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current --params '{}' ``` Safer write flow: ```bash 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 \ --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-.md`. - Open `references/chains-.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 2. 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.*`). 3. Choose auth quickly: - one portal/internal integration: webhook - app or multi-portal lifecycle: OAuth 4. 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: ```bash python3 skills/bitrix24-agent/scripts/bitrix24_client.py \ --params '' \ --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: | Error code | Typical cause | Immediate action | |---|---|---| | `WRONG_AUTH_TYPE` | method called with wrong auth model | switch webhook/OAuth model for this method | | `insufficient_scope` | missing scope | add scope and reinstall/reissue auth | | `expired_token` | OAuth token expired | refresh token (`--auto-refresh` or external refresh flow) | | `QUERY_LIMIT_EXCEEDED` | burst above portal budget | backoff, queue, tune limiter, reduce concurrency | | `ERROR_BATCH_LENGTH_EXCEEDED` | batch payload too large | split batch | | `ERROR_BATCH_METHOD_NOT_ALLOWED` | unsupported method in batch | call directly | 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-.md` for method shortlist. 3. `references/chains-.md` for implementation chains. 4. `references/bitrix24.md` for protocol-level troubleshooting and architecture decisions. Useful search shortcuts: ```bash 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. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/vrtalex) — claim your Tome and manage your conversions.