Banner

A banner is a short text message Flatpeak places in your app. Your app asks for it from any screen, with the Connect session it holds. See the Banners guide. Hosted Connect shows banners on its own pages, and you build nothing for those. A banner request does not start the session or use it up. One session serves banner requests until it expires or the user taps a banner.

Preview
Code

A banner: a bolt icon, one line of text and a chevron

curl --request POST \
  --url https://connect.flatpeak.com \
  --header 'Content-Type: application/json' \
  --data '{
  "connect_session": "cos_6587fa4362341be5b524de3b",
  "route": "banner",
  "placement": "HOME"
}'

{
  "connect_session": "cos_6587fa4362341be5b524de3b",
  "route": "banner",
  "live_mode": true,
  "actions": [
    "CLICK",
    "DISMISS"
  ],
  "data": {
    "banner": {
      "id": "bnr_68b7d3f2a1c4e5d6b7f8a901",
      "text": "Switch to Smart Trading to earn up to €120 per kW of battery, every year.",
      "icon": "bolt",
      "background_color": "#0D9373",
      "text_color": "#FFFFFF",
      "end_time": "2026-06-30T23:59:59Z"
    }
  }
}

curl --request POST \
  --url https://connect.flatpeak.com \
  --header 'Content-Type: application/json' \
  --data '{
  "connect_session": "cos_6587fa4362341be5b524de3b",
  "route": "banner",
  "action": "CLICK",
  "action_context": { "banner_id": "bnr_68b7d3f2a1c4e5d6b7f8a901", "placement": "HOME" }
}'

curl --request POST \
  --url https://connect.flatpeak.com \
  --header 'Content-Type: application/json' \
  --data '{
  "connect_session": "cos_6587fa4362341be5b524de3b",
  "route": "banner",
  "action": "DISMISS",
  "action_context": { "banner_id": "bnr_68b7d3f2a1c4e5d6b7f8a901" }
}'

Request fields

Field	Description
`placement`	Required. The kind of screen the placeholder is on. See Placements.

Placements

Flatpeak reads placement with the session’s device_type to decide what to show. Use one placeholder per placement.

`placement`	The screen is about
`HOME`	The app’s main screen
`DEVICE`	One device: its status and controls
`SCHEDULE`	When the device runs: a charging schedule, a heating programme, a delayed start, automations
`INSIGHTS`	History, usage, costs or savings
`SETTINGS`	Account or device settings
`OTHER`	Anything else

Response fields

data.banner is null when there is nothing to show.

Field	Description
`id`	Flatpeak ID of the banner.
`text`	The message, in plain text, ready to display. Up to 120 characters.
`icon`	Font Awesome icon name, such as `bolt`. Map it to your own icon set, or leave it out. `null` when the banner has none.
`background_color`	Background color, as `#RRGGBB`. `null`: use your own banner style.
`text_color`	Text and icon color, as `#RRGGBB`. Its contrast with `background_color` is at least 4.5 to 1. `null`: use your own banner style.
`end_time`	When the banner ends, in UTC. Stop showing a cached copy at this time. `null` when it has no set end.

Actions

Action	Result
`CLICK`	The user tapped the banner. Send `action_context.banner_id` and `action_context.placement`, the placement it was tapped in. Connect answers with the next route. Offered only when the banner opens something.
`DISMISS`	The user closed the banner. Send `action_context.banner_id`, and Flatpeak stops returning it for the device.

After a tap

CLICK starts the session. Handle the response like any other Connect response:

Connect returns	Do
`session_redirect`	Send the user to `redirect_url`, as on any redirect
Any other route	Render that page, because the banner opened a Connect flow

Create a new session for the next banner request.

Errors

Error code	Description
`data_json_invalid`	Data does not conform to the JSON schema. Includes a missing or unknown `placement`.
`action_invalid`	Action is not available on this route, or is not permitted in the current state.

Platform

Tariffs

VPP