b24jssdk-recipes

name: b24jssdk-recipes description: End-to-end mini-apps built on the canonical b24jssdk actions.v{2,3}.* surface — CRM analytics, ERP sync, Telegram bot, mass mailing, task automation, AI assistant, web search + LLM, Disk files, webhook handler, error-handling cookbook, event registration, OAuth install handshake. Each recipe is a self-contained TypeScript program using B24Hook on the server side. Load when the user asks for a working example or a starting template.

b24jssdk recipes

Twelve end-to-end programs. Every recipe runs on B24Hook (Node.js), but each function body takes $b24: TypeB24 so the same code works in-frame too — just swap the boot for initializeB24Frame().

All recipes use the canonical $b24.actions.v{2,3}.*.make() surface. The legacy callMethod / callBatch / callListMethod / fetchListMethod is @deprecated for 3.0.0 — do not generate code against it.

Shared library (lib/)

Pure, I/O-free helpers extracted from recipes so they can be unit-tested without a live portal.

baseStage(s) strips the multi-funnel category prefix ("C2:WON" → "WON").
analyseFunnel(deals) groups deals by raw stageId key, summing counts and opportunity amounts.

Boot snippet (shared by all recipes)

import { B24Hook, LoggerBrowser, type TypeB24 } from '@bitrix24/b24jssdk'

export function bootB24(): TypeB24 {
  const url = process.env.B24_HOOK
  if (!url) throw new Error('B24_HOOK env var is required (incoming webhook URL)')
  const $b24 = B24Hook.fromWebhookUrl(url)
  $b24.offClientSideWarning()
  return $b24
}

export const logger = LoggerBrowser.build('Recipe', process.env.NODE_ENV !== 'production')

The snippet is inlined into each recipe file for copy-paste convenience.

API-version split — quick reference

Inside the recipes the split is:

The SDK no longer gates v3 by a hardcoded allowlist: actions.v3.* sends any method to the v3 endpoint and the server validates it (an unknown method returns METHODNOTFOUNDEXCEPTION as a soft error on the AjaxResult, not an SDK throw). The recipes pick a surface per method by what reads cleanest for that data, not by a whitelist.

Field-naming choice

CRM v3-style methods (crm.item.list) use camelCase fields: stageId, assignedById, opportunity, createdTime. Classic methods (tasks.task.add, crm.activity.list, crm.timeline.comment.add) use uppercase: TITLE, DESCRIPTION, OWNER_TYPE_ID. Recipes follow this split.

Running

# 1. Install: at the repo root or in a fresh project
pnpm add @bitrix24/b24jssdk
# Recipe-specific deps as needed:
#   recipe 4: pnpm add node-cron
#   recipe 6: pnpm add grammy node-cron
#   recipe 7: pnpm add express
#   recipe 8: pnpm add openai
#   recipe 9: pnpm add openai
#   recipe 12: pnpm add express

# 2. Set env
export B24_HOOK='https://YOUR_PORTAL.bitrix24.com/rest/1/k32t88gf3azpmwv3'

# 3. Run with tsx (no build step)
npx tsx examples/01-crm-analytics.ts

Caveats applied across recipes

• Multi-funnel pipelines: stage IDs may carry a category prefix (C2:WON, C4:LOSE). Recipes 1, 3, and 6 strip the prefix when checking the base stage.
• order in callList.make: silently dropped (the action forces cursorIdKey ASC, defaulting to idKey, for cursor stability). Use filter to narrow.
• customKeyForResult: 'items' for crm.item.list, omit or 'tasks' for classic methods. Wrong value → silent empty array.
• idKey / cursorIdKey: idKey: 'id' for crm.item.list; 'ID' (default) for classic methods. tasks.task.list is the exception on v2 — it returns lowercase id but sorts by ID, so use idKey: 'id', cursorIdKey: 'ID' (and customKeyForResult: 'tasks'); on v3 it is all-lowercase: idKey: 'id' (default), no cursorIdKey, customKeyForResult: 'items'.
• Error handling: failed calls throw AjaxError for REST errors; recipes log and continue where it makes sense. Tune via setRestrictionManagerParams if you need different retry behaviour (see b24jssdk-core).
• Webhook events (recipe 7): registration of the outbound webhooks themselves (which events go where) is a one-off setup. Recipe 11 (11-event-registration.ts) is a small CLI for that: list / bind / unbind via event.get / event.bind / event.unbind.

Cross-reference

For v3 wire-level details (filter grammar, batch $ref/$refArray, cursor pagination), use the b24jssdk-rest and b24jssdk-filtering skills.