Triggering Campaigns Via Their API (classic)
Overview
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.
Prerequisites
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:
https://[portal.company.com]/api/campaign/v1/trigger
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:
CampaignUid
Identifier of the campaign
UserSids
List of user identifiers
Example of the JSON payload of a request to the API of Engage:
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.
HTTP headers
Send your POST request to the API of Engage with the following HTTP headers to specify JSON content and basic authentication:
Content-type: application/json
Authorization: Basic [base-64(user:password)]
Replace [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.
Error conditions
In response to a request, the Portal may send one of the following answers if something goes wrong:
Access Denied
Unauthorized 401
Authentication error
Forbidden 403
User with insufficient permissions to run the specified campaign
Validation error
Bad request 400
Invalid JSON
Invalid encoding
Invalid Content-type
Invalid or missing UID of campaign
Invalid or missing SIDs of users
Unknown or not published campaign
The campaign does not target users manually
Too many user SIDs specified (limited to 12 000 users)
Unknown error
Internal server error 500
Undefined internal error
Quiet period
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.
RELATED TASKS
RELATED REFERENCE
Last updated