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.
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.
Specify the API URL provided below:
Specify the parameters involved in your call. In this example, to notify Luma users, the following parameters need to be specified.
Provide details of the recipients who will receive the Luma notifications. Recipients data includes the ID or username, Contacts and Role.
The users' ID or username can be provided (for example, sam.phyll). Include details of the contacts who need to notified (type '0' to notify all users, else, for specific contacts, include their name, for example, Ruth).
Specify the user roles who need to be notified, for example, specify Analysts, or Self-service users.
|Response Type||Specify the format in which you want to receive the response, for example, text, image, application/json and more. For example, let us use the simple text format. |
|Message||Specify the message you want Luma to send to the users. For example, 'This is to notify you that the Microsoft Exchange server is down due to internal maintenance and will be up at 9 PM (PST)'|
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||Include the API Token provided to your Tenant in Luma.|
API_TOKEN: Specify the alphanumeric access token available on Manage Tenant Information page.
|Content-Type||Specify the data format in which you want the response to be provided, for example, json payload, or card.|
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.
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, email@example.com, firstname.lastname@example.org).
- 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)
- 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.
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 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 convey the results of your request. The following status code applies to the Post API.
|200||Indicates that the request is completed successfully. However, if no results are returned, it means that the response body contains only an empty result array.|
|204||Indicates that the REST API declines to send back any status message in the response message’s body.|
|400||Indicates that the request may contain errors such as malformed request syntax, invalid request message parameters, or deceptive request routing and so on. Identify the error and resend the request with the required modification.|
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.