| name | bitrix24-agent |
| description | 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. |
Bitrix24 Agent (Lean + Reliable)
Use this skill to deliver correct Bitrix24 integrations with minimal token usage.
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 user asks for workflow/chain.
- Open
references/bitrix24.md only for auth architecture, limits, events reliability, or unknown errors.
Response format limits:
- Use concise output (goal + next action + one command).
- Do not retell documentation.
- Do not dump large JSON unless explicitly requested.
- Avoid repeating already provided guidance; return only delta.
Routing Workflow
- Determine intent:
- method call,
- troubleshooting,
- architecture decision,
- event/reliability setup.
Term normalization (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.*).
- Choose auth quickly:
- one portal/internal: incoming webhook.
- app/multi-portal/lifecycle features: OAuth.
- Select minimal packs:
- default
core.
- add only required packs:
comms, automation, collab, content, boards, commerce, services, platform, sites, compliance, diagnostics.
- Execute with guardrails:
- prefer
scripts/bitrix24_client.py and scripts/offline_sync_worker.py,
- enforce allowlist +
--confirm-write / --confirm-destructive,
- keep writes idempotent when possible.
- Escalate to deep reference only on trigger:
WRONG_AUTH_TYPE, insufficient_scope, QUERY_LIMIT_EXCEEDED, expired_token,- offline event loss concerns,
- OAuth refresh race or tenant isolation issues.
Quality Guardrails
- Never expose webhook/OAuth secrets.
- Scope and permissions must be least-privilege.
- No nested
batch.
- Online events are not guaranteed delivery; use offline flow for no-loss processing.
- Prefer REST 3.0 where compatible; fallback to v2 where needed.
Reference Loading Map
references/packs.md for pack and loading strategy.references/catalog-<pack>.md for method shortlist.references/chains-<pack>.md for implementation chains.references/bitrix24.md only when deeper protocol detail is required.
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, audit.scripts/offline_sync_worker.py: offline queue processing with retries and DLQ.
