From 14e2a016a7f0b943f8cec81037ea2bf250baf7a4 Mon Sep 17 00:00:00 2001 From: Mariana Caramori Date: Mon, 7 Sep 2026 18:31:52 -0300 Subject: [PATCH] Document both button shapes on the survey.button.clicked webhook A Microsurvey click now resolves a Question's answer Button as well as a page Button, so the published schema needs to name `question_id` as the discriminator rather than showing only the page shape. Co-authored-by: Chameleon dev --- mintlify-docs/webhooks/outgoing.mdx | 42 ++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/mintlify-docs/webhooks/outgoing.mdx b/mintlify-docs/webhooks/outgoing.mdx index cdc3282..87e2b05 100644 --- a/mintlify-docs/webhooks/outgoing.mdx +++ b/mintlify-docs/webhooks/outgoing.mdx @@ -41,7 +41,7 @@ When receiving a webhook from Chameleon you should: | `survey.completed` | [example](#example-survey-all) | [Action](#schema-actions-campaign), [Microsurvey](/apis/surveys), [Step](/apis/steps), [User Profile](/apis/profiles) | Sent when the Microsurvey is completed with the Step the user completed | | `survey.exited` | [example](#example-survey-all) | [Action](#schema-actions-campaign), [Microsurvey](/apis/surveys), [Step](/apis/steps), [User Profile](/apis/profiles) | Sent when the Microsurvey is exited with the Step the user exited | | `survey.snoozed` | [example](#example-survey-snooze) | [Action](#schema-actions-snooze), [Microsurvey](/apis/surveys), [Step](/apis/steps), [User Profile](/apis/profiles) | Sent when the Tour is exited on Step configured to snooze (re-display the Step at a later time). | -| `survey.button.clicked` | [example](#example-tour-button-clicked) | [Microsurvey](/apis/surveys), [Step](/apis/steps), [Button](/apis/buttons), [User Profile](/apis/profiles) | Sent when the Tour is exited with the Step the user exited | +| `survey.button.clicked` | [example](#example-tour-button-clicked) | [Microsurvey](/apis/surveys), [Step](/apis/steps), [Button](#schema-button-survey-button-clicked), [User Profile](/apis/profiles) | Sent when the Tour is exited with the Step the user exited | | `embed.started` | [example](#example-embed-all) | [Action](#schema-actions-campaign), [Embed](/apis/tours), [Step](/apis/steps), [User Profile](/apis/profiles) | Sent when the Embed is started; includes the first Step in the payload | | `embed.completed` | [example](#example-embed-all) | [Action](#schema-actions-campaign), [Embed](/apis/tours), [Step](/apis/steps), [User Profile](/apis/profiles) | Sent when the Embed is completed; includes the Step the user completed | | `embed.exited` | [example](#example-embed-all) | [Action](#schema-actions-campaign), [Embed](/apis/tours), [Step](/apis/steps), [User Profile](/apis/profiles) | Sent when the Embed is exited; includes the Step the user exited | @@ -175,6 +175,44 @@ Each Webhook can contain an `action` key in the payload. It will contain context | `results_count` | integer | Number of source results that were used to generate this answer | | `references` | array<string> | Array of reference URLs or sources that support the provided answer | + +### Button (`survey.button.clicked`) +A Microsurvey click can come from a Button on the page or from a Button that answers a Question, so the `button` object of a `survey.button.clicked` payload has **two shapes**. + +**`question_id` is the discriminator.** It is present only on a Question's answer Button. Branch on it rather than on `tour_action`, which an answer Button does not reliably carry — a subscriber switching on that field sees `undefined` for a Question answer. + +| Shape | Identified by | Properties to expect | +|-----------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| Page Button | no `question_id` | `tour_action`, `position`, `additional_actions` and the `style_*` properties — the full [Button](/apis/buttons) schema | +| Question Button | `question_id` is present | `question_id`, `order`, `enabled`, plus `score_type` on an `nps` Question. `tour_action` and `position` are normally absent — see below | + +Both shapes carry `id` and `text`. `order`, `enabled` and `additional_actions` appear on both, but on an answer Button `order` is its place within its Question and `enabled` is whether that answer is offered. + +`tour_action`, `position` and the `style_*` properties are not meaningful on an answer Button, because a Question lays out and colours its own Buttons. A `rating` and an `nps` answer Button never carries them — its Buttons come from the Question's preset and cannot be edited. A `multibutton` answer Button is edited through the same panel as a page Button, so one can carry them without their having any effect. Either way, `question_id` is what tells the two shapes apart. + +Only a `multibutton`, `rating` or `nps` Question answers through Buttons. A `text`, `choice`, `multi_choice` or `dropdown` answer sends no `survey.button.clicked` webhook. + + +#### Question Button properties +| Property | Type | Description | +|---------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `question_id` | ID | The Chameleon ID of the Question this Button answers. Its presence is what identifies the object as a Question's Button | +| `order` | integer | The place of this Button within its Question, starting from `0` | +| `enabled` | boolean | Whether this Button is offered. Only meaningful for a `multibutton` Question — a `rating` and an `nps` always present their full preset set | +| `score_type` | string | Only on an `nps` Question: which bucket this Button's score falls in. One of `detractor` (scores 0-6), `passive` (7-8) or `promoter` (9-10). Absent on every other Question type | + +#### Example question button +```json +"button": { + "id": "5fb6e4ab8af58a00073f0d9a", + "text": "9", + "order": 9, + "enabled": true, + "question_id": "5fb6e4ab8af58a00073f0d91", + "score_type": "promoter" +} +``` + ### Payload Examples @@ -503,6 +541,8 @@ Every Button that is clicked in a Tour / Microsurvey will send a webhook to this > The key will be "tour", "survey", or "embed" depending on the Experience type. +> For `survey.button.clicked` the `button` object has [two shapes](#schema-button-survey-button-clicked) — a Question's answer Button carries `question_id` and no `tour_action`. + ```json { "id": "5fb70dcbc39330000325a819",