Triggering campaigns via their API

Contents

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 through either:

  • The Finder: Display field SID of the user object.
  • NXQL: Retrieve the sid field of the user objects, for instance:
    (select sid (from user))

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 references