Skip to main content

Polling & Refresh

This page describes how the widget keeps the message thread up to date once a conversation exists. Read it when tuning refresh timing or debugging "why didn't new messages appear yet?".

Prerequisite: an active conversation​

Nothing is polled until the widget has a conversation — created by sending the first message, or restored from sessionStorage for that account. With no conversation, polling does not start.

The poll timer (fetchIntervalMs)​

  • Setting: settings.fetchIntervalMs, default 10000 ms. Clamped to 500–60000 ms. See Settings.
  • Mechanism: while the panel is open, the widget refetches the latest page on each tick.
  • Tab visibility: if the document is not visible on a given tick, that tick is skipped. The timer keeps running and resumes work when the tab is visible again.

When the timer starts and stops​

EventBehaviour
Chat panel opensAn immediate fetch (if a conversation exists), then polling starts.
Panel minimized or collapsedPolling stops. (This is not the header end-chat X flow.)
Successful sendThe cache is cleared, messages refetch, and polling resumes (the panel is still open).
End-chat (X) startsPolling stops while the close request runs.
End-chat failsPolling resumes so the thread keeps updating.
End-chat succeedsThe panel collapses and polling stops.
Teardown (destroy())Polling stops as part of cleanup.
info

While the panel is minimized or collapsed, no polling runs. Reopening the panel triggers an immediate fetch plus the interval again.

Returning to a background tab​

When the document becomes visible again — if the panel is open and a conversation exists — the widget fetches once immediately, rather than waiting for the next interval tick.

When do new messages appear?​

Inbound messages (e.g. agent replies) show up when all of the following are true:

RequirementWhy
Panel openPolling stops when minimized/collapsed.
Tab visiblePoll ticks are skipped while the document is hidden.
A conversation existsNothing is polled until at least one message has been sent.

Typical delay: up to fetchIntervalMs (default 10 s) between ticks. Opening the panel or returning to the tab can refetch sooner.

Refresh caching​

To avoid redundant network traffic, the widget briefly caches the latest conversation page and coalesces duplicate in-flight requests. During polling, a background refresh still runs so newer server messages merge in without waiting for the cache to expire. This cache is internal and not configurable; tune refresh behaviour via settings.fetchIntervalMs.