Creating an Announcement Flow

An Announcement Flow shows a banner across the top of your website – a message bar for launches, events, or campaigns. This article covers building the Flow and controlling whether the banner sits on top of your page or pushes your content down to make room for it. It is one of the Web Experience Flow types – see Creating a Web Experience Flow for how Flows are built, triggered, and previewed.

Table of Contents

• Before you begin
• The Show Announcement node
• How the banner can appear
• Set the placement in your snippet
• Shift a fixed or sticky header
• Worked example
• Style the banner from your own CSS
• Limitations

Before you begin

The Announcement Flow runs on the same Chili Piper install snippet as your other Web Experience Flows. There is no separate script to add.

You need:

• The Chili Piper install snippet already on the page or pages where the banner should appear;
• Admin access to edit that snippet (placement is set in code, not in the workspace UI);
• An Announcement Flow built in your Chili Piper workspace (see The Show Announcement node below).

The Show Announcement node

The Announcement Flow opens with the Show Announcement node, where you set the banner content:

• Body – the banner text;
• Call to Action – an optional button label, for example "See integration";
• Call to Action URL – where the visitor goes when they click the call-to-action. The URL must start with http:// or https://, or it will not open;
• Close button – the "Let visitors close the banner" toggle. When on, the banner shows an X so the visitor can dismiss it.

You can also set Styling – background and text colors – to match your site.

The node branches on how the visitor responds:

• CTA Engaged – the visitor clicks the call-to-action;
• Dismissed – the visitor closes the banner.

How the banner can appear

The banner has two placement modes:

• Overlay – the banner sits on top of your page content at the top of the viewport. Nothing on the page moves. Content behind the top of the banner is covered while the banner is visible;
• Push – the page moves down by the height of the banner, so the banner and your content sit side by side with no overlap.

Overlay is the behavior when you set no placement configuration. Push is opt-in.

Push is the right choice when the top of your page holds content a visitor needs to see – a fixed navigation bar, a logo, or a hero headline. On a page where the top area is decorative, overlay is simpler and needs no configuration.

Set the placement in your snippet

Placement is controlled by the announcementPlacement object inside window.ChiliChat.config. Add it to the config block of your existing install snippet:

<script>
  window.ChiliChat = {
    config: {
      workspaceId: 'your-workspace-id',
      tenantId: 'your-tenant-id',
      // ...your existing config...
      announcementPlacement: {
        mode: 'push',
      },
    },
  };
</script>

The announcementPlacement object takes these fields:

Note: Always set mode. The banner overlays the page unless mode is 'push' – so if you leave mode out, or set it to 'overlay', the pushPage and shiftElements settings have no effect. With no announcementPlacement object at all, the banner overlays. You only need this object when you want push behavior.

Shift a fixed or sticky header

Push mode moves your page's normal content down automatically. It does not move elements that are pinned to the viewport with CSS position: fixed or position: sticky – a navigation bar that stays at the top as the visitor scrolls, for example. Those elements ignore the page shift and end up behind the banner.

To move them, list their CSS selectors in shiftElements:

announcementPlacement: {
  mode: 'push',
  shiftElements: ['header', '.site-nav'],
},

Chili Piper moves each named element down by the banner height while the banner is visible, and returns it to its original position when the banner closes.

Point shiftElements at your own site's fixed elements. Inspect the page to find the right selector – a tag name such as header, a class such as .site-nav, or an ID such as #topbar all work.

⚠️ Warning: List only the fixed or sticky elements at the top of the page. Listing an element that already flows with the page (an element push mode moves anyway) shifts it twice.

Worked example

This is a complete, working configuration for a page with a fixed header. The page content moves down, and the fixed header moves with it:

<script>
  window.ChiliChat = {
    config: {
      workspaceId: 'your-workspace-id',
      tenantId: 'your-tenant-id',
      chatUrl: 'https://your-tenant.chilipiper.com/chat/widget/',
      announcementPlacement: {
        mode: 'push',
        shiftElements: ['header.header'],
      },
    },
  };
</script>

Replace workspaceId, tenantId, and chatUrl with your own values – they are the same ones already in your install snippet. The shiftElements: ['header.header'] selector matches a <header class="header"> element; replace it with the selector for the fixed header on your own site. To compare the two behaviors, change mode to 'overlay' and the banner returns to sitting on top of the page.

Style the banner from your own CSS

While the banner is visible, Chili Piper exposes its height and visibility to your page so you can react in your own stylesheet, whether or not you use push mode:

• A CSS custom property --chili-announcement-height on :root, set to the current banner height;
• A chili-announcement-visible class on the <html> element.

You can use these to make finer adjustments than shiftElements allows – for example, nudging a specific component only while the banner is showing:

html.chili-announcement-visible .my-floating-button {
  top: calc(20px + var(--chili-announcement-height));
}

Viewing logs

Each time the Announcement Flow runs for a visitor, it is recorded in Logs, alongside your Chat logs – including whether the visitor engaged the call-to-action or dismissed.

Limitations

• Placement is set in the install snippet, not in the Chili Piper workspace. Editing it requires access to your website's code;
• shiftElements moves elements you name by CSS selector. It does not detect fixed elements automatically – any pinned element you want moved must be listed;
• Push and overlay placement apply to the Announcement Flow only. The Offer and Scheduling Experiences appear as overlays and do not move page content;
• The banner content, targeting, and triggers are configured in your Chili Piper workspace. This article covers placement on the page only.