Triggering campaigns via their API

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:

Name	Description
CampaignUid	Identifier of the campaign
UserSids	List of user identifiers

Example of the JSON payload of a request to the API of Engage:

{
 "CampaignUid": "3a6ae8fe-3e00-40f8-a061-5d8b3ba6d8e9",
 "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:

1. Log in to the Finder as a user with the permission to edit Engage campaigns.

2. Locate the desired campaign under the Campaigns section of the left-hand side menu.

3. Right-click the name of the campaign.

4. 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:

Error type	HTTP code	Cause
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

• Triggering a campaign manually

• GetSID API

RELATED REFERENCE

• Types of campaigns