Este artigo descreve como usar a API de notificação para enviar notificações dos aplicativos externos para os usuários da agente virtual. É útil enviar notificações aos usuários quando ocorre uma interrupção, em comunicados da empresa, quando uma solicitação ou um serviço é concluído, e assim por diante.
Este artigo aborda as seguintes áreas:
Observação
A partir desta release, oferecemos suporte apenas ao método POST para notificar o usuário. Esse método insere um registro na tabela especificada.
Notificando usuários
Vamos usar um exemplo em que a API de notificação será útil. Um usuário solicita que o bot redefina sua senha. A habilidade chama um aplicativo externo para atender à solicitação. O sistema externo conclui a reinicialização do servidor. Usando a API de notificação, o aplicativo externo informa o usuário por meio do bate-papo que a solicitação foi concluída. Nesse caso, a API seguinte precisa ser chamada, fornecendo os cabeçalhos, o URL e os parâmetros obrigatórios para receber a resposta.
Formato do URL
Especifique o URL da API fornecido abaixo:
| Nome | Valor | Exemplo de terminal |
|---|---|---|
| URL padrão | {{ENDPOINT}}/api/v1/bulk/notification | https://luma2.serviceaide.com/api/v1/bulk/notification |
Cabeçalhos
Veja a seguir os cabeçalhos necessários.
| Nome | Descrição |
|---|---|
| Autorização | Inclua a chave de acesso à API (API_TOKEN) fornecida aos aplicativos externos. |
| ID externa do inquilino | A ID externa do inquilino da Luma. |
| Content-Type | Especifique em que formato de dados deseja que a resposta seja fornecida; por exemplo: carga XML, JSON, TEXT. |
Parâmetros da solicitação (dados)
A seção corpo/solicitação da API inclui o seguinte:
| Nome | Descrição |
|---|---|
| Destinatários | Forneça os detalhes dos destinatários que receberão as notificações. Isso inclui:
|
| Tipo de resposta | Especifique o formato em que deseja receber a resposta. No momento, há suporte apenas para o formato JSON. |
| Mensagem | Especifique a mensagem que você deseja que a Luma envie aos usuários. Por exemplo, "Reiniciei o servidor. Caso encontre algum problema, crie um ticket de suporte" |
Usar os elementos acima, incluindo o URL, os parâmetros e os cabeçalhos, permite criar a solicitação para notificar os usuários. Neste exemplo, usaremos uma solicitação JSON, conforme especificado a seguir.
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.