# Banners

Retrieve the banners a contact matches and record dismissals, so you can display
banners on surfaces outside the Messenger (native mobile apps, kiosks, embedded
tools). These endpoints are part of the `Preview` API version and require an OAuth
token with the `read_write_users` scope. Requesting a contact's banners records an
impression for each banner returned, and dismissals are shared with the web Messenger.


## List banners for a contact

 - [GET /contacts/{id}/banners](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/banners/listcontactbanners.md): Returns the banners a contact currently matches, so you can display them on
surfaces outside the Messenger (native mobile apps, kiosks, embedded tools).

Each banner in the response includes a view_id. Use it to record a dismissal
with the dismiss endpoint. A returned banner is treated as shown: requesting
this endpoint records an impression for each banner returned, so call it at the
point you are about to display the banners, not speculatively.

## Dismiss a banner for a contact

 - [POST /contacts/{id}/banners/{view_id}/dismiss](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/banners/dismisscontactbanner.md): Records that a contact has dismissed a banner. Dismissals are shared across
surfaces, so a banner dismissed through this endpoint will also stop appearing
in the web Messenger for that contact, and vice versa.

The request is idempotent: dismissing an already-dismissed banner succeeds and
returns the same response.

## List banners for a contact

 - [GET /contacts/{id}/banners](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/contacts/listcontactbanners.md): Returns the banners a contact currently matches, so you can display them on
surfaces outside the Messenger (native mobile apps, kiosks, embedded tools).

Each banner in the response includes a view_id. Use it to record a dismissal
with the dismiss endpoint. A returned banner is treated as shown: requesting
this endpoint records an impression for each banner returned, so call it at the
point you are about to display the banners, not speculatively.

## Dismiss a banner for a contact

 - [POST /contacts/{id}/banners/{view_id}/dismiss](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/contacts/dismisscontactbanner.md): Records that a contact has dismissed a banner. Dismissals are shared across
surfaces, so a banner dismissed through this endpoint will also stop appearing
in the web Messenger for that contact, and vice versa.

The request is idempotent: dismissing an already-dismissed banner succeeds and
returns the same response.