Send Notifications to Luma Users from other Applications

APIs are great interfaces to integrate different applications. An API exposes the functionality and features to the external applications. Luma provides an inbound API that allows external applications to interact with Luma, which can be used for scenarios such as notifying the bot users after completion of a service or request.

This article deals with the following areas:

The Luma Notification API is used by Admins to notify Luma users from an external system. For example, a user asks Luma to reset their password. An external ITSM system completes the password reset process and informs the user through Luma that they can now login. By using the Luma Notification API, the external ITSM system can send a message to the user through a Luma chat. 

Notify Users

In this article, let us take an example of Luma notifying the users about a Microsoft Exchange server outage. In such case, the following API needs to be called, by providing the required URL, parameters and headers, in order to receive the response.

URL Format

Specify the API URL provided below:

Parameters

Specify the parameters involved in your call. In this example, to notify Luma users, the following parameters need to be specified.

Headers

The Post method supports the following request and response headers applicable to this action.

Following are the sample headers that you will encounter the most:

• Authorization: Bearer {{API_TOKEN}}
  • Example API_TOKEN: Specify the alphanumeric access token available on Manage Tenant Information page. 
• Content-Type: application/json

Request

Using the above elements namely URL, parameters and headers, create the request to notify the Luma users. In this example, let us use a JSON request as specified below. 

{

  "recipients" : {

    "contacts" : ["jake@seviceaide.com"],

    "roles" : [""]

  },

  "botExternalID" : "",

  "template_type" : "",

  "template_id" : "",

  "responseType" : "TEXT",

  "message" : "Maintainance is in progress. Will update you once it is done.",

  "repeat" : ""

} 

To send an inbound message to Luma users using an REST API (for example, Postman), include the following details:

• Contacts: Include the login ID of the users to whom the inbound message needs to be sent. You can send the message to multiple recipients by separating the login IDs using comma (for example, sam@gmail.com, judy@gmail.com).
• Roles: Include the role code of the users to whom the inbound message needs to be sent. The following user roles and their respective codes are available:
  • - 1 (to be used to send the message to Administrator)
  • - 2 (to be used to send the message to Developer)
  • - 3 (to be used to send the message to Analyst)
  • - 4 (to be used to send the message to Self-service user)

  • - 5 (to be used to send the message to Guest user)

    Note

    To send message to all the Luma users, include "0'' in the contacts and leave the roles blank.

• Template ID: Include the template ID which needs to be used while sending the message to the users. To know the template ID in the Skills Builder, on the Settings page, click Notification Templates tab. Search for the notification template ID from the list and include it.
• Response Type: Specify the response type to be sent to the users - text, image or card.
• Message: Include the message which needs to be sent to the users. If a variable message is used in the Skills Builder notification template, the message included in the REST API is displayed in the user's chat window. Similarly, if the message is provided in the Skills Builder notification template, then it overrides any message details included in the REST API, and displays the Skills Builder message to the users.

Response

Once the Post request is executed, a response is received in the specified format. A sample JSON response for a payload can look like this.

{

    "timestamp": 1534497594873,

   "status": 200,

    "message": "OK",

    "errors": [],

    "data": "success"

}

Status Codes

Status codes convey the results of your request. The following status code applies to the Post API.

If the request is a success with status code 200, then Luma notifies the users regarding the outage; else, Luma prompts the users to check the errors in the request and retry after fixing the errors.

View Luma Notification

Once the notify users API request is successful, the following message is sent to all the Luma users.