# Integrating chatbots using Nexthink REST APIs

Without integration, chatbots cannot retrieve device or user information. This leads to incomplete responses, employee frustration, and unnecessary service desk escalations.

By integrating with Nexthink APIs, your chatbot can:

* Provide data-driven chatbot responses
* Retrieve real-time device and employee context using NQL queries
* Diagnose issues in real time within the conversation
* Trigger associated actions to remediate problems instantly

## How does chatbot integration work using Nexthink API features? <a href="#integratingchatbotswithnexthink-chatbotintegrationflow" id="integratingchatbotswithnexthink-chatbotintegrationflow"></a>

Nexthink chatbot-API integrations adhere to the following structure:

* The chatbot system controls the interaction with employees, including conversation content and logic.
* Nexthink provides APIs that the chatbot calls during conversations:
  * NQL API - Retrieve context-related data from Nexthink.
  * Remote Action API - If applicable, trigger a remediation remote action.

{% hint style="info" %}
Optionally, configure Nexthink **Outbound connectors** export large amounts of data using [Data Exporters](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/data-exporters) and [Webhooks](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/webhooks). Use exported event data to trigger proactive chatbot conversations.
{% endhint %}

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-1ba37a5ab3f5498046a13fcf276e7897070d027d%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Chatbot flow using Nexthink API technologies

Find below the chatbot flow with tasks to achieve issue resolution via Nexthink APIs.

| Required task or step - Chatbot                                                 | API integration approach                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ol><li><strong>Authenticate communication</strong></li></ol>                   | **API credentials** - token collection via the API.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| <ol start="2"><li><strong>Identify employee or device</strong></li></ol>        | <p><strong>NQL API</strong> - Retrieve specific username and/or device identifier data.</p><p><br>(Optional) <strong>Data Export-</strong> Export essential data, such as user/device names and last seen dates, to regularly enrich the chatbot-integrated CMDB system.</p>                                                                                                                                                                                                                                                                                                                                                                                                                |
| <ol start="3"><li><strong>Diagnose the user device</strong></li></ol>           | **NQL API** - Retrieve employee device information (e.g., device health, application metrics) to narrow down remediation actions to follow.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| <ol start="4"><li><strong>Remediate device issues</strong></li></ol>            | **Remote Action API** - Trigger remediation action on target device based on diagnosis, or upon user request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| <ol start="5"><li><strong>Follow up and confirm fix</strong></li></ol>          | **NQL API** - Retrieve the results of the remote action execution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| <ol start="6"><li><strong>Proactive identification of issues</strong></li></ol> | <p><a href="../../configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/data-exporters">Data exporters</a> (optional) - Export all users and devices potentially impacted by the issue to solutions like a data lake.<br>This enables proactive communication of issues to employees.</p><p><br><a href="../../configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/webhooks">Webhooks</a> (optional)—Send notifications when specific events or alerts are triggered, allowing chatbots to proactively identify impacted employees.</p> |

***

## Configuring Nexthink API features to support chatbot integration <a href="#integratingchatbotswithnexthink-prerequisites" id="integratingchatbotswithnexthink-prerequisites"></a>

Before implementing API calls within the chatbot's service layer, as a Nexthink [administrator](https://docs.nexthink.com/platform/user-guide/administration/account-management/roles#roles-administration), conduct the following preliminary configurations in Nexthink.

{% stepper %}
{% step %}

#### **Plan the API integration for a specific chatbot** <a href="#integratingchatbotswithnexthink-planning" id="integratingchatbotswithnexthink-planning"></a>

1. Verify that your API usage complies with Nexthink's API usage limits. Refer to the [Nexthink developer portal](https://developer.nexthink.com) documentation for more information.
2. Map how to match users between your chatbot solution and Nexthink.
   * Nexthink Collector compiles username, SID, and UPN, if activated.
   * [Connector for Microsoft Entra ID](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/inbound-connectors/connector-for-microsoft-entra-id-azure-ad) provides additional data for mapping, including user email, if activated in your Nexthink instance.
     {% endstep %}

{% step %}

#### Set up API credentials in Nexthink <a href="#integratingchatbotswithnexthink-credentials" id="integratingchatbotswithnexthink-credentials"></a>

1. Configure [API credentials](https://developer.nexthink.com/docs/api/api-credentials) to secure calls from the chatbot to your Nexthink tenant and outbound connections—data exporters and webhooks.\
   Ensure that you have the following permissions activated in your API credentials:
   * **NQL API**
   * **Remote Actions API**
2. Optionally, configure [connector credentials](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/connector-credentials) if you plan to use outbound integrations.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-a36e484ad9f168147ba0dc23ed7919eef94ea738%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Create Nexthink content for contextual data retrievals and remediation actions—for API calls <a href="#integratingchatbotswithnexthink-preparingcontent" id="integratingchatbotswithnexthink-preparingcontent"></a>

1. [Create NQL queries](https://docs.nexthink.com/platform/solutions/chatbots/chatbot-use-cases#creating-nql-api-queries) within the Nexthink user interface to define the **NQL API** calls from the chatbot. Typically, required queries include:
   * Query to retrieve devices and their basic information for a given user.
   * Query to retrieve ad-hoc diagnostic information for a given user or device.
   * Query to retrieve the status and outputs of a remote action.
2. Create remote actions configured for **API** triggers. Alternatively, install a large set of preconfigured remote actions from the Nexthink Library that you can use and adapt.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-858a5e89d04d70bfa2975dab41960381d80e7352%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

***

## Using pre-built content to implement REST API calls within chatbot's service layer

Once you configured all necessary API features listed above within Nexthink, move on to implementing the REST API calls within the chatbot's service layer—explained in detail in a [end-to-end use case](https://docs.nexthink.com/platform/solutions/chatbots/chatbot-use-cases#step-3-implement-api-calls-within-the-chatbots-service-layer).

To help you get started, find below query samples and pre-built content that you can use and adapt when configuring your chatbot orchestration and logic.

{% hint style="info" %}
You can implement these examples using a chatbot design similar to that depicted in the referenced use case, assuming that you identified the device name beforehand.
{% endhint %}

### Generic NQL query samples for chatbot tasks <a href="#chatbotusecases-generalqueries" id="chatbotusecases-generalqueries"></a>

As part of configuring chatbot orchestration and logic using REST APIs, you need to set up generic queries to perform two basic tasks below that are useful across all chatbot integrations with Nexthink:

<details>

<summary>NQL query for retrieving device of a user</summary>

Query ID: #get\_device\_basic\_infos - matching based on the `username`

```
devices during past 7d
| with session.events past 7d
| where user.name == $username
| list collector.uid, device.name, 
  operating_system.platform, operating_system.name, 
  hardware.type, hardware.manufacturer, last_seen
| sort last_seen desc
```

You can adjust the where clause `| where user.name == $username` for use with alternative approaches, for example:

* If you know the user UPN: `| where user.upn == $upn` (requires the UPN to be activated at collector level)
* If you know the user email address: `| where user.ad.email_address == $email` (requires the Azure AD connector to be activated and the email field synced)
* If you know the device name: `| where device.name == $device_name`

Adjust the timeframe if you want to consider devices on which the user has been active during a period of time other than 7 days.

Replace both `past 7d` clauses with the desired timeframe, up to the maximum data retention period in your Nexthink tenant, which is by default 30 days.

</details>

<details>

<summary>NQL query for retrieving the status and outputs of remediation remote actions</summary>

Query ID: #get\_remote\_action\_result

```
remote_action.executions past 24h
| where request_id == $request_id
| list request_id, device.name, remote_action.name, 
  status, status_details, outputs
```

</details>

### Pre-built content for implementing chatbot REST API calls to address common issues <a href="#chatbotusecases-microsoftoutlookissues" id="chatbotusecases-microsoftoutlookissues"></a>

Use pre-built content—including NQL queries for diagnosis, remote actions and remediation logic—to configure your chatbot integration to diagnose, solve, and confirm the fix status of the following common issues:

<details>

<summary>Address <strong>Microsoft Outlook</strong> issues</summary>

Diagnose issues that cause Microsoft Outlook to malfunction for an employee.

<table><thead><tr><th width="170">Type</th><th>Content</th></tr></thead><tbody><tr><td>Platforms</td><td>Microsoft Windows</td></tr><tr><td>Data-collection remote actions</td><td><p>Schedule data collection remote actions:</p><ul><li>Get Microsoft Outlook online</li><li>Get Microsoft Outlook plugin crash details</li></ul></td></tr><tr><td>NQL query</td><td><p>Query ID: #diagnose_outlook_issues</p><pre><code>devices
| where device.name == $device_name
| include package.installed_packages
| where package.name in ["Microsoft Office", "Microsoft 365"]
| where package.version != "16.*"
| compute outdated_office_packages = package.name.count()
| list collector.uid, device.name,
  remote_action.get_outlook_plugin_crash_details_windows.execution.outputs.CrashedPluginList,
  remote_action.get_outlook_online_windows.execution.outputs.IsOnline,
  remote_action.get_outlook_online_windows.execution.status,
  boot.days_since_last_full_boot, outdated_office_packages
</code></pre></td></tr><tr><td>Remediation list</td><td><ol><li><strong>IF</strong> <code>remote_action.get_outlook_online_windows.execution.outputs.IsOnline</code> = <code>"No"</code> and <code>remote_action.get_outlook_online_windows.execution.status</code> = <code>"success"</code><br><strong>THEN</strong> Run remediation remote action <strong>Set Outlook online</strong></li><li><strong>IF</strong> <code>remote_action.get_outlook_plugin_crash_details_windows.execution.outputs.CrashedPluginList</code> != <code>"["-"]"</code><br><strong>THEN</strong> Run remediation remote action <strong>Set Outlook plugins</strong></li><li><strong>IF</strong> <code>device.boot.days_since_last_full_boot</code> > <code>10</code><br><strong>THEN</strong> Recommend the employee restart their machine.</li><li><strong>IF</strong> <code>outdated_office_packages</code> = <code>"1"</code><br><strong>THEN</strong> Run remediation remote action <strong>Repair Office 365</strong></li><li>Additional generic remediation: Run remediation remote action <strong>Repair Outlook OST Problem</strong></li></ol></td></tr></tbody></table>

</details>

<details>

<summary>Address <strong>Microsoft OneDrive</strong> issues</summary>

Diagnose issues related to Microsoft OneDrive and repair OneDrive when the system detects issues.

<table><thead><tr><th width="169">Type</th><th>Content</th></tr></thead><tbody><tr><td>Platforms</td><td>Microsoft Windows</td></tr><tr><td>Data-collection remote action</td><td><p>Schedule data collection remote actions:</p><ul><li>Get OneDrive status</li></ul></td></tr><tr><td>NQL query</td><td><p>Query ID: #diagnose_onedrive_issues</p><pre><code>devices
| where device.name == $device_name
| list collector.uid, device.name,
  remote_action.get_onedrive_status.execution.outputs.OneDriveStatus
</code></pre></td></tr><tr><td>Remediation list</td><td><ol><li><p><strong>IF</strong> <code>remote_action.get_onedrive_status.execution.outputs.OneDriveStatus</code> contains one of the following:</p><ol><li><code>OneDrive is not installed</code></li><li><code>OneDrive is installed but not running</code></li><li><code>OneDrive environment variable does not exist</code></li><li><code>OneDrive folder is not present</code></li></ol></li></ol><p><strong>THEN</strong> Run remediation remote action <strong>Repair OneDrive</strong></p></td></tr></tbody></table>

</details>

<details>

<summary>Address <strong>slow PC</strong> issues</summary>

Diagnose a wide range of typical issues resulting in slowness on the endpoint.

<table><thead><tr><th width="170">Type</th><th>Content</th></tr></thead><tbody><tr><td>Platforms</td><td>Microsoft Windows</td></tr><tr><td>Data-collection remote actions</td><td><p>Schedule data collection remote actions:</p><ul><li>Get GPO startup impact</li><li>Get startup impact</li></ul></td></tr><tr><td>NQL query</td><td><p>Query ID: #diagnose_slow_pc_issues</p><pre><code>devices during past 7d 
| where name == $device_name
| include device_performance.events during past 24h
| compute free_space = system_drive_free_space.avg() / 1000000000
| include package.installed_packages
| where package.name in ["*Microsoft Office*", "*Microsoft 365*"]
| where package.version != "16.*"
| compute outdated_office_packages = package.name.count()
| list collector.uid, device.name, free_space,
  boot.days_since_last_full_boot,
  outdated_office_packages,
  remote_action.get_startup_impact_windows.execution.outputs.HighImpactCount,
  remote_action.get_gpo_startup_impact_windows.execution.outputs.UserGpoAppliedTimeInSeconds,
  remote_action.get_gpo_startup_impact_windows.execution.outputs.UserGpoDCDiscoveryInSeconds
</code></pre></td></tr><tr><td>Remediation list</td><td><ol><li><strong>IF</strong> <code>device.boot.days_since_last_full_boot</code> > <code>10</code><br><strong>THEN</strong> Recommend the employee restart their machine.</li><li><strong>IF</strong> <code>free_space_GB</code> &#x3C;= <code>6</code><br><strong>THEN</strong> Run remediation remote action <strong>Disk cleanup</strong></li><li><strong>IF</strong> <code>remote_action.get_startup_impact_windows.execution.outputs.HighImpactCount</code> > 0<br><strong>THEN</strong> Run remediation remote action <strong>Disable Application from Startup menu</strong> using the value of <code>remote_action.get_startup_impact_windows.execution.outputs.HighImpactApplications</code> to disable high-impact applications</li><li><strong>IF</strong> <code>remote_action.get_gpo_startup_impact_windows.execution.outputs.UserGpoAppliedTimeInSeconds</code> + <code>remote_action.get_gpo_startup_impact_windows.execution.outputs.UserGpoDCDiscoveryInSeconds</code> > 10<br><strong>THEN</strong> Run remediation remote action <strong>Update Group Policy settings</strong></li><li><strong>IF</strong> <code>outdated_office_packages</code> = <code>"1"</code><br><strong>THEN</strong> Run remediation remote action <strong>Repair Office 365</strong></li></ol></td></tr></tbody></table>

</details>

{% hint style="warning" %}
All remote actions listed above should be installed from the [Nexthink Library](https://docs.nexthink.com/platform/user-guide/nexthink-library) and require prior configuration:

* Data-collection remote actions must have an active **Schedule**-type trigger and a collection schedule set to hourly or daily, depending on the required frequency.
* Remediation remote actions must have an active **API**-type trigger.
  {% endhint %}

***

RELATED TOPIC

* [chatbot-use-cases](https://docs.nexthink.com/platform/solutions/chatbots/integrating-chatbots-with-nexthink/chatbot-use-cases "mention")
* [#optionally-make-the-workflow-available-in-nexthink-spark](https://docs.nexthink.com/platform/user-guide/workflows/creating-workflows#optionally-make-the-workflow-available-in-nexthink-spark "mention")