Table of Contents
Ticket Widget: Overview
A ticket widget is a block of dynamic content shown inside the ticket. An external provider supplies the content, and the ticket view displays it. Unlike the old Dynamic Content, a widget is not only a display. The user can click through it, move between steps and answer quick questions, all without leaving the ticket.
In short: a widget shows information about a ticket, lets the user navigate and act on it, and replaces itself in place with the next response.
What a widget can do
- Show information. Display facts about a contact, an order or an asset. See Ticket Widget: Description Type.
- List things and open them. Show a list of items. Each item can open more detail inside the widget, or link to another page. See Ticket Widget: List Type.
- Page through results. There is no built-in pagination, but leading and secondary buttons, such as "Previous" and "Next", can simulate it. The provider keeps the page number in
state. See Ticket Widget: Actions. - Show progress. Report the steps of an automation or task, and update itself while it runs. See Ticket Widget: Progress Type and Ticket Widget: Refresh Modes.
- Ask for a quick decision. When an automation needs a human choice, offer a few options. The answer goes to the provider, which decides what happens next. See Ticket Widget: Form Type.
- Offer quick actions. Give agents buttons and dropdowns so they can act without leaving the ticket.
A widget can behave like a small application inside the ticket: a list, a detail view, a back button, a decision, a progress report.
How it works
- The ticket loads, and the client requests the widget content from the provider's API.
- The provider returns structured content, not HTML.
- The client renders it.
- When the user presses an action or an item, the client requests new content from the URL it gives, and replaces the widget in place. This is the same idea as Adaptive Cards.
- Every request carries
formandstate, including requests from list items and progress steps. The provider's API can stay stateless.
A link is the one exception to "no navigation": it opens a page.
For what the provider receives, see Ticket Widget: How the Widget Is Requested. For how data travels between steps, see Ticket Widget: Form Results and State Across Steps.
Content types
Type | Use it to | Article |
Description | Show key and value facts about an entity | |
List | Show items that can be plain, links or actions | |
Progress | Show step-by-step status | |
Form | Ask for a quick decision, single or multiple choice |
All types share a title, icon, Markdown description and colours, described in Anatomy and Styling. They also share up to three actions, described in Actions.
What's new compared with Dynamic Content
Dynamic Content came from a single API and was built for a single purpose: displaying content. It could not navigate or act. It returned blocks (description, list, progress), the first three were shown, and there were no actions or refresh.
Dynamic Content will be replaced by ticket widgets. This starts with the TECH portal (agent facing). The client portal (contact facing) follows when it is rewritten.
Widgets add:
- Actions. Leading, secondary and primary, as buttons, dropdowns or split buttons. See Actions.
- Form type. Single-select and multi-select questions. See Form Type.
- Interactive items. List items and progress steps can be clickable, and each can have a "…" dropdown. See List Type and Progress Type.
- Navigation inside the widget. Items, pages and steps replace each other in place.
- Refresh. Content can update itself on a timer or on change. See Refresh Modes.
- State.
stateandformcarry information between steps. See Form Results and State Across Steps. - Conditions. A widget can appear only when the ticket matches the conditions you set.
- One fetch API per widget.
Availability
- Per portal. A widget is registered for a portal, agent or client. For now, only the agent portal is supported. The client portal follows its rewrite.
- Conditions. Each widget has conditions that decide when it appears. Only the conditions the product offers can be used, such as queue, status, priority and office hours.
- Limit. Up to 3 matching widgets are shown per ticket, ranked by order.
Conditions are a helper. They are not the only way to vary content. Your API receives the ticket and the reader (see How the Widget Is Requested), so it can return different content depending on ticket properties or on who is reading. You could also register one list widget that shows only what the reader may see, and let them click through to explore.
Designing with widgets
The types and features combine in many ways. How to combine them is up to the integrator or developer. To use them well, understand how each part works.
A few examples of the range:
- A list of related assets, each opening a detail view with a back button.
- A decision from an automation, followed by a progress report.
- A paged list of results, using leading and secondary buttons to move between pages.
Widgets can also work with AI and automation, if you build that integration. The widget does not provide AI. It gives the integration a place to show progress and ask for a decision. See Building a Multi-Step Request for a complete example.
Reading map
I want to... | Read |
Understand the layout, icon and colours | |
Add buttons and navigation | |
Know what the provider receives | |
Show facts about an entity | |
Show a list that opens detail or links out | |
Show the status of a process | |
Ask for a quick decision | |
Keep a widget up to date | |
Carry answers and data between steps | |
Understand errors and fix problems | |
See a complete example |
