Awesome-omni-skill 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.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/development/bitrix24-agent-vrtalex" ~/.claude/skills/diegosouzapw-awesome-omni-skill-bitrix24-agent-2d7f52 && rm -rf "$T"

manifest: skills/development/bitrix24-agent-vrtalex/SKILL.md

source content

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:

Pick intent + one minimal pack (
```
core
```
by default).
Run a read probe first.
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

Determine intent:

method call
troubleshooting
architecture decision
event/reliability setup

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.*
```
).

Choose auth quickly:

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

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:

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

```
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
```
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.