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 users through Luma, which can be used for scenarios such as notifying 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 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 system can send a message to the user through a Luma chat. 

Notifying Users

In this article, let us take an example of Luma notifying the users about a Microsoft Exchange server outage. In this 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}}

  Note

  If the 'Bearer' text is not included, then 401 invalid token error response is received.

  • 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" : "This is to notify you that the Microsoft exchange server is down due to internal maintenance and will be up at 9 PM (PST).",

  "repeat" : ""

} 

To send an inbound message to Luma users using a 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: You can specify the role of the user to whom the message needs to be displayed. However, if you want to display the message to all the users of a particular Tenant with a specific role, then include the role code of the users. For example, if you type "0'' in the contacts and '-1' in the roles, then the message is displayed to all the Administrators of the Tenant. 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)

    Note

    To send message to all Luma users, include "0'' in the contacts and leave the roles blank. However, if the contact information is provided, then including the Role is optional.

• Template ID: Include the template ID which needs to be used while sending the message to the users. To find an existing template ID, go to Skills Builder and on the Settings page, click Notification Templates tab. Find the correct notification template and the related notification template ID from the list.
• 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 you wish to use a Skills Builder notification template, then the variable (@request.message) should be used in the notification template. 

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"

}

Timestamp specifies the date and time of the message being displayed in UNIX or epoch format.

Status specifies the results of your request. For more details, see Status Codes.

Message specifies details of the status code.

Errors specifies the errors in displaying the message, if any.

Data specifies any additional details related to displaying the message.

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.

If status code 400 is received, failure is recorded and available in Troubleshoot logs. This enables administrator to keep a check on the failed notification and rectify errors.

Trigger API Notification from a Luma Skill

An Administrator can configure the API response in the Text Responses section of a skill as shown below. To know how to create a skill, refer Creating your First Skill.

Once the Text Response is created, the acknowledgement of the triggered API is visible in the Troubleshoot log as seen below.

Alternatively, if the Administrator wants the acknowledgement from the API to be viewed as the skill response, then @resp.data needs to be configured in the Skill Text Responses section. 

View Luma Notification

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