Enviar notificaciones a los usuarios desde aplicaciones externas
- haritha.kothapalem (Unlicensed)
- sneha.tripathi
- Adriana Rios
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 reinicie un servidor, 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/gateway/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 tenant | El ID externo del tenant 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 el formato 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}]"
}
}
En el ejemplo anterior, el campo 'message' (mensaje) se utiliza para diseñar el mensaje de la notificación que se enviará al usuario. La plantilla JSON del campo crea un mensaje con formato correcto con encabezados, subtítulos, mensaje y botones procesables.
Para enviar un mensaje de texto simple, puede utilizar el campo 'textmessage' (mensaje de texto) en lugar del campo message (mensaje). Se puede usar el campo textmessage (mensaje de texto) para enviar un mensaje de texto simple al usuario sin ningún formato especial o acción vinculada. En el ejemplo, agregaremos un mensaje de texto simple.
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": null,
"textMessage": "You server reboot is complete. We recommend you to test your applications and contact the support team in case of any issue"
}
}
Respuesta
Una vez que se ejecuta la solicitud POST, se recibe la siguiente respuesta en formato JSON.
{
"status": "Success",
"statusCode": 0,
"statusLine": null,
"errors": null,
"resultData": "39136311-ca49-43fd-990a-9d998858761f",
"warnings": null,
"timestamp": 1577094803197,
"reasonPhrase": null,
"metaInfo": null
}
- La marca de tiempo es la fecha y hora del mensaje que se muestra en formato UNIX o epoch.
- El estado es el resultado de su solicitud. Para obtener más información, consulte Códigos de estado.
- “Error” muestra si se ha producido algún error al mostrar el mensaje.
Códigos de estado
Los códigos de estado transmiten los resultados de su solicitud. El siguiente código de estado se aplica a la API POST.
| Nombre | Descripción |
|---|---|
| 200 | Esto indica que la solicitud se ha completado correctamente. Sin embargo, si no se devuelven resultados, significa que el cuerpo de la respuesta solo contiene una matriz de resultados vacía. |
| 204 | Indica que la API REST se niega a devolver cualquier mensaje de estado en el cuerpo del mensaje de respuesta. |
| 400 | Esto indica que la solicitud puede contener errores como una sintaxis de solicitud mal formada, parámetros de mensaje de solicitud no válidos o enrutamiento de solicitud engañoso, etc. Identifique el error y vuelva a enviar la solicitud con la modificación requerida. |
Si la solicitud es correcta y recibe el código de estado 200, Luma notifica a los usuarios sobre la interrupción; de lo contrario, Luma les solicita que comprueben los errores de la solicitud y que vuelvan a intentarlo después de corregirlos.
Activar la API de notificación desde una habilidad
Una habilidad puede llamar a la API de notificación y se puede acceder a la respuesta de la API mediante @resp.data.
Cuando se utiliza la API de notificación como parte del flujo de la conversación en la habilidad, el desarrollador o el administrador puede verificar o depurar la respuesta de la API de notificación en la utilidad de depuración desde el widget de prueba o puede acceder a los datos desde las secciones Conversation History (Historial de conversaciones) del agente virtual. Para obtener más información sobre cómo depurar una habilidad o acceder al historial de conversaciones, consulte los artículos Depurar habilidades e Historial de conversaciones.
Ver notificaciones de Luma
Una vez que la solicitud de la API de notificación sea correcta, el mensaje se entregará a todos los usuarios registrados que se especifican como parte de la solicitud de la API de notificación.
