The API of Nexthink Engage lets you trigger campaigns programmatically, enabling their integration with third-party products, such as self-service portals or ticketing systems.
To trigger a campaign through the API, the following prerequisites apply:
The campaign targets users manually.
The campaign is published.
The campaign is triggered on behalf of a user whose profile includes Finder access with the option Access campaigns trigger API ticked.
Calling the Engage API
The Portal exposes the Engage API as a REST API under the URL:
In the URL, substitute
[portal.company.com] for the external DNS name of your Portal.
To trigger a manually targeted campaign, submit a POST request to the URL of the API (note that GET requests are not supported, returning a 404 error) with a JSON payload containing two parameters:
Identifier of the campaign
List of user identifiers
Example of the JSON payload of a request to the API of Engage:
"UserSids" : ["S-1-5-21-2281471460-584676728-3927365163-9716"]
A call to the Engage API is dispatched to all the Engines connected to the Portal and executed asynchronously, meaning that the call returns immediately after the request has been validated. Therefore, a successful response from the Portal does not guarantee that the selected users have received the campaign notification. For unsuccessful responses, see the list of error conditions below.
Obtaining the UIDs of campaigns and the SIDs of users
To get the UID of a campaign:
Log in to the Finder as a user with the permission to edit Engage campaigns.
Locate the desired campaign under the Campaigns section of the left-hand side menu.
Right-click the name of the campaign.
Select Export > Campaign Uid to clipboard.
Find the SID of users by either:
Displaying the SID field of the user object in the Finder.
Retrieving the sid field of the user objects via NXQL, for instance:
(select sid (from user))
Calling the GetSID API.
Send your POST request to the API of Engage with the following HTTP headers to specify JSON content and basic authentication:
Authorization: Basic [base-64(user:password)]
[base-64(user:password)] with the credentials (in base-64 encoding) of a Nexthink user who has the right to access the API for triggering campaigns.
In response to a request, the Portal may send one of the following answers if something goes wrong:
Bad request 400
Internal server error 500
Triggering a campaign through the Engage API is equivalent to triggering it manually from the Finder. Thus, after triggering a campaign via an API call, a subsequent API call can resend the campaign to the same users later, regardless of their previous responses, and even if they declined answering the campaign in the past.
Nonetheless, to prevent bothering users from accidental or repeated triggering, campaigns triggered through the Engage API apply the same quiet period as any other manually triggered campaign: two hours. During this time, a user that already received the campaign will not receive the same campaign again.
If a call to the Engage API triggers a campaign multiple times while a user is offline, the user receives the campaign just once.