Si vous avez un site web ou une application existante et que vous souhaitez encourager les discussions sur votre forum Discourse, il peut être utile d’afficher les notifications Discourse à l’intérieur de votre application. Ce guide vous montrera comment utiliser l’API Discourse pour récupérer les notifications d’un utilisateur et comment les marquer comme lues.
La méthode recommandée pour utiliser l’API est que votre application effectue des requêtes côté serveur vers Discourse, puis transmette ces données à la couche front-end/présentation de votre application.
Consultez la Documentation de l’API pour obtenir des informations sur l’utilisation de l’API Discourse.
Récupération des notifications pour un utilisateur
Pour obtenir des notifications via l’API, vous pouvez effectuer une requête GET authentifiée vers le point de terminaison /notifications. Vous pouvez spécifier le nom d’utilisateur pour lequel vous récupérez les notifications dans l’en-tête Api-Username ou en tant que paramètre de requête : /notifications?username=<username>.
Paramètres de requête optionnels
| Paramètre | Description |
|---|---|
username |
Le nom d’utilisateur pour lequel récupérer les notifications |
filter |
Filtrer par état de lecture : read ou unread |
filter_by_types |
Liste séparée par des virgules des noms de types de notification pour filtrer (ex. : mentioned,replied) |
offset |
Décalage pour la pagination |
limit |
Nombre de notifications à retourner (max 60) |
Exemple de requête
curl -X GET "http://localhost:8080/notifications.json?username=blake.erickson" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: system"
Ceci retournera la réponse JSON suivante
{
"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"
}
Ceci retourne un tableau de notifications. Si vous souhaitez uniquement afficher les notifications non lues, vous pouvez passer le paramètre de requête filter=unread pour que le serveur retourne uniquement les notifications non lues. Par exemple :
curl -X GET "http://localhost:8080/notifications.json?username=blake.erickson&filter=unread" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: system"
Vous pouvez consulter cette page pour une liste des types de notification. Par exemple, le type de notification 12 correspond à « granted_badge ».
Marquage des notifications comme lues
Maintenant que vous avez récupéré les notifications d’un utilisateur, vous pouvez les marquer comme lues en envoyant une requête PUT à /notifications/mark-read avec l’id de la notification dans le corps de la requête et en spécifiant le nom d’utilisateur dans l’en-tête de la requête.
Exemple de requête
curl -X PUT "http://localhost:8080/notifications/mark-read" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: blake.erickson" \
-F "id=4"
Vous pouvez également omettre l’identifiant de la notification et toutes les notifications pour cet utilisateur seront marquées comme lues.
Ceci retournera une simple réponse JSON « OK » :
{
"success": "OK"
}