Este artículo describe cómo utilizar la API de notificación para enviar notificaciones desde aplicaciones externas a los usuarios del agente virtual. Las notificaciones son útiles para notificar a los usuarios sobre una interrupción, un anuncio de la empresa o que se completó una solicitud o un servicio, entre otras opciones.
Este artículo trata de los siguientes temas:
Nota
A partir de esta versión, solo se permite el método POST (Registro) para notificar al usuario. Este método agrega un registro en la tabla especificada.
Notificación a los usuarios
Ejemplificaremos una situación en la que el uso de la API de notificación es conveniente. Un usuario le pide al bot que restablezca su contraseña, por lo que la habilidad llama a una aplicación externa para cumplir la solicitud. El sistema externo completa el reinicio del servidor. Con la API de notificación, la aplicación externa informa al usuario que se completó su solicitud a través del chat. En este caso, se debe llamar a la siguiente API proporcionando la dirección URL, los encabezados y los parámetros necesarios para recibir la respuesta.
Formato de URL
Especifique la dirección URL de la API proporcionada a continuación:
| Nombre | Valor | Ejemplo de punto de conexión |
|---|---|---|
| URL predeterminada | {{ENDPOINT}}/api/v1/bulk/notification | https://luma2.serviceaide.com/api/v1/bulk/notification |
Encabezados
Los siguientes son los encabezados obligatorios.
| Nombre | Descripción |
|---|---|
| Autorización | Incluya la clave de acceso de la API (API_TOKEN) proporcionada para las aplicaciones externas. |
| ID externo del inquilino | El ID externo del inquilino de Luma. |
| Content-Type | Especifique el formato de datos de la respuesta, por ejemplo, carga de JSON, TEXT o XML. |
Parámetros (datos) de la solicitud
La sección del cuerpo/la solicitud de la API incluye lo siguiente:
| Nombre | Descripción |
|---|---|
| Destinatarios | Proporcione los detalles de los destinatarios que recibirán las notificaciones. Esto incluye:
|
| Response Type (Tipo de respuesta) | Especifique el formato en el que desea recibir la respuesta. Actualmente, solo se admite JSON. |
| Mensaje | Especifique el mensaje que desea que Luma envíe a los usuarios. Por ejemplo, “Ya reinicié el servidor. Si tiene un problema, cree un ticket de Soporte”. |
Use los elementos anteriores, incluida la URL, los parámetros y los encabezados, para crear la solicitud de notificación a los usuarios. En este ejemplo, usaremos una solicitud JSON, como se especifica a continuación.
curl -X POST 'http://localhost:90/gateway/api/v1/bulk/notification' \
--header 'Content-Type: application/json' \
--header 'Luma-tenant-externalId: ' \
--header 'Luma-api-access-key: ' \
--data-raw '{ "agentChannels": [
{
"agentExternalId": null,
"channelTypes": [
"WEB_WIDGET",
"TEST_WIDGET"
]
}
],
"configuration": {
"id": null,
"name": "ISM Outage",
"recipient": {
"users": [
{
"id": -3,
"userName": null
},
{
"id": null,
"userName": "admin@dev.com"
},
{
"id": null,
"userName": "admin@betatwothree.com"
}
],
"groups": [
{
"id": 1,
"name": null
},
{
"id": null,
"name": "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}]"
}
}
Response
Once the POST request is executed, the following response is received in the JSON format.
{
"status": "Success",
"statusCode": 0,
"statusLine": null,
"errors": null,
"resultData": "39136311-ca49-43fd-990a-9d998858761f",
"warnings": null,
"timestamp": 1577094803197,
"reasonPhrase": null,
"metaInfo": null
}
- The Timestamp is the date and time of the message being displayed in UNIX or epoch format.
- Status is the result of your request. For more details, see Status Codes.
- Error shows if any errors that may have occurred when displaying the message.
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, 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, Luma notifies the users regarding the outage; else, Luma prompts the users to check the errors in the request and to retry after fixing the errors.
Triggering Notification API from a Skill
A Skill can call the Notification API and the API response could be accessed using @resp.data.
When you use the NotifyAPI as part of the conversation flow in the skill, the Developer or Administrator can verify or debug the response from the Notify API in debug utility from the test widget or could access the data from Conversation History sections of the virtual agent. More information on debugging a skill or accessing the conversation history, refer to these articles Debug Skills and Conversation History
View Luma Notification
Once the notify API request is successful, the message will be delivered to all registered users who are specified as part of the Notification API request.
