> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Widget Events
When certain events trigger in our UI, we send you a widget event. These events have the information you need to take action in your codebase in response to the event.
If integrating on mobile through a WebView, an alternative to standard widget events is required. See [Events in Mobile WebViews](#events-in-mobile-webviews) for more information.
It's your responsibility to add a listener to capture the properties of these triggered events and handle what happens next.
Don't use widget events for keeping data in sync between platforms. [Webhooks](/resources/webhooks) are a more reliable way of coordinating events between your servers and MX servers.
Widget events from MX have the following properties:
* The `mx` field that lets you filter out widget events coming from MX.
* The `type` field that identifies what the event represents at a high level.
* The `metadata` object field that has information related to the `type`.
Here’s an example integration that lets you listen to the events we send:
```js Example Integration theme={null}
function handleEvent(event) {
if (event.data.mx) {
// handle the mx post message using event.data.type and event.data.metadata.
}
}
window.addEventListener('message', handleEvent)
```
## Events in Mobile WebViews
MX has developed a URL-based updating mechanism to replace event messages that are available to other desktop implementations. You can capture this URL and use the information provided in it to build the necessary logic for coordinating application events.
When requesting a widget URL, you must include the `is_mobile_webview` field with a value of `true` in your request to access WebView event messages. If you don't want to handle these events, either set the `is_mobile_webview` value to `false` or don’t include this flag.
For the Micro Insights Widget, this URL is delivered via a `window.location = "mx://pulse/micro-carousel/cta?metadata="` call within the iFrame. You must capture this URL, parse out the path and query string, then JSON decode the metadata field. When decoded, the metadata contains the `beat_guid`, `beat_template`, and `user_guid` fields.
Not capturing this URL can cause the app to break.
## Application Events
### Widget Load
This event triggers when the widget loads.
```json theme={null}
{
"type": "mx/load",
"mx": true
}
```
### Widget Ping
This event keeps the widget session alive.
```json theme={null}
{
"type": "mx/ping",
"mx": true,
"metadata": {
"user_guid": "USR-123",
"session_guid": "ANS-123"
}
}
```
### Widget focusTrap
This event is triggered when popover content which traps the focus onto a particular element is opened or closed, but only in the case that no other popover content is already open. This event is triggered by some drawers, menu buttons, and modals.
```json theme={null}
{
"type": "mx/focusTrap",
"mx": true,
"metadata": {
"trapped": "true"
}
}
```
## Insights Widget Events
When displayed in the Insights Widget, some insights contain a call to action (CTA) that directs the user to the appropriate location by default, but others require you to send the user somewhere else to complete an action.
Here’s the process:
1. We detect that a user has selected a CTA on one of our insights that requires you to send the user somewhere outside of our widget.
2. We send you a UI event to let you know that a user has selected this CTA. Each event contains base metadata fields, and some events contain fields specific to individual insight templates. Refer to [Table 1](#table-1) for details about these fields.
3. The listener you create for this event sends the user to the appropriate location within your mobile app or website based on the details we sent through the UI event.
**Table 1. Event fields**
| Field | Type | Definition |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account. Defined by MX. |
| `account_name` | String | The human-readable name of the account. |
| `accounts` | Array | An array of account objects, each of which contains the `account_guid` and `account_name` described in this table. |
| `action` | String | The base metadata field that represents the scenario number within an insight. Most insights have only one scenario. For insights that require you to configure events for two or more possible scenarios, use the value `op_1` to indicate the first scenario, `op_2` to indicate the second scenario, and `op_3` to indicate the third scenario. For example, `"action": 'op_1'` indicates the first scenario of a multi-scenario insight. |
| `amount` | Integer | The amount the user would like to transfer to savings. |
| `beat_guid` | String | The base metadata field that represents the unique identifier for the insight. Defined by MX. |
| `beat_template` | String | The base metadata field that represents a short label for the insight being delivered. For example, `DesignateEmergencySavingsAccount`. |
| `destination_account_ids` | Array | The identifiers you define for the accounts eligible to transfer funds to. |
| `goal_guid` | String | The unique identifier for the goal. Defined by MX. This field returns an empty string for the **Start Saving for Emergencies** call to action. |
| `projected_overdraft_amount` | Integer | The projected amount the account will be overdrawn. |
| `source_account_ids` | Array | The identifiers you define for the accounts eligible to transfer funds from. |
| `total_amount_withdrawn` | Integer | The total amount withdrawn from all included accounts. |
| `user_guid` | String | The unique identifier for the user. Defined by MX. |
You must create listeners for each of the insight templates described in [Table 2](#table-2) that MX has enabled for you.
**Table 2. Templates and associated actions**
| Insight Template | When MX Sends This Event | What You Must Do | Base Metadata Fields |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| `DesignateEmergencySavingsAccount` | When the user selects the **Open Savings Account** CTA in the scenario where the user doesn't have a savings account. | Send the user to open a savings account. | `"action": 'op_1'` |
| `EmergencyFundWithdrawal` | When the user selects the **View my emergency savings** CTA or the **Transfer funds** CTA. The CTA that appears depends on if you have transfers for funds enabled. | When MX sends you this event, you must either send the user to view their emergency savings or create a transfer, depending on whether you have transfers for funds enabled or disabled. | `"action": 'op_1'` |
| `LowAccountBalance` | When the user selects the **Transfer funds** CTA. | Send the user to transfer funds to their low balance account. | `"action": 'op_1' account_guid` |
| `MonthlyEmergencyFundReview` (scenario 1) | When the user selects the **View my emergency savings** CTA. | Send the user to where they can view their emergency savings amount. | `"action": 'op_1'` |
| `MonthlyEmergencyFundReview` (scenario 2) | When the user selects the **Create new goal** CTA. | Send the user to the Goals Widget. | `"action": 'op_2'` |
| `MonthlyEmergencyFundReview` (scenario 3) | When the user selects the **Create transfer** CTA. | Send the user somewhere where they can transfer money. | `"action": 'op_3'` |
| `MonthlyObligationsStatus` | When the user selects the **Make a transfer** CTA. | Send the user somewhere where they can transfer money. | `"action": 'op_1'` |
| `MonthlySpendingPlanCelebration` | When the user selects the **Visit spending plan** CTA. | Send the user to the Spending Plan Widget. | `"action": 'op_1'` |
| `ReplenishSavings` | When the user selects the **Create Transfer** CTA. | Send the user to create a transfer to their savings account. | `"action": 'op_1' account_guid account_name accounts total_amount_withdrawn` |
| `SaveAnExtra100Dollars` | When the user selects the **Make A Transfer** CTA. | Send the user to where they can make a transfer. | `"action": 'op_1'` |
| `SavingsAccountDeposit` | When the user selects either the **View my emergency savings** or **Start saving for emergencies** CTA. | Send the user to the Goals Widget. From there the user can see their emergency savings goal or start an emergency savings goal. | `"action": 'op_1' account_guid goal_guid` (if available) `user_guid` |
| `SavingsMilestoneEmergencyFund` | When the user selects the **View my emergency savings** CTA. | Send the user to where they can view the Goals Widget. | `"action": 'op_1' account_guid goal_guid` `user_guid` |
| `SavingsOpportunityV2` (scenario 1) | When the user already has an eligible savings account to transfer money to and selects the **Transfer Funds** CTA. | Send the user to create a transfer to their savings account. | `"action": 'op_1' amount destination_account_ids` `source_account_ids` |
| `SavingsOpportunityV2` (scenario 2) | When the user doesn't have an eligible savings account to transfer money to and selects the **Open Savings Account** CTA. | Send the user to open a savings account. | `"action": 'op_2' amount` `source_account_ids` |
| `SetUpDirectDeposit` | When the user selects the **Set Up Direct Deposit** CTA. | When MX sends you this event, you must activate your direct deposit integration. | None. |
| `SpendingPlanCreatedCelebration` | When the user selects either the **Start Spending Plan** or **Visit Spending Plan** CTA. | Send the user to the Spending Plan Widget. | `"action": 'op_1'` |
| `SwitchDirectDeposit` | When the user selects the **Switch Direct Deposit** CTA. | When MX sends you this event, you must activate your direct deposit integration. | None. |
| `TransparentOverdraft` | When the user selects the **Transfer funds** CTA. | Send the user to transfer funds to their potentially overdrawn account. | `"action": 'op_1' destination_account_ids projected_overdraft_amount user_guid` |
| `UnifiedDepositEmergencyFund` (scenario 1) | When the user selects the **Start saving for emergencies** CTA. | Send the user to the Goals Widget. | `"action": 'op_1' account_guid goal_guid` `user_guid` |
| `UnifiedDepositEmergencyFund` (scenario 2) | When the user selects the **Transfer funds** CTA. | Send the user to a location where they can transfer funds to their emergency savings fund. | `"action": 'op_2' account_guid goal_guid` `user_guid` |
| `UnifiedDepositEmergencyFund` (scenario 3) | When the user selects the **View my emergency savings** CTA. | Send the user to the Goals Widget. | `"action": 'op_3' account_guid goal_guid` `user_guid` |
| `WeeklyNoSpendDays` | When the user selects the **Visit Spending Plan** CTA. | Send the user to the Spending Plan Widget, where they can see the widget as normal or onboard to it. | `"action": 'op_1'` |
## Micro Insights Widget Events
The Micro Insights Widget has two UI events.
One event triggers when the user selects the **View all** CTA in the Micro Insight Widget's header. If you have the header enabled, you must add a listener for this event that sends the user to the Insights Widget.
Here’s what this event looks like:
```json Example theme={null}
{
"type": "mx/pulse/micro-carousel/cta",
"mx": true,
"metadata": {
"user_guid": "USR-abcd-1234"
}
}
```
Another event is triggered when the user selects the **Learn more** CTA. You must add a listener for this event that sends the user to the Insights Widget.
In this event, the `metadata` includes a `beat_guid`. Use this GUID in your widget URL request for the Insights Widget so the specified insight shows at the top of the insights feed. See [Move Insight to Top of Feed](/products/experience/insights/integration-guides/integrate-insights-widget#move-insight-to-top-of-feed) for more info.
Here’s an example of what this event looks like:
```json Example theme={null}
{
"type": "mx/pulse/micro-carousel/cta",
"mx": true,
"metadata": {
"beat_guid": "BRT-2345-bcda",
"beat_template": "MonthlySpendComparison",
"user_guid": "USR-abcd-1234"
}
}
```