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().

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.