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 reinicialize 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.
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/gateway/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 tenant | A ID externa do tenant 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}]"
}
}
Resposta
Depois que a solicitação POST é executada, a seguinte resposta é recebida no formato JSON.
{
"status": "Success",
"statusCode": 0,
"statusLine": null,
"errors": null,
"resultData": "39136311-ca49-43fd-990a-9d998858761f",
"warnings": null,
"timestamp": 1577094803197,
"reasonPhrase": null,
"metaInfo": null
}
- 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 StatusCodes.
- 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.
