Skip to content

Commit 658b314

Browse files
mapierceclaude
mapierce
and
claude
authored
Add Banners API (list + dismiss) to Preview (#539)
* Add Banners API (list + dismiss) to Preview spec Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Document Banners API action variant fields The action object only exposed `type`, so generated SDKs dropped the variant-specific fields. Add label/target (url), reaction_set (reaction), and tour_id/tour_url (product_tour) as documented optional properties matching the API response. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Type Banners API contact id and view_id path params as string Contact ids are alphanumeric strings (matching every other contacts endpoint in the spec), and view_id is already typed as string in the banner/banner_dismiss response schemas. The path params were integer, which would generate incorrect numeric-typed SDK parameters and reject real ids. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 0e34cbb commit 658b314

1 file changed

Lines changed: 269 additions & 0 deletions

File tree

‎descriptions/0/api.intercom.io.yaml‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7829,6 +7829,127 @@ paths:
78297829
message: Contact not found
78307830
schema:
78317831
"$ref": "#/components/schemas/error"
7832+
"/contacts/{id}/banners":
7833+
get:
7834+
summary: List banners for a contact
7835+
parameters:
7836+
- name: id
7837+
in: path
7838+
required: true
7839+
description: The unique identifier of a contact.
7840+
schema:
7841+
type: string
7842+
- name: Intercom-Version
7843+
in: header
7844+
schema:
7845+
"$ref": "#/components/schemas/intercom_version"
7846+
tags:
7847+
- Banners
7848+
- Contacts
7849+
operationId: listContactBanners
7850+
description: |
7851+
Returns the banners a contact currently matches, so you can display them on
7852+
surfaces outside the Messenger (native mobile apps, kiosks, embedded tools).
7853+
7854+
Each banner in the response includes a `view_id`. Use it to record a dismissal
7855+
with the dismiss endpoint. A returned banner is treated as shown: requesting
7856+
this endpoint records an impression for each banner returned, so call it at the
7857+
point you are about to display the banners, not speculatively.
7858+
responses:
7859+
'200':
7860+
description: Successful response
7861+
content:
7862+
application/json:
7863+
examples:
7864+
Successful response:
7865+
value:
7866+
type: list
7867+
data:
7868+
- type: banner
7869+
id: '486517'
7870+
view_id: '645719311'
7871+
title: Hi there
7872+
body: "<p class=\"no-margin\">Hi there!</p>"
7873+
style: inline
7874+
position: top
7875+
show_dismiss_button: true
7876+
action:
7877+
client_targeting:
7878+
created_at: 1780580493
7879+
schema:
7880+
"$ref": "#/components/schemas/banner_list"
7881+
'404':
7882+
description: Contact not found
7883+
content:
7884+
application/json:
7885+
examples:
7886+
Contact not found:
7887+
value:
7888+
type: error.list
7889+
request_id: 57055cde-3d0d-4c67-b5c9-b20b80340bf0
7890+
errors:
7891+
- code: not_found
7892+
message: User Not Found
7893+
schema:
7894+
"$ref": "#/components/schemas/error"
7895+
"/contacts/{id}/banners/{view_id}/dismiss":
7896+
post:
7897+
summary: Dismiss a banner for a contact
7898+
parameters:
7899+
- name: id
7900+
in: path
7901+
required: true
7902+
description: The unique identifier of a contact.
7903+
schema:
7904+
type: string
7905+
- name: view_id
7906+
in: path
7907+
required: true
7908+
description: The `view_id` of the banner to dismiss, as returned by the list banners endpoint.
7909+
schema:
7910+
type: string
7911+
- name: Intercom-Version
7912+
in: header
7913+
schema:
7914+
"$ref": "#/components/schemas/intercom_version"
7915+
tags:
7916+
- Banners
7917+
- Contacts
7918+
operationId: dismissContactBanner
7919+
description: |
7920+
Records that a contact has dismissed a banner. Dismissals are shared across
7921+
surfaces, so a banner dismissed through this endpoint will also stop appearing
7922+
in the web Messenger for that contact, and vice versa.
7923+
7924+
The request is idempotent: dismissing an already-dismissed banner succeeds and
7925+
returns the same response.
7926+
responses:
7927+
'200':
7928+
description: Successful response
7929+
content:
7930+
application/json:
7931+
examples:
7932+
Successful response:
7933+
value:
7934+
type: banner_dismiss
7935+
view_id: '645719311'
7936+
dismissed: true
7937+
schema:
7938+
"$ref": "#/components/schemas/banner_dismiss"
7939+
'404':
7940+
description: Banner view not found
7941+
content:
7942+
application/json:
7943+
examples:
7944+
Banner view not found:
7945+
value:
7946+
type: error.list
7947+
request_id: 57055cde-3d0d-4c67-b5c9-b20b80340bf0
7948+
errors:
7949+
- code: not_found
7950+
message: Resource Not Found
7951+
schema:
7952+
"$ref": "#/components/schemas/error"
78327953
"/contacts/bulk":
78337954
post:
78347955
summary: Bulk update contacts
@@ -32592,6 +32713,147 @@ components:
3259232713
type: string
3259332714
description: The body text of the note.
3259432715
example: "<p>Text for the note.</p>"
32716+
banner_list:
32717+
title: Banner List
32718+
type: object
32719+
description: A list of banners a contact currently matches.
32720+
properties:
32721+
type:
32722+
type: string
32723+
description: String representing the object's type. Always has the value
32724+
`list`.
32725+
example: list
32726+
data:
32727+
type: array
32728+
description: An array of banners.
32729+
items:
32730+
"$ref": "#/components/schemas/banner"
32731+
banner:
32732+
title: Banner
32733+
type: object
32734+
x-tags:
32735+
- Banners
32736+
description: A banner the contact currently matches, with the content and view
32737+
identifier needed to display and dismiss it.
32738+
properties:
32739+
type:
32740+
type: string
32741+
description: String representing the object's type. Always has the value
32742+
`banner`.
32743+
example: banner
32744+
id:
32745+
type: string
32746+
description: The id of the banner.
32747+
example: '486517'
32748+
view_id:
32749+
type: string
32750+
description: The id of the contact's view of this banner. Pass this to the
32751+
dismiss endpoint to record a dismissal.
32752+
example: '645719311'
32753+
title:
32754+
type: string
32755+
nullable: true
32756+
description: The banner's title. `null` when the banner has no title.
32757+
example: Hi there
32758+
body:
32759+
type: string
32760+
nullable: true
32761+
description: The banner's body content as HTML.
32762+
example: "<p class=\"no-margin\">Hi there!</p>"
32763+
style:
32764+
type: string
32765+
description: How the banner is displayed.
32766+
example: inline
32767+
position:
32768+
type: string
32769+
description: Where the banner is positioned.
32770+
example: top
32771+
show_dismiss_button:
32772+
type: boolean
32773+
description: Whether the banner should display a dismiss control.
32774+
example: true
32775+
action:
32776+
type: object
32777+
nullable: true
32778+
description: |
32779+
The action a contact can take on the banner, or `null` when the banner has
32780+
no action. The fields present depend on `type`:
32781+
`url` (`label`, `target`), `reaction` (`reaction_set`),
32782+
`email_collector`, or `product_tour` (`tour_id`, `tour_url`).
32783+
properties:
32784+
type:
32785+
type: string
32786+
description: The kind of action. One of `url`, `reaction`, `email_collector`,
32787+
or `product_tour`.
32788+
example: url
32789+
label:
32790+
type: string
32791+
nullable: true
32792+
description: For `url` actions, the label shown on the action link or button.
32793+
example: Learn more
32794+
target:
32795+
type: string
32796+
nullable: true
32797+
description: For `url` actions, the URL the contact is sent to.
32798+
example: https://www.intercom.com/pricing
32799+
reaction_set:
32800+
type: array
32801+
description: For `reaction` actions, the reactions a contact can choose from.
32802+
items:
32803+
type: object
32804+
properties:
32805+
index:
32806+
type: integer
32807+
description: The reaction's position in the set.
32808+
example: 0
32809+
unicode_emoticon:
32810+
type: string
32811+
description: The reaction's unicode emoji.
32812+
example: "\U0001F44D"
32813+
tour_id:
32814+
type: string
32815+
nullable: true
32816+
description: For `product_tour` actions, the id of the product tour to launch.
32817+
example: '12345'
32818+
tour_url:
32819+
type: string
32820+
nullable: true
32821+
description: For `product_tour` actions, the URL that launches the product tour.
32822+
example: https://app.intercom.com/tours/12345
32823+
client_targeting:
32824+
type: array
32825+
nullable: true
32826+
description: |
32827+
Reserved for future use. Always `null` in the current version — banners
32828+
that depend on client-side targeting rules (such as page URL or time on
32829+
page) are not returned by this endpoint.
32830+
items:
32831+
type: object
32832+
created_at:
32833+
type: integer
32834+
format: timestamp
32835+
description: The time the contact's view of this banner was created.
32836+
example: 1780580493
32837+
banner_dismiss:
32838+
title: Banner Dismiss
32839+
type: object
32840+
x-tags:
32841+
- Banners
32842+
description: The result of dismissing a banner for a contact.
32843+
properties:
32844+
type:
32845+
type: string
32846+
description: String representing the object's type. Always has the value
32847+
`banner_dismiss`.
32848+
example: banner_dismiss
32849+
view_id:
32850+
type: string
32851+
description: The id of the dismissed banner view.
32852+
example: '645719311'
32853+
dismissed:
32854+
type: boolean
32855+
description: Whether the banner view is dismissed.
32856+
example: true
3259532857
note_list:
3259632858
title: Paginated Response
3259732859
type: object
@@ -35368,6 +35630,13 @@ tags:
3536835630
description: Everything about your Away Status Reasons
3536935631
- name: Audiences
3537035632
description: Everything about your Audiences
35633+
- name: Banners
35634+
description: |
35635+
Retrieve the banners a contact matches and record dismissals, so you can display
35636+
banners on surfaces outside the Messenger (native mobile apps, kiosks, embedded
35637+
tools). These endpoints are part of the `Preview` API version and require an OAuth
35638+
token with the `read_write_users` scope. Requesting a contact's banners records an
35639+
impression for each banner returned, and dismissals are shared with the web Messenger.
3537135640
- name: Brands
3537235641
description: Everything about your Brands
3537335642
- name: Calls

0 commit comments

Comments
 (0)