Se você tem um site ou aplicativo existente e deseja incentivar a discussão no seu fórum Discourse, pode ser útil exibir notificações do Discourse dentro do seu aplicativo. Este guia mostrará como usar a API do Discourse para buscar notificações para um usuário e como marcá-las como lidas.
A maneira recomendada de usar a API é fazer com que seu aplicativo faça solicitações de back-end para o Discourse e, em seguida, passe esses dados para a camada de front-end/apresentação do seu aplicativo.
Consulte a Documentação da API para obter informações sobre como usar a API do Discourse.
Buscando notificações para um usuário
Para obter notificações via API, você pode fazer uma solicitação GET autenticada para o endpoint /notifications. Você pode especificar o nome de usuário para o qual está buscando notificações no cabeçalho Api-Username ou como um parâmetro de consulta: /notifications?username=<username>.
Parâmetros de consulta opcionais
| Parâmetro | Descrição |
|---|---|
username |
O nome de usuário para o qual buscar notificações |
filter |
Filtrar por status de leitura: read (lido) ou unread (não lido) |
filter_by_types |
Lista separada por vírgulas de nomes de tipos de notificação para filtrar (ex: mentioned,replied) |
offset |
Deslocamento para paginação |
limit |
Número de notificações a serem retornadas (máx. 60) |
Exemplo de solicitação
curl -X GET "http://localhost:8080/notifications.json?username=blake.erickson" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: system"
Isso retornará a seguinte resposta JSON
{
"notifications": [
{
"id": 3,
"user_id": 5,
"external_id": null,
"notification_type": 12,
"read": true,
"high_priority": false,
"created_at": "2019-06-17T20:26:05.670Z",
"post_number": null,
"topic_id": null,
"slug": null,
"data": {
"badge_id": 41,
"badge_name": "First Emoji",
"badge_slug": "first-emoji",
"badge_title": false,
"username": "blake"
}
},
{
"id": 2,
"user_id": 5,
"external_id": null,
"notification_type": 6,
"read": true,
"high_priority": true,
"created_at": "2019-06-17T20:26:04.305Z",
"post_number": 1,
"topic_id": 10,
"fancy_title": "Greetings!",
"slug": "greetings",
"data": {
"topic_title": "Greetings!",
"original_post_id": 14,
"original_post_type": 1,
"original_username": "discobot",
"revision_number": null,
"display_username": "discobot"
}
}
],
"total_rows_notifications": 2,
"seen_notification_id": 3,
"load_more_notifications": "/notifications?offset=60&username=blake"
}
Isso retorna um array de notificações. Se você estiver interessado em mostrar apenas notificações não lidas, poderá passar o parâmetro de consulta filter=unread para fazer com que o servidor retorne apenas notificações não lidas. Por exemplo:
curl -X GET "http://localhost:8080/notifications.json?username=blake.erickson&filter=unread" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: system"
Você pode visitar esta página para obter uma lista de tipos de notificação. Por exemplo, o tipo de notificação 12 corresponde a “granted_badge” (emblema concedido).
Marcando notificações como lidas
Agora que você buscou as notificações de um usuário, você pode marcá-las como lidas enviando uma solicitação PUT para /notifications/mark-read com o id da notificação no corpo da solicitação e especificando o nome de usuário no cabeçalho da solicitação.
Exemplo de solicitação
curl -X PUT "http://localhost:8080/notifications/mark-read" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: blake.erickson" \
-F "id=4"
Você também pode omitir o ID da notificação e ele marcará todas as notificações para aquele usuário como lidas.
Isso retornará uma resposta JSON simples de “OK”:
{
"success": "OK"
}