bitrix-pull

Realtime Pull (pull)

Baseline: main 23.0+ · Verified: pull 26.100.0, main 26.800.0

pull delivers short commands to browsers and the mobile app through the push server. Needs a configured server (CPullOptions::GetQueueServerStatus()); mobile push also CPullOptions::GetPushStatus().

Mechanism	Use for
Pull	Instant UI signal: "row 42 changed", counters
Messenger / agents (bitrix-background-jobs)	Durable work with retries; emit Pull from the worker when the UI must refresh

Send from PHP

\Bitrix\Main\Loader::includeModule('pull');

$ok = \Bitrix\Pull\Event::add([$userId, $otherUserId], [
    'module_id' => 'vendor.module',   // lower-cased by the kernel
    'command' => 'itemUpdated',
    'params' => ['id' => $itemId],   // IDs and flags only; load data via AJAX afterwards
    // 'expiry' => 86400,            // seconds, default
]);
if (!$ok) {
    $error = \Bitrix\Pull\Event::getLastError();
}

• Recipients: user ID(s), 32-char channel IDs or Bitrix\Pull\Model\Channel; 3rd arg \CPullChannel::TYPE_PRIVATE (default) / TYPE_SHARED.
• Per-user params: 'user_params' => [$userId => ['unread' => 3]] (merged into params for that user), 'dictionary' => [...] (merged for all). Result is reliable since pull 26.100; before it a falsy result for these keys is not a failure — check getLastError().
• Invalid UTF-8 anywhere in the payload → false (EVENT_BAD_ENCODING).
• Delivery is queued and sent by a background job at the end of the hit. Long-running CLI worker: call \Bitrix\Pull\Event::send() right after add().

Tags (CPullWatch)

\CPullWatch::Add($userId, 'VENDOR_ITEM_' . $itemId);          // when rendering the page
\CPullWatch::AddToStack('VENDOR_ITEM_' . $itemId, [           // later, to all watchers
    'module_id' => 'vendor.module',
    'command' => 'itemUpdated',
    'params' => ['id' => $itemId],
]);

• Add() is written at OnAfterEpilog for the current user; for another user or outside a web hit pass 3rd arg true (immediate).
• A watch lives ~30 min; the page keeps it alive with BX.PULL.extendWatch(tag).
• AddToStack() accepts an array of tags and skip_users.

Subscribe in JS

Add pull.client to rel (import { PULL } from 'pull.client', global BX.PULL). moduleId must be lower-case.

// With command: (params, extra, command, info)
const off = BX.PULL.subscribe({
    moduleId: 'vendor.module',
    command: 'itemUpdated',
    callback: (params, extra, command) => reload(params.id),
});

// Without command: one object for every module command
BX.PULL.subscribe({
    moduleId: 'vendor.module',
    callback: (data) => { /* data.command, data.params, data.extra */ },
});

BX.PULL.extendWatch('VENDOR_ITEM_' + itemId);
off(); // unsubscribe

• Handler object: BX.PULL.attachCommandHandler({ getModuleId: () => 'vendor.module', handleItemUpdated(params, extra) {} }) — method handle + command with capital first letter, or getMap().
• Vue: this.$Bitrix.PullClient.get().subscribe(...) in mounted, call the returned function in unmounted (bitrix-vue).
• Never use pull's global protobuf: since pull 26.100 it is a minimal build (load, parse, Root, Type gone). Bundle your own protobufjs without assigning globalThis.protobuf — pull reads globalThis.protobuf.roots['push-server'].

Mobile push

\Bitrix\Pull\Push::add($users, ['module_id' => 'vendor.module', 'push' => ['message' => 'Text', 'params' => [...]]]) — kernel entry point for push (drops command/params); or add push / pushParamsCallback to Event::add() to send both. CPullStack is legacy.

Badge refresh: Push::add($userId, ['module_id' => 'pull', 'push' => ['badge' => 'Y']]). CPushManager::sendBadges() was removed in pull 26.0 (fatal) and MobileCounter::send() is a no-op; the Push::add() call works on all versions.

Checklist

• module_id / command identical (lower-case module) in PHP and JS.
• Payload small, UTF-8; heavy data fetched on demand.
• Tags: CPullWatch::Add on render + extendWatch in JS.
• Subscriptions removed on unmount / destroy.
• Pull never used as a job queue.