A valid request URL is required to generate request examples{
"banners": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"slot": "<string>",
"kind": "text",
"dismissible": true,
"cta_url": "<string>",
"title": "<string>",
"body": "<string>",
"icon": "<string>",
"tone": "<string>",
"cta_label": "<string>",
"image_url": "<string>",
"image_alt": "<string>"
}
]
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}The banners on my screen
What the widget asks on a page load: which banner belongs in each slot, right now, for this person.
At most one banner per slot, decided in the database rather than by the client — highest priority, ties broken by newest. Every slot comes back in one response rather than one request per slot, so a page with a header strip and a billing notice costs one round-trip.
Four things have already been applied and none of them is the client’s to re-check: the banner is active, the current time is inside its window, this person is in its audience, and they have not closed it (unless it is not dismissible, in which case a previous close is ignored — that is what the field means).
Only the fields the kind actually carries are sent. A text banner has title, body, icon, tone and cta_label; an image banner has image_url and image_alt. cta_url is on both — it is the button’s destination on one and the whole picture’s link on the other. Branch on kind, never on a field being empty.
An anonymous session is not a special case: it has a contact like any other, so it sees the banners aimed at everybody and its dismissals stick for as long as that contact does. That is the case half this module is for — the maintenance notice on your signed-out landing page.
It needs a verified session, and the reason is the targeting: which banner is drawn depends on segment membership, so “does this external_id see the win-back strip” would be “is this person in the churn-risk segment”, asked by anybody who knows an id.
A valid request URL is required to generate request examples{
"banners": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"slot": "<string>",
"kind": "text",
"dismissible": true,
"cta_url": "<string>",
"title": "<string>",
"body": "<string>",
"icon": "<string>",
"tone": "<string>",
"cta_label": "<string>",
"image_url": "<string>",
"image_alt": "<string>"
}
]
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}