# Request (/docs/settings/mqtt/topics/request)



<Callout title="Tip" type="info">
  Webview Kiosk also utilises the request-response pattern for manual query
  of device information states.<br />
  This pattern is explained in:

  * [EMQX — MQTT 5: Request–Response](https://www.emqx.com/en/blog/mqtt5-request-response)
  * [HiveMQ — MQTT 5 Essentials Part 9: Request–Response Pattern](https://www.hivemq.com/blog/mqtt5-essentials-part9-request-response-pattern/)
</Callout>

## 1. Settings [#1-settings]

### 1.1. Topic Name [#11-topic-name]

All [global variables](/docs/settings/mqtt/#3-global-variables) are supported.
For example,

```js
wk/${USERNAME}/${APP_INSTANCE_ID}/request
```

**Default:**

```js
wk/request
```

### 1.2. Quality of Service (QoS) [#12-quality-of-service-qos]

Quality of Service (QoS) ensures different message delivery guarantees
in case of connection failures.

**Default:** At Most Once (0)

### 1.3. Retain Handling [#13-retain-handling]

Control whether Webview Kiosk should receive existing
retained messages when subscribing.

**Default:** Do Not Send (2)

### 1.4. Retain as Published [#14-retain-as-published]

Controls whether retained messages from the broker keep their original
retained flag when delivered to the subscriber.

**Default:** false

## 2. Payloads [#2-payloads]

In addition to the
[Shared Subscribe Payload Properties](/docs/settings/mqtt/topics/#3-shared-subscribe-payload-properties),
the following properties can be provided for all requests:

<table>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>responseTopic</code>
      </td>

      <td>
        string 

        <i>(optional)</i>
      </td>

      <td>
        Topic the server should publish responses to. Global variables are supported.

        If empty, the response will be published to the configured *response
        topic name* in settings
        (default: <code>wk/response/$\{RESPONSE\_NAME}</code>).

        This is provided as a fallback, and will be overridden by MQTT's V5 metadata
        (<a href="https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901066" className="underline text-blue-600">3.1.3.2.6. Response Topic</a>)
        if both are provided.
      </td>
    </tr>

    <tr>
      <td>
        <code>correlationData</code>
      </td>

      <td>
        string 

        <i>(optional)</i>
      </td>

      <td>
        Data to correlate the response with the request. In Webview Kiosk

        This is provided as a fallback, and will be overridden by MQTT V5 metadata
        (<a href="https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901067">3.1.3.2.7. Correlation Data</a>)
        if both are provided.

        In Webview Kiosk, the correlation data must be a `UTF-8` string.
      </td>
    </tr>
  </tbody>
</table>

### 2.1. Get Status [#21-get-status]

Retrieves device and app states.

Example payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "requestType": "get_status"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```jsonc
    {
      "requestType": "get_status",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],

      // NOTE: these can be specified as metadata in MQTT v5
      "responseTopic": "wk/${APP_INSTANCE_ID}/${RESPONSE_TYPE}",
      "correlationData": "arbitrary-data-12345"
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.2. Get Settings [#22-get-settings]

Retrieves configured user settings of your choosing by providing an array of
setting keys inside the payload data. This array could look like:

```json
[
  "device.rotation",
  "appearance.theme"
]
```

The values for the following settings will not be returned for security reasons:

* `device.custom_auth_password`
* `mqtt.connection.password`

If no setting keys are provided, all valid settings will be returned.

#### 2.2.1. Parse as Array [#221-parse-as-array]

For the the following setting keys, which are stored as strings and delimited
by a new line (`\n`):

1. `web_content.website_blacklist`
2. `web_content.website_whitelist`
3. `web_content.website_bookmarks`

You can optionally use the object notation below with the `parseAsArray` property:

```jsonc
[
  // Before
  "web_content.website_blacklist",

  // After
  {
    "key": "web_content.website_blacklist",
    "parseAsArray": true
  }
]
```

which will return them as an array of strings split by new lines.

#### 2.2.2. Evaluate Variables [#222-evaluate-variables]

For the following setting keys:

1. `mqtt.connection.client_id`
2. `mqtt.publish.event.topic`
3. `mqtt.publish.response.topic`
4. `mqtt.subscribe.command.topic`
5. `mqtt.subscribe.settings.topic`
6. `mqtt.will.topic`
7. `mqtt.will.payload`

You can optionally use the object notation below with the `evaluateVariables` property:

```jsonc
[
  // Before
  "mqtt.connection.client_id",

  // After
  {
    "key": "mqtt.connection.client_id",
    "evaluateVariables": true
  }
]
```

which will interpolates global variables with static values such as `APP_INSTANCE_ID` or `USERNAME`.

#### 2.2.3. Example payload [#223-example-payload]

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Advanced">
      Advanced
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "requestType": "get_settings"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Advanced">
    ```jsonc
    {
      "requestType": "get_settings",
      "data": {
        "settings": [
          "device.rotation",
          "appearance.theme",
          {
            "key": "web_content.website_blacklist",
            "parseAsArray": true
          },
          {
            "key": "mqtt.connection.client_id",
            "evaluateVariables": true
          },
          "web_browsing.allow_refresh"
        ]
      },
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],

      // NOTE: these can be specified as metadata in MQTT v5
      "responseTopic": "wk/${APP_INSTANCE_ID}/${RESPONSE_TYPE}",
      "correlationData": "arbitrary-data-12345"
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.3. Get System Info [#23-get-system-info]

Retrieves device and app system information.

Example payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "requestType": "get_system_info"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```jsonc
    {
      "requestType": "get_system_info",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],

      // NOTE: these can be specified as metadata in MQTT v5
      "responseTopic": "wk/${APP_INSTANCE_ID}/${RESPONSE_TYPE}",
      "correlationData": "arbitrary-data-12345"
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.3. Get Launchable Packages [#23-get-launchable-packages]

Retrieves a list of package names corresponding to applications that
can be opened on the device.

In the `data` property, you can optionally specify:

* `filterLockTaskPermitted`: (boolean) if true, only return launchable packages that are
  permitted for [Lock Task Mode](https://developer.android.com/work/dpc/dedicated-devices/lock-task-mode)

Example payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "requestType": "get_launchable_packages"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```jsonc
    {
      "requestType": "get_launchable_packages",
      "data": {
        "filterLockTaskPermitted": true
      },
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],

      // NOTE: these can be specified as metadata in MQTT v5
      "responseTopic": "wk/${APP_INSTANCE_ID}/${RESPONSE_TYPE}",
      "correlationData": "arbitrary-data-12345"
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### 2.4. Get Lock Task Packages [#24-get-lock-task-packages]

Retrieves the list of lock task packages using
[DevicePolicyManager#getLockTaskPackages](https://developer.android.com/reference/android/app/admin/DevicePolicyManager#getLockTaskPackages\(android.content.ComponentName\)).

This list is not limited to only launchable packages.

If neither Device Owner nor Dhizuku privileges were granted to Webview Kiosk, an empty list will be returned.

Example payload:

<CodeBlockTabs defaultValue="Minimal">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Minimal">
      Minimal
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Full">
      Full
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Minimal">
    ```json
    {
      "requestType": "get_lock_task_packages"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Full">
    ```jsonc
    {
      "requestType": "get_lock_task_packages",
      "messageId": "example-001",
      "targetInstances": ["070219ea-d0cb-11f0-9e76-5a93ec0e6f90"],
      "targetUsernames": ["user-001"],

      // NOTE: these can be specified as metadata in MQTT v5
      "responseTopic": "wk/${APP_INSTANCE_ID}/${RESPONSE_TYPE}",
      "correlationData": "arbitrary-data-12345"
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>