Table of Contents

Ticket Widget: Control When a Widget Refreshes

Helpdocs Admin Updated by Helpdocs Admin

A ticket widget doesn't have to stay frozen after it first loads. You can have it update on its own while a process is running, update when someone edits the ticket, or only update when the page is reloaded. This article explains how to choose, and how to set it up in your provider's response.

This article is part of the Ticket Widget category, which covers the other widget topics.

Refresh behaviour is controlled by two properties in the widget response:

  • refreshMode: the rule for when the widget refreshes.
  • refreshIntervalSec: how often, in seconds, for modes that use a timer.

Each refresh is a new request to your widget's API, and the response replaces the widget in place. Both properties are available on every widget type (description, list, progress and form). Choose the longest interval that still keeps the content current, because every refresh adds load on your provider.

The four modes at a glance

Mode

Refreshes when…

Typical use

manual

The page is fully reloaded, or the user clicks refresh

Forms, static or rarely changing content

timer

The interval elapses

Progress tracking, time-dependent content

on-change

The ticket changes (lastModifiedAt changes)

Content driven by ticket properties

timer-or-change

The interval elapses or the ticket changes

Time-dependent content that also reacts to ticket edits

Mode details

manual

The widget only refreshes when the page is fully reloaded or the user clicks the refresh button. Nothing happens automatically.

Use it for:

  • Forms, where an automatic refresh could interrupt what the user is entering.
  • Static content that rarely changes.

timer

The widget refreshes automatically every refreshIntervalSec seconds.

Use it for:

  • Progress tracking. While any step is still pending a state change, keep returning timer. When the process finishes, switch to manual or on-change, since there's nothing left to poll for.
  • Time-dependent content, such as office-hours messages. Refreshing every 5 to 15 minutes is usually enough. Avoid very short intervals for this kind of content.

on-change

The widget refreshes when the ticket changes, detected by a change in the ticket's lastModifiedAt. There is no polling interval.

Use it for content that depends on ticket properties, for example:

  • The ticket owner and the owner's associated account. If either changes, the widget shows different content.
  • The queue.
  • Any other ticket property, such as status or priority.

timer-or-change

This combines both triggers. The widget refreshes when the interval elapses or when the ticket changes, whichever comes first.

Use it when content depends on time but can also be affected by ticket edits. For example, an automation is running and the widget shows its progress. If someone changes a ticket property, the automation may discard the earlier progress and queue a new task. The widget should reflect that straight away instead of waiting for the next timer tick.

Interval rules

refreshIntervalSec applies to timer and timer-or-change.

  • Minimum: 30 seconds
  • Maximum: 15 minutes (900 seconds)
  • Not specified: if you choose a timer mode and omit refreshIntervalSec, the maximum of 15 minutes is used.
  • Out of range: a value outside the allowed range is adjusted to the nearest limit. For example, 5 is treated as 30, and 3600 is treated as 900.

Defaults and enforced behaviour

  • No refreshMode specified: the widget uses manual.
  • Form widgets: manual is always enforced, to avoid interrupting the user's input. Any other value you return for a form widget is overridden.

Choosing a mode

Ask what makes the content go stale:

  1. Nothing, or very rarely → manual.
  2. The passage of time (a process running, office hours) → timer.
  3. A change to the ticket → on-change.
  4. Both time and ticket changes → timer-or-change.

Tips

  • Use the longest interval that still feels current.
  • Stop polling when there's nothing left to wait for. Switch a finished progress widget away from timer.
  • Don't rely on timers for forms. They are forced to manual anyway.

How did we do?

Ticket Widget: Form Type

Ticket Widget: Form Results and State Across Steps

Contact