Sending Notifications to Users From External Applications

This article describes how to trigger Channel notifications to Luma users through APIs.

Channel Notifications in Luma VA are used to send information to users on their Chat Channel. These notifications can broadcast an outage or a company announcement to a group of users or notify users of the completion of their request or service. Besides triggering a notification manually through Bot builder, you can also send these notifications as part of skill or from a third-party system.

Luma provides SendNotification API that can be used to trigger notifications via a Luma Skill or an external application. The Luma API can initiate an existing notification configuration or send a customized notification.

API Configuration

Following are the details to configure the API:

URI: Specify the /bulk/notification as URI. Based on the Luma instance the Endpoint URL is formed. For example, https://luma2.serviceaide.com/gateway/api/v1/bulk/notification.
HTTP Method for the operation: POST
Pass the following as Headers:
1. Generate and copy the API Access Token from Luma VA and pass it to the API as the Header. Provide Send Channel Notifications permission when creating API access key. Refer to Create and Manage API Access Keys to create an API access key with Send Channel Notifications permission.
2. Fetch the Tenant External ID from Luma VA and pass it to the API as the Header. Click on the Tenant → Settings. Copy the Tenant External ID on Tenant Information. Refer to Tenant Information for more details.
3. Pass the data format for the request and response, for example, JSON, TEXT, XML payload. Pass ‘application/json’ as Content-Type.

Pass the Request Parameters. The API requires the following parameters:

Recipients: These are the users who should receive the notifications. Notifications can be sent based on:
1. Users - a list of specific Luma users.
2. Groups - one or more groups available in Luma VA
3. Contact Channel Authentication (CCA) - Specific users based on the user’s ChannelScope ID and ChannelScopeContact ID. These IDs are specific to users that are assigned when a user is registered to a specific Channel.
Agent Channels - The channel information where the user should be notified.
BotExternalId - The Virtual Agent ID to be notified.
Notification ID- Channel Notification details to be triggered.

Message - Notification Message to be sent to the users
Using the above elements including the Request URL, parameters, and headers, you can send the web service request to notify users. The request is passed in the following JSON format. Update the various parameters in the request as required. Refer to the next sections for more details.

curl --location --request POST 'https://luma2.serviceaide.com/gateway/api/v1/bulk/notification' \
--header 'Luma-api-access-key: ' \
--header 'Luma-tenant-externalId: ' \
--header 'Content-Type: application/json' \
--data-raw '{
"agentChannels": [
{
"agentExternalId": null,
"channelTypes": [
"WEB_WIDGET",
"TEST_WIDGET"
]
}
],
"configuration": {
"id": null,
"name": "test",
"recipient": {
"users": [
{
"id": -3,
"userName": null
},
{
"id": null,
"userName": "test1"
},
{
"id": null,
"userName": "test2"
}
],
"groups": [
{
"id": 1,
"name": null
},
{
"id": null,
"name": "Default Administrators"
}
],
"contactChannels": [
{
"id": null,
"channelScopeId": "8560f2ef-3dea-4701-ae4a-a66101784acb",
"channelScopeContactId": "89d83c3e-a14a-11e9-870d-a44cc82a824c",
"agentChannel": {
"id": null,
"channelType": "TEST_WIDGET"
}
}
]
},
"message": "[ { \"format\": \"CAROUSEL\", \"content\": {\"cards\": [{\"title\": \"Create Support Issue : \", \"buttons\": [{\"type\": \"postBack\", \"title\": \"Create Ticket in ISM\", \"value\": \"val1\"}], \"subtitle\": null}], \"title\": \"Hey, I have rebooted the server, If you have an issue please create a support ticket\"}, \"sendButtonTextAsPayload\": true}]"
}
}'

Once the notification is successfully triggered, the response is received in the following JSON format.
```
{
"status":"Success",
"statusCode":0,
"statusLine":null,
"errors":null,
"resultData":"fa1e784e-4d7e-40d4-826d-a627764ea546",
"warnings":[],
"timestamp":1641915369739,
"reasonPhrase":null,
"metaInfo":null
}
```
1. Timestamp is the date and time of the wen service execution. It is in UNIX or epoch format.
2. Status is the result of your request. For more details, see Status Codes.
3. Error shows the error message in case the web service execution fails.

Status Codes

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

Name	Description
200	This 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	It indicates that the REST API declines to send back any status message in the response message’s body.
400	This indicates that the request may contain errors such as malformed request syntax, invalid request message parameters, 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, Luma VA triggers the notification to the users as per the configuration. In case of an error, check for the errors in the request and retry.

Trigger an Existing notification

Use the following parameters, to trigger an existing notification already configured in the Luma VA tenant.

agentExternalId: This refers to the bot to which the notification should be triggered. Add the Bot external ID. This is optional. If not provided, the default bot for the tenant is considered.
ChannelTypes: Add the Channels to which the notification should be sent.
Configuration → id: This refers to the Channel Notification to be triggered. Add the Notification ID in Luma VA. Refer to Channel Notifications for more information.
Configuration → name: Add the Notification name in Luma VA. The notification with the provided name is triggered. If the name is ‘null’, the ID is used to identify the notification configuration.

Using the configuration, the notification with specified ID in Luma is triggered. Recipients and the Message configured in Luma are used to send the notification. Recipients or messages added in the request are ignored.

{
  "agentChannels": [
{
 "agentExternalId": null,
 "channelTypes": 
[
 "WEB_WIDGET",
 "TEST_WIDGET"
]
}
],
  "configuration": {
"id": 3,
"name": null,
"recipient": null,
"message": null,
"textMessage": null
}
}

Send a Custom Notification

Custom Notifications are not configured in the Luma Virtual Agent and are triggered directly from a Skill or an external system. These notifications only appear in the Notification History tab and cannot be triggered from Luma Bot Builder. Custom Notifications can be sent with the following configurations:

Notification to a specific list of Luma User

Configure the following parameters to trigger a custom notification to a specific list of Luma VA.

agentExternalId: This refers to the bot to which the notification should be triggered. Add the Bot external ID. This is optional. If not provided, the default bot for the tenant is considered.
ChannelTypes: Add the Channels to which the notification should be sent.
Configuration→ id: This refers to the Channel Notification to be triggered. For a custom notification, set ID to null.
Configuration→ name: Provide a name for the Channel configuration.
Configuration→ recipient → users: Provide the list of Luma users to whom the notification is to be sent. Add the user ID or username.
- ID refers to the UserID in Luma
- userName refers to username in Luma
Configuration→ Message: The 'message' field is used to design the notification message to be sent to the user. The field accepts JSON templates to create a well-formatted message to be displayed in a card with Headings, Sub-headings, Message, or/and Actionable buttons.
Configuration→ textmessage: You can use the 'textmessage' field to send a simple text message, instead of the message field. The textmessage field can be used to send a simple text message to the user without any special formatting or linked action. Set the Message field to null and add the message to the textmessage field.

Use either ‘Message’ or ‘textmessage’ field to configure the message.

Using the above configuration, the notification is triggered to the added Luma users.

{
  "agentChannels":[
{
"agentExternalId": null,
"channelTypes": [
"WEB_WIDGET",
"TEST_WIDGET"
]
}
],
"configuration": {
"id": null,
"name": "Test",
"recipient": 
{
"users": [
{
"id": null,
"userName": "Shekar"
}
]
},
"message": "[{\"format\": \"CAROUSEL\", \"content\": {\"cards\": [{\"title\": \"Create Support Issue : \", \"buttons\": [{\"type\": \"postBack\", \"title\": \"Create Ticket in ISM\", \"value\": \"val1\"}], \"subtitle\": null}], \"title\": \"Hey, I have rebooted the server, If you have an issue please create a support ticket\"}, \"sendButtonTextAsPayload\": true}]",
"textMessage": null
}
}

To send the notification to multiple users, add userid or username for each user in the recipient list. Following is the sample JSON format to send notifications to multiple users.

{ 
  "agentChannels":[ 
    { 
    "agentExternalId": null,
    "channelTypes":
      [
      "WEB_WIDGET", 
      "TEST_WIDGET" 
      ] 
    } 
    ],
    "configuration":
    { 
      "id": null,
      "name": "Test",
      "recipient": 
        { 
          "users": 
          [ 
            { 
              "id": null, 
              "userName": "User1" 
            },
            { 
              "id": null, 
              "userName": "User2" 
            },
            { 
              "id": 9, 
              "userName": null 
            }
          ] 
        }, 
        "message": null, 
        "textMessage": "This is test notification" 
      } 
}

Custom Notification to a Group

To send the notification to a user group, add the following group details to the request parameter:

Configuration→ recipient → group: Provide the list of user groups in Luma. The notification is sent to all the active users in the group. Add the Group ID or Group name.
- ID refers to the Group ID in Luma
- Name refers to Group name in Luma

Following is the sample Request Parameters configuration to send notifications to a group.

{"agentChannels": [
{
"agentExternalId": null,
"channelTypes": [
"WEB_WIDGET",
"TEST_WIDGET"
]
}
],
"configuration": {
"id": null,
"name": "ISM Outage",
"recipient": {
"users": [
{
"id": null,
"userName":"Test"
}
],
"groups": [
{
"id": -3,
"name": null
}
]
},
"message": null,
"textMessage": "This is a notification to New user group"
}
}

Custom Notification to a User based on channel ID

To send the notification to a user based on Channel ID, add the following details to the request parameter:

Configuration→ recipient → contactChannels: Provide the channel contact details for users in Luma to whom the notification is to be sent.
- channelScopeId refers to Channel’s Scope ID
- channelScopeContactId refers to user’s channelScopeContactId
- agentChannel → channelType refers to the channel name to which the notification should be sent.

Refer to Luma APIs for User Registration to get ChannelScopeID and ChannelScopeContactId for a user.

Following is the sample Request Parameters configuration to send notifications to a user based on the Channel details.

{"agentChannels": [
{
"agentExternalId": null,
"channelTypes": [
"WEB_WIDGET",
"TEST_WIDGET"
]
}
],
"configuration": {
"id": null,
"name": "ISM Outage",
"recipient": {
"contactChannels": [
{
"id": null,
"channelScopeId": "afafa5d4-20f7-4eca-ad5d-511535de6346",
"channelScopeContactId": "8ea66353-5b6d-4f9c-8543-da7ca6c80508",
"agentChannel": {
"id": null,
"channelType": "TEST_WIDGET"
}
}
]
},
"message": null,
"textMessage": "This is a notification to Channel"
}
}

Triggering Notification from a Skill

You can add the Notification API in your Luma Skill to trigger a notification as part of a user-bot conversation. Use the configurations to create an integration operation and add the same as the conversation item in your skill. For more information refer to Create Skills.

When the Notification API is executed from skills, the Developer or Administrator can verify or debug the API response in debug utility from the test widget or access the logs from Conversation History. For more information on debugging a skill or accessing the conversation history, refer to these articles Debug Skills and Conversation History.

View Notification in Luma VA

Once the API request is successful, the message is delivered to Luma users specified in the Notification API request.