Skip to main content
The Notifications API provides methods for managing notifications for organization members. Notifications can be used for mentions, message reactions, system alerts, and other events that require user attention.

​
Authentication

All Notifications API methods require authentication via the AuthMiddleware. Include a valid bearer token in your requests.

​
Notification Structure

Notifications in Hazel Chat use a flexible resource-based model:
  • memberId: The organization member who should receive the notification
  • targetedResourceId/Type: The primary resource (e.g., a message that mentions the user)
  • resourceId/Type: Related secondary resource (e.g., the channel containing the message)
  • readAt: Timestamp when notification was read (null if unread)

​
Methods

​
Create Notification

Create a new notification for an organization member. Used for mentions, reactions, system alerts, etc. 
const client = yield* RpcClient

const result = yield* client["notification.create"]({
  memberId: "mem_123",
  targetedResourceId: "msg_456",
  targetedResourceType: "message",
  resourceId: "chn_789",
  resourceType: "channel"
})
​
memberId
OrganizationMemberId
required
ID of the organization member who should receive the notification
​
targetedResourceId
string (UUID) | null
ID of the primary resource that triggered the notification (e.g., message ID)
​
targetedResourceType
string | null
Type of the targeted resource (e.g., “message”, “reaction”, “mention”)
​
resourceId
string (UUID) | null
ID of a related secondary resource (e.g., channel ID)
​
resourceType
string | null
Type of the secondary resource (e.g., “channel”)
​
data
Notification
required
The created notification object
​
transactionId
TransactionId
required
Transaction ID for optimistic updates
Errors:
  • UnauthorizedError - User lacks permission to create notifications
  • InternalServerError - Unexpected server error
Implementation Notes:
  • Policy checks ensure users can only create notifications for authorized members
  • Performed within a database transaction

​
Update Notification

Update an existing notification. Typically used to mark notifications as read. 
const client = yield* RpcClient

const result = yield* client["notification.update"]({
  id: "ntf_123",
  readAt: new Date()
})
​
id
NotificationId
required
ID of the notification to update
​
readAt
Date | null
Timestamp when notification was read. Set to mark as read, or null to mark as unread.
​
data
Notification
required
The updated notification object
​
transactionId
TransactionId
required
Transaction ID for optimistic updates
Errors:
  • NotificationNotFoundError - Notification with the specified ID doesn’t exist
  • UnauthorizedError - User lacks permission to update this notification
  • InternalServerError - Unexpected server error
Implementation Notes:
  • Only the notification owner or authorized users can update
  • Performed within a database transaction
  • Policy checks ensure proper authorization

​
Delete Notification

Delete a notification. Only the notification owner or users with appropriate permissions can delete. 
const client = yield* RpcClient

const result = yield* client["notification.delete"]({
  id: "ntf_123"
})
​
id
NotificationId
required
ID of the notification to delete
​
transactionId
TransactionId
required
Transaction ID for optimistic updates
Errors:
  • NotificationNotFoundError - Notification with the specified ID doesn’t exist
  • UnauthorizedError - User lacks permission to delete this notification
  • InternalServerError - Unexpected server error
Implementation Notes:
  • Performed within a database transaction
  • Policy checks ensure only authorized users can delete

​
Delete Notifications by Message IDs

Bulk delete notifications for the current user by message IDs. Used when messages become visible in the viewport to automatically clear their notifications. 
const client = yield* RpcClient

const result = yield* client["notification.deleteByMessageIds"]({
  messageIds: ["msg_123", "msg_456", "msg_789"],
  channelId: "chn_abc"
})

console.log(`Cleared ${result.deletedCount} notifications`)
​
messageIds
MessageId[]
required
Array of message IDs to clear notifications for
​
channelId
ChannelId
required
ID of the channel containing the messages (used for authorization)
​
deletedCount
number
required
Number of notifications that were deleted
​
transactionId
TransactionId
required
Transaction ID for optimistic updates
Errors:
  • UnauthorizedError - User is not a member of the channel’s organization
  • InternalServerError - Unexpected server error
Implementation Notes:
  • Automatically determines the organization member from the current user and channel
  • Only deletes notifications belonging to the current user
  • If messageIds is empty, returns immediately with deletedCount of 0
  • Verifies channel exists and user is an organization member
  • Performed within a database transaction

​
Usage Patterns

import { Effect } from "effect"
import { RpcClient } from "@hazel/domain/rpc"

const markAsRead = (notificationId: string) => Effect.gen(function* () {
  const client = yield* RpcClient
  
  const result = yield* client["notification.update"]({
    id: notificationId,
    readAt: new Date()
  })
  
  return result.data
})

​
Common Use Cases

​
Message Mentions

Create notifications when users are mentioned in messages: 
{
  memberId: mentionedMemberId,
  targetedResourceId: messageId,
  targetedResourceType: "mention",
  resourceId: channelId,
  resourceType: "channel"
}

​
Message Reactions

Notify users when someone reacts to their message: 
{
  memberId: messageAuthorMemberId,
  targetedResourceId: reactionId,
  targetedResourceType: "reaction",
  resourceId: messageId,
  resourceType: "message"
}

​
System Alerts

Send system notifications to users: 
{
  memberId: recipientMemberId,
  targetedResourceId: null,
  targetedResourceType: "system_alert",
  resourceId: null,
  resourceType: null
}

​
Error Handling

import { Effect } from "effect"
import { RpcClient } from "@hazel/domain/rpc"
import { NotificationNotFoundError } from "@hazel/domain/rpc"

const updateNotificationSafe = (id: string) => Effect.gen(function* () {
  const client = yield* RpcClient
  
  const result = yield* client["notification.update"]({
    id,
    readAt: new Date()
  }).pipe(
    Effect.catchTag("NotificationNotFoundError", (error) =>
      Effect.succeed({ data: null, transactionId: "" })
    ),
    Effect.catchTag("UnauthorizedError", () =>
      Effect.fail(new Error("Not authorized to update this notification"))
    )
  )
  
  return result
})

Build docs developers (and LLMs) love

Get started for freeTalk to us