Page Comparison

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 the bot users after completion of a service or request.

...

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. 

...

Notifying Users

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

...

...

• Authorization: Bearer {{API_TOKEN}}

  Info
  title 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

...

{

  "recipients" : {

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

    "roles" : [""]

  },

  "botExternalID" : "",

  "template_type" : "",

  "template_id" : "",

  "responseType" : "TEXT",

  "message" : "MaintainanceThis is in progress. Will update you once it is doneto 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 an 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:  Include You can specify the role code of the users user to whom the inbound message needs to be sentdisplayed. 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)- 5 (to be used to send the message to Guest user)

    
    

    Info
    title Note
    To send message to all the 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 know the find an existing template ID in the , go to Skills Builder , and on the Settings page, click Notification Templates tab. Search for the Find the correct notification template and the related 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 you wish to use a Skills Builder notification template, then 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.variable (@request.message) should be used in the notification template. 

Response

Once the Post 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.

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.

Image Added 

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

Image Added 

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.

...