Skip to content
Home/
/Banners

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.

Schemas
Operations

List banners for a contact

Request

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.

Security
bearerAuth
Path
idstringrequired

The unique identifier of a contact.

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"Preview"
Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:Preview
curl -i -X GET \
  'https://api.intercom.io/contacts/{id}/banners' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: Preview'

Responses

Successful response

Bodyapplication/json
typestring

String representing the object's type. Always has the value list.

Example:"list"
dataArray of objects(Banner)

An array of banners.

Response
{
  "type": "list",
  "data": [
    { … }
  ]
}