Get notifications
/v1/notificationsNo specific role is required; any valid credential works.
Retrieves all user in-app notifications.
Notifications
Notifications are the alerts Kustomer sends a user about activity they care about, such as a conversation being assigned to them or a teammate mentioning them in a note. Each user chooses which events notify them in the app and by email, and admins choose who receives org-wide alerts about problems such as a disconnected channel.
When something happens in Kustomer that a user has asked to hear about, Kustomer creates an in-app notification for that user, sends an email, or both. In-app notifications appear in the notifications list in the agent desktop. Each one belongs to a single user, starts as unread, and is removed automatically after seven days. These endpoints always act on the signed-in user: an API key sees the notifications of its own user, not everyone's.
In-app notifications
Each notification has a name, the event that triggered it (such as kustomer.conversation.firstmessagein), a status of read or unread, and event, a copy of the event with the object it is about, such as the message and links to its conversation and customer. The list is newest first and paginated with page and pageSize. meta.unread gives the number of unread notifications, which is handy for a badge. A user is never notified twice about the same event for the same reason.
Notification preferences
Each user has one preferences record with an entry per notification type, such as notify_kustomer_conversation_assign, notify_kustomer_note_mention or notify_kustomer_conversation_unsnooze. Each entry sets two channels:
| Channel | Values |
|---|---|
web |
always or never: whether to show an in-app notification. |
email |
always, loggedout (only while the user is signed out of Kustomer) or never. |
Types ending in _by_app, such as notify_kustomer_conversation_messagein_by_app, hold the same pair for each channel app (for example postmark and gmail for email, chat, facebook, twilio for SMS, or form), so a user can, for example, hear about new chat messages but not new emails. A user who has never changed anything gets Kustomer's defaults: assignments and note mentions notify them, and new incoming messages don't.
Org alert recipients
Separate from personal preferences, the notifications logs settings hold one list per org: emails, up to five addresses that receive an email when Kustomer detects a problem that affects the whole org, such as a Facebook or Gmail connection failing to authenticate. If the list is empty, these alerts go to the org owner.
Which endpoint to use
| To | Call |
|---|---|
| List the signed-in user's notifications and unread count | GET /v1/notifications |
| Mark all of them as read or unread | PUT /v1/notifications with status |
| Clear all of them | DELETE /v1/notifications |
| Read or change the signed-in user's preferences | GET or PUT /v1/notifications/users/current/settings |
| Read or change who receives org alerts | GET or PUT /v1/notifications/logs/settings |
PUT /v1/notifications and DELETE /v1/notifications act on every notification the user has, and both return 204 with no body. When you update preferences, send only the types you want to change; the others keep their current values. A PUT to the org alert settings replaces the whole emails list and requires an admin role with permission to manage settings.
Query parameters
Page number of results to return.
1Number of results to return per page.
100Responses
OK