> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/best-practices/announcements-write-target-and-schedule-them.md). # Announcements: write, target, and schedule them How to time, target, and write announcements that end users read and act on rather than click through. An [announcement](/assistance/change-communication/announcements.md) is a push message delivered through the Assistant[^1]. It appears automatically when end users load a page, and it stays available in the Assistant's **Messages** tab afterward. When announcements are well-timed and well-targeted, they inform end users at the moment it matters. When they are overused, end users click through them without reading. The difference is restraint, targeting, and a clear reason for each one. ## How it works {% stepper %} {% step %} #### Decide whether an announcement is the right content type An announcement pushes information to the user. A guide teaches a process. A tooltip explains a specific element. Before creating an announcement, confirm the goal fits the format:
GoalRight content type
Inform end users about a change, update, or deadlineAnnouncement
Teach end users how to complete a processGuide (link to it from the announcement's call to action)
Explain what a specific field or button doesTooltip
Ensure correct data entry in a formValidator
If the announcement needs more than a short paragraph of text, the content probably belongs in a guide. Use the announcement to inform and link to the guide for detail. {% endstep %} {% step %} #### Write short, purposeful content End users decide quickly whether to read or dismiss, so keep every part of the announcement short. **Keep the headline specific.** "New feature: automated approval routing" tells the user what happened. "Important update" does not. **Keep the description short.** One to three sentences. State what changed, why it matters, and what to do next. If the announcement needs more than a short paragraph, link to a guide or external resource. **Define the goal.** Each announcement should either inform (the user reads and moves on) or call to action (the user clicks through to a guide, a link, or a page). Name the goal before writing, and match the content to it. **Add a call to action when one exists.** If a guide teaches the new feature, link to it. If a help article covers the change, link to it. Without a next step, the announcement ends at awareness. **Provide text in every application language.** Users dismiss announcements shown in a language they do not work in. {% endstep %} {% step %} #### Target and schedule carefully An untargeted, unscheduled announcement reaches everyone indefinitely. That is almost never the right choice. **Target with audiences.** An announcement about a feature only available to managers should target the manager audience[^2]. An announcement about a process only relevant to the finance team should target the finance audience. Untargeted announcements teach end users to ignore all of them. **Target with display rules.** If the announcement is relevant only on a specific page (the settings page, the reporting module), scope the display rule[^3] to those URLs. An announcement about report exports appearing on the dashboard is noise. **Trigger with Contextual Actions.** Instead of relying on audiences and display rules alone, a Contextual Action[^4] can trigger an announcement when a specific condition is met in real time, for example when a user lands on a page for the first time after a process change. This delivers the message at the moment it is most relevant rather than to everyone at once. See [Creating Contextual Actions](/assistance/in-app-guidance/creating-contextual-actions.md) for setup. **Schedule a start and end date.** An announcement about a deadline that has passed is clutter. Set the end date to the day the announcement stops being relevant. The announcement disappears automatically after the end date. **Limit the number of active announcements.** If multiple announcements are active at the same time, end users see a carousel and click through all of them to get back to work. Two to three active announcements is a practical maximum. If there are more, prioritize and stagger. {% endstep %} {% step %} #### Use announcements for recurring scenarios Most announcements fit one of three patterns: **Rollout announcement.** When going live with Userlane or launching new content on an application, announce it. Let end users know the Assistant exists, what it offers, and where to get additional support. A day later, send a follow-up announcement targeting users who have not started the first guide. This two-step pattern turns awareness into action. **New feature or change announcement.** When the underlying application adds a feature or changes a process, announce the change. Link to the guide that covers the new workflow. Add a beacon on the feature itself as a persistent reminder. The announcement reaches everyone. The beacon stays on the page for users who missed it. **Downtime or maintenance window.** When a scheduled downtime or maintenance window is coming, announce it in the affected application before it happens. State the date, time, expected duration, and what users should do in the meantime (save work, use a different system, wait). This prevents support tickets from users who encounter the outage without warning. {% hint style="info" %} **Do not delay communication until the change goes live.** If end users learn about a change by encountering it, the announcement is too late. Send the announcement before or at the moment of the change, not after. {% endhint %} {% endstep %} {% step %} #### Name categories to match the organization Userlane provides six announcement categories with default names: **New feature**, **Reminder**, **Must see Guide**, **News**, **Announcement**, and **Important**. These names can be changed in the portal under **Customize** to match how the organization communicates. Consistent category names help end users scan the **Messages** tab and find what matters. If the organization uses terms like "System update," "Action required," or "Training available," use those instead of the defaults. Each category has a color badge. Set colors in the portal under **Customize** > **Design** to match the organization's brand or severity conventions. {% endstep %} {% endstepper %} ## How to know it is working Check two things in the portal analytics: 1. **Reach rate.** What percentage of the targeted audience saw the announcement? A low reach rate may mean the display rule is too narrow or the audience does not match the users who visit the relevant page. It can also mean the schedule window was too short. 2. **Interaction rate.** If the announcement has a call to action, how often did users click it? A low interaction rate with a high reach rate means the content did not motivate action. Check whether the headline is specific enough and whether the call to action is clear. {% hint style="warning" %} **Caveat.** Once an end user dismisses an announcement, it does not reappear in the carousel for that user. The announcement remains in the Assistant's **Messages** tab, but most users will not revisit it there. Get the timing, targeting, and headline right before publishing. {% endhint %} ## Relevant articles {% content-ref url="/pages/JKbJ88H839VzRksHakFJ" %} [Announcements](/assistance/change-communication/announcements.md) {% endcontent-ref %} {% content-ref url="/pages/L1pTwQHW0TmAMoPDFhLR" %} [Creating Contextual Actions](/assistance/in-app-guidance/creating-contextual-actions.md) {% endcontent-ref %} {% content-ref url="/pages/TKBRGmMaapWk0xuF3XwG" %} [Audiences](/administration/audiences.md) {% endcontent-ref %} {% content-ref url="/pages/JAVVeLucPxhcVUV81Jw5" %} [Tooltips: choose, write, and place them well](/best-practices/tooltips-choose-write-and-place-them-well.md) {% endcontent-ref %} {% content-ref url="/pages/i1K1cNUetLC3hx3jInea" %} [Go-live: how to prepare for launch](/best-practices/go-live-how-to-prepare-for-launch.md) {% endcontent-ref %} ## FAQ
How many announcements should be active at the same time? Two to three is a practical maximum. More than that creates a carousel that end users click through without reading. If there are more messages to deliver, stagger them by scheduling start and end dates so only a few are active at any time.
Can an announcement be sent again to users who already dismissed it? No. Once an end user reaches the dismissed state for an announcement, it cannot be re-prompted through the carousel. To reach those users again, create a new announcement. The dismissed announcement remains visible in the Assistant's **Messages** tab until it expires or is unpublished.
What is the difference between an announcement and a Contextual Action? An announcement pushes a message to all users who match the audience and display rule, on a schedule. A Contextual Action triggers specific content (a guide, tooltip, or announcement) when a condition is met in real time. Use announcements for broad communication. Use Contextual Actions for behavior-triggered delivery.
Can an announcement link to an external page instead of a guide? Yes. The call-to-action button supports two modes: linking to a Userlane guide or opening an external URL. Use external links for release notes, help center articles, or internal documentation that lives outside Userlane.
[^1]: The Assistant is the end-user-facing panel where guides, search, announcements, and help resources are accessible inside the application. [^2]: An audience is a reusable group of users defined by rules about their attributes, behavior, or tag interactions. Audiences control who sees which content and can also filter analytics. [^3]: A display rule is a URL-based condition that controls which pages content appears on. [^4]: A Contextual Action triggers content automatically when a defined condition is met. Conditions can be based on URL, page state, or user attributes. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.userlane.com/best-practices/announcements-write-target-and-schedule-them.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.