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.
...
Vamos usar um exemplo em que a API de notificação será útil. Um usuário solicita que o bot redefina sua senhareinicialize um servidor. 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.
...
| Nome | Valor | Exemplo de terminal |
|---|---|---|
| URL padrão | {{ENDPOINT}}/api/v1/bulk/notification | https://luma2.serviceaide.com/gateway/api/v1/bulk/notification |
...
| Nome | Descrição |
|---|---|
| Autorização | Inclua a chave de acesso à API (API_TOKEN) fornecida aos aplicativos externos. |
| ID externa do inquilinotenant | A ID externa do inquilino tenant da Luma. |
| Content-Type | Especifique em que formato de dados deseja que a resposta seja fornecida; por exemplo: carga XML, JSON, TEXT. |
...
| 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" |
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
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
...
No exemplo acima, o campo message é usado para criar a mensagem de notificação a ser enviada ao usuário. O modelo JSON no campo cria uma mensagem bem formatada com cabeçalhos, subtítulos, mensagem e botões acionáveis.
Para enviar uma mensagem de texto simples, você pode usar o campo textmessage em vez do campo message. O campo textmessage pode ser usado para enviar uma mensagem de texto simples ao usuário, sem nenhuma formatação especial ou ação vinculada. No exemplo, vamos adicionar uma mensagem de texto simples.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
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"
}
} |
Resposta
Depois que a solicitação POST é executada, a seguinte resposta é recebida no formato JSON.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"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.
...
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 Depurar habilidades and Histórico da conversa
View Luma Notification
...
- O carimbo de data e hora é a data e a hora da mensagem exibida no formato UNIX.
- O status é o resultado de sua solicitação. Para obter mais detalhes, consulte Códigos de status.
- Erro mostra se há algum erro que possa ter ocorrido ao exibir a mensagem.
Códigos de status
Os códigos de status transmitem os resultados da sua solicitação. O código de status a seguir se aplica à API Post.
| Nome | Descrição |
|---|---|
| 200 | Isso indica que a solicitação foi concluída com êxito. No entanto, se nenhum resultado for retornado, isso significa que o corpo da resposta contém apenas uma matriz de resultados vazia. |
| 204 | Ele indica que a API REST se recusa a enviar de volta qualquer mensagem de status no corpo da mensagem de resposta. |
| 400 | Isso indica que a solicitação pode conter erros, como sintaxe de solicitação malformada, parâmetros de mensagem de solicitação inválidos ou roteamento de solicitação enganosa, e assim por diante. Identifique o erro e reenvie a solicitação com a modificação necessária. |
Se a solicitação for bem-sucedida com o código de status 200, a Luma notificará os usuários sobre a interrupção; Caso contrário, a Luma solicita que os usuários verifiquem os erros na solicitação e tentem novamente após corrigir os erros.
Disparando API de notificação a partir de uma habilidade
Uma habilidade pode chamar a API de notificação e a resposta da API pode ser acessada usando @resp.data.
Quando você usa a API de notificação como parte do fluxo de conversa na habilidade, o desenvolvedor ou administrador pode verificar ou depurar a resposta da API de notificação no utilitário de depuração do widget de teste, ou pode acessar os dados nas seções Histórico da conversa da agente virtual. Para obter mais informações sobre como depurar uma habilidade ou acessar o histórico da conversa, consulte estes artigos Depurar habilidades e Histórico da conversa.
Exibir notificação da Luma
Assim que a solicitação da API de notificação for bem-sucedida, a mensagem será entregue a todos os usuários registrados que são especificados como parte da solicitação da API de notificação.
