# Interventions

Interventions represent the actions a user needs to do in order to enable a blocked capability on their device.

There are some situations where a specific device’s capability depends on an action taken by the end user. For instance, some Volkswagen ID vehicles will only be smart charging capable after a specific software update.

In cases like this, we will return an intervention ID as part of the capabilities object in one of the asset endpoints, like [**Get vehicle**](https://developers.enode.com/api/reference#getVehicle). You can use the intervention ID to fetch additional information about how to resolve the intervention using our [**Get Intervention**](https://developers.enode.com/api/reference#getIntervention) endpoints.

You can display this information directly in your app to help the end-user resolve the intervention and unblock the device's capability.

## Capabilities and interventions

![An illustration showing the three steps of intervention resolution: 1. Detecting a blocked capability, 2. Resolving intervention by following the resolution description, 3. Capability is no unblocked](https://developers.enode.com/images/interventions/enode-interventions-intro.png)

**Capabilities** represent Enode’s ability to fetch information, perform actions, or utilize features such as [**smart charging**](https://developers.enode.com/docs/smart-charging/introduction) for a given device. Depending on the device model or version, specific capabilities may not be accessible. These cases can be split into two categories:

- **Missing capabilities** are permanently missing from a device, e.g. a specific vehicle model missing an onboard GPS will never be able to transmit a location
- **Blocked capabilities** are inherently supported by a device model but require user action to be unblocked for a user’s specific device, e.g. a vehicle that has an onboard GPS and can start transmitting a location if the user enables the setting in their vehicle’s infotainment system

**Interventions** represent the user actions required to unblock a **blocked capability**. For each connected device, every blocked capability contains one or more interventions that must be resolved to unblock the capability (surfaced e.g. via our [**Get vehicle**](https://developers.enode.com/api/reference#getVehicle) endpoint).

### Additional information

- A specific device can have multiple blocked capabilities and, therefore, multiple interventions tied to it
- Two unique devices of the same model can have different combinations of blocked capabilities based on factors such as user settings, software versions and more
- Multiple capabilities can be unblocked by a single intervention
  - Example: Some vendors require a service subscription to transmit any data from the device, and once the user signs up for the subscription, multiple capabilities will be unblocked
- Interventions may appear on blocked capabilities throughout the connection lifecycle
  - Example: Some interventions will appear directly after the user links their device through Link UI, while others may appear later
- A capability can become blocked based on an event and, therefore, be assigned an intervention at any given time
  - Example: By a user disabling a setting in the vendor app or on the device itself
- If a device lacks a certain capability but does not have an assigned intervention, the capability is categorized as missing. However, it can be re-categorized as a blocked capability and be assigned an intervention in the future if Enode detects a new resolution
- Intermittently impaired capabilities that require no user action are not considered blocked and won't include interventions
  - Example: Some vehicle models may temporarily disable location data transmission while in motion
- An intervention may be brand-specific, or may apply to all brands. In the latter case, the fields `vendor`, `vendorType` and `brand` will all be null.

Brands overview: You can refer to the [brands overview](https://developers.enode.com/brands) for a list of known supported models and their inherent capabilities. This overview also lists the currently known interventions grouped by vendor.

## Accessing interventions via our API

Interventions are surfaced via the `capabilities` object returned by fetching a specific device. In most cases, this means there is a two-step process to receive and react to interventions:

1. Fetch a device, e.g. via **[Get vehicle](https://developers.enode.com/api/reference#getVehicle)**. Detect a blocked capability with an intervention ID attached to it.
2. Query the **[Get intervention](https://developers.enode.com/api/reference#getIntervention)** endpoint to fetch detailed information about this intervention.

### 1. Detect a blocked capability

We recommend checking for blocked capabilities every time you fetch a device, as a change in status can be unpredictable at times.

Sample response from **[Get vehicle](https://developers.enode.com/api/reference#getVehicle)**.

```json
{
  "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
  "vendor": "AUDI",
  "capabilities": {
    "location": {
      "isCapable": false,
      "interventionIds": [
        "394939c1-70bd-42d9-881f-24d15e3610e2"
      ]
    },
    { ... }
  },
  { ... }
}
```

### 2. Fetch intervention information

This contains general information as well as more detailed information about the resolution of the intervention.

Sample response from **[Get intervention](https://developers.enode.com/api/reference#getIntervention)**.

```json
{
    "id": "394939c1-70bd-42d9-881f-24d15e3610e2",
    "vendor": "AUDI",
    "vendorType": "vehicle",
    "introducedAt": "2022-11-18T00:00:00",
    "brand": "Audi",
    "domain": "Device",
    "resolution": {
        "title": "Enable the \"Car finder\" connect service",
        "description": "For remote access to your vehicle's location, it's necessary to enable the *Car finder Connect Service*. Follow these steps to activate it:\n\n1. From your car's infotainment system, navigate to Settings.\n2. Select Privacy.\n3. Choose *Car finder*.",
        "access": "Physical",
        "agent": "User"
    }
},
```

Drop-in descriptions: The resolution title and description can be presented directly in your app, as described in the [Displaying resolutions](https://developers.enode.com/docs/interventions#presenting-interventions-to-users) section. The description is formatted using Markdown and written to give simple and clear instructions to the end-user on how to resolve an intervention.

### List all interventions

If you wish to query a list of all interventions, you can use the **[List interventions](https://developers.enode.com/api/reference/#listInterventions)** endpoint. It returns all interventions the system currently supports broken down by vendor, including all brand-agnostic interventions.

### Localization

Both intervention endpoints accept a `language` query parameter to request a translated resolution title and description. For a full list of supported languages, please refer to the [API reference](https://developers.enode.com/api/reference#getIntervention).

## Intervention types

Interventions typically relate to the vendor user account, device settings, or software versions. While most of them can be resolved by the user remotely or on the device itself, some need third-party involvement. These possible combinations are described through three pieces of structured data.

### Domain

![An illustration showing an example of an intervention resolution title for each type of domain](https://developers.enode.com/images/interventions/enode-interventions-domain.png)

The `domain` key describes whether the intervention relates to the device itself or the vendor user account used to access the device.

| Value | Description |
| --- | --- |
| `Account` | The intervention is related to the vendor user account, e.g. the account the user created when setting up the Tesla app and paired their Tesla vehicle to. |
| `Device` | The intervention is related to the specific device, e.g. a user’s Tesla vehicle. |

### Access

![An illustration showing an example of an intervention resolution title for each type of access](https://developers.enode.com/images/interventions/enode-interventions-access.png)

The `access` key describes **where** the intervention can be resolved.

| Value | Description |
| --- | --- |
| `Remote` | The intervention can be resolved remotely, either via the vendor app or web service, e.g. via the Tesla app. |
| `Physical` | The intervention needs to be resolved physically on the device itself, e.g. in the Tesla infotainment system. |

### Agent

![An illustration showing an example of an intervention resolution title for each type of agent](https://developers.enode.com/images/interventions/enode-interventions-agent.png)

The `agent` key describes **who** can resolve the intervention.

| Value | Description |
| --- | --- |
| `User` | The intervention can be resolved by the user themselves, following the steps described by the description value, e.g. enabling a setting in the Tesla app. |
| `ThirdParty` | The intervention has to be resolved by a third party, e.g. a mechanic at the Tesla dealership. |

## Presenting interventions to users

The Interventions API is universally designed to fit many presentation and delivery methods, with the goal of making it as easy as possible to integrate it into your current app structure and design. Below are some considerations that could be worth taking into account when implementing interventions into your product.

### Showing relevant interventions only

The `capabilities` object returned for any given device does not regard the use case you are building for. We recommend filtering out any interventions that might be irrelevant to using your product. For example, discarding interventions relating to the smart charging capability if your product only reads vehicle information.

### Displaying resolutions

![An illustration showing a possible UI treatment to display an intervention notification in an app](https://developers.enode.com/images/interventions/enode-interventions-display.png)

Because of the nature of [blocked capabilities](https://developers.enode.com/docs/interventions#capabilities-and-interventions), and that interventions can appear at any given time, we recommend finding a fixed place to present these to your users. For example, this could be contextually presented in the device detail view if any relevant interventions are present. Alternatively, interventions could be presented in close proximity to the related functionality in your app (e.g. smart charging settings).

Interventions that make it to your UI are inherently important, and to catch the user’s attention, you could consider explicitly mentioning the functionality that is blocked by the missing capability (e.g. “Additional steps are required to enable smart charging”) and using prominent visual aids such as strong colors to highlight their importance. To extend this, you could consider utilizing push messages if interventions are not resolved within a certain time span.

Some interventions can be resolved by visiting Link UI. Please refer to the [Relinking documentation](https://developers.enode.com/docs/link-ui/relinking) for more information.

![An illustration showing a possible UI treatment to display the resolution description in an app](https://developers.enode.com/images/interventions/enode-interventions-display_full.png)

Intervention descriptions are formatted as [Markdown](https://www.markdownguide.org/), allowing you to render them with rich formatting matching your design language. Since the resolution descriptions vary in length and can have links, we recommend using the intervention title in minified contexts and allowing the user to tap to open the intervention resolution in a fullscreen or modal view.

Markdown syntax elements: The currently utilized Markdown formatting features are [bold](https://www.markdownguide.org/basic-syntax/#bold), [ordered lists](https://www.markdownguide.org/basic-syntax/#ordered-lists), [unordered lists](https://www.markdownguide.org/basic-syntax/#unordered-lists) and [links](https://www.markdownguide.org/basic-syntax/#links), but this could be extended in the future.

### Handling multiple interventions

![An illustration showing a possible UI treatment to display multiple intervention notifications, stacked in an app](https://developers.enode.com/images/interventions/enode-interventions-multiple_display.png)

After discarding irrelevant interventions [through filtering](https://developers.enode.com/docs/interventions#showing-relevant-interventions-only), there could still be cases where multiple interventions need to be resolved to unlock the wanted functionality. To handle this case gracefully and to avoid overwhelming the user, we recommend focusing on one intervention at a time and utilizing it as an entry to all interventions (e.g. as a list view of all interventions). We would also consider allowing the user to solve one intervention at a time, allowing them to navigate your app freely between each intervention is resolved (as opposed to locking them into a longer flow for solving all interventions).

To present the most important interventions first, you can consider sorting interventions by the following parameters.

1. **Occurrence** — If e.g. one intervention unlocks multiple capabilities, you could consider presenting this first
2. **Friction** — Focusing on lower friction interventions first, e.g. interventions that can be solved by the user before interventions that need third-party involvement or remotely before physically

### Enriching with metadata

![An illustration showing a possible UI treatment of how to enrich an intervention resolution view by using the intervention meta data](https://developers.enode.com/images/interventions/enode-interventions-metadata.png)

To extend the title and description of the resolution, you can utilize the structured data to build more context for your user. This could be done by mapping the `domain` or `access` keys to supporting icons or category tags, mentioning that the steps can be resolved easily by the user themselves via the `agent` key, or highlighting if the intervention requires the user to make an appointment with a third-party (for vehicles, this is typically their dealership).

You can also utilize the blocked capability to enrich the intervention, such as mapping a blocked location capability to a pin icon.