Notifications API

The Notifications API manages in-app notifications, email preferences, and push notification settings for users.

Notification Object

{
  id: string;                    // UUID
  user_id: string;               // UUID of the recipient
  organization_id: string;       // UUID of the organization
  type: string;                  // Notification type
  title: string;                 // Notification title
  message: string;               // Notification body
  data?: object;                 // Additional data (link, entity ID, etc.)
  read: boolean;                 // Whether notification has been read
  created_at: string;            // ISO timestamp
}

Notification Types

List Notifications

Retrieve notifications for the current user.

Procedure: notifications.list

Authentication: Required

Input:

{
  unreadOnly?: boolean;  // Filter to unread only (default: false)
  limit?: number;        // 1-100, default: 50
  cursor?: string;       // Pagination cursor
}

Example:

curl -X GET "https://your-domain.com/api/trpc/notifications.list?input=%7B%22unreadOnly%22:true,%22limit%22:20%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "notifications": [
          {
            "id": "uuid",
            "type": "ticketAssigned",
            "title": "Ticket Assigned",
            "message": "You've been assigned ticket #1234: Customer login issue",
            "data": {
              "ticketId": "ticket-uuid",
              "ticketNumber": 1234
            },
            "read": false,
            "created_at": "2024-01-15T10:30:00.000Z"
          },
          {
            "id": "uuid-2",
            "type": "mentions",
            "title": "You were mentioned",
            "message": "@john mentioned you in ticket #1230",
            "data": {
              "ticketId": "ticket-uuid-2",
              "conversationId": "conv-uuid"
            },
            "read": false,
            "created_at": "2024-01-15T10:15:00.000Z"
          }
        ],
        "nextCursor": "uuid-2",
        "hasMore": true
      }
    }
  }
}

Get Unread Count

Get the count of unread notifications.

Procedure: notifications.unreadCount

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/notifications.unreadCount" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "count": 5
      }
    }
  }
}

Mark as Read

Mark a specific notification as read.

Procedure: notifications.markAsRead

Authentication: Required

Input:

{
  id: string;  // Notification UUID
}

Example:

curl -X POST "https://your-domain.com/api/trpc/notifications.markAsRead" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"id":"notification-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Mark All as Read

Mark all notifications as read.

Procedure: notifications.markAllAsRead

Authentication: Required

Input: None

Example:

curl -X POST "https://your-domain.com/api/trpc/notifications.markAllAsRead" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "count": 5
      }
    }
  }
}

Delete Notification

Delete a specific notification.

Procedure: notifications.delete

Authentication: Required

Input:

{
  id: string;  // Notification UUID
}

Example:

curl -X POST "https://your-domain.com/api/trpc/notifications.delete" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"id":"notification-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Get Preferences

Get the user's notification preferences.

Procedure: notifications.getPreferences

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/notifications.getPreferences" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "email": {
          "ticketCreated": true,
          "ticketAssigned": true,
          "ticketUpdated": false,
          "ticketResolved": true,
          "newComment": true,
          "mentions": true,
          "slaWarning": true,
          "slaBreach": true,
          "weeklyReport": true
        },
        "inApp": {
          "ticketCreated": true,
          "ticketAssigned": true,
          "ticketUpdated": true,
          "ticketResolved": true,
          "newComment": true,
          "mentions": true,
          "slaWarning": true,
          "slaBreach": true,
          "weeklyReport": false
        },
        "push": {
          "ticketAssigned": true,
          "mentions": true,
          "slaWarning": false,
          "slaBreach": true
        }
      }
    }
  }
}

Update Preferences

Update notification preferences.

Procedure: notifications.updatePreferences

Authentication: Required

Input:

{
  channel: 'email' | 'inApp' | 'push';
  type: string;        // Notification type
  enabled: boolean;    // Enable or disable
}

Example:

curl -X POST "https://your-domain.com/api/trpc/notifications.updatePreferences" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "channel": "email",
      "type": "ticketUpdated",
      "enabled": false
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "preferences": {
          "email": {
            "ticketUpdated": false
          }
        }
      }
    }
  }
}

Disable All Email

Disable all email notifications (useful for vacation/away mode).

Procedure: notifications.disableAllEmail

Authentication: Required

Input: None

Example:

curl -X POST "https://your-domain.com/api/trpc/notifications.disableAllEmail" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "message": "All email notifications disabled"
      }
    }
  }
}

Notification Channels

Use Cases

Real-Time Notifications

// Poll for new notifications
const { count } = await trpc.notifications.unreadCount.query()

// Display badge
if (count > 0) {
  showBadge(count)
}

// Fetch notifications when user opens panel
const { notifications } = await trpc.notifications.list.query({
  unreadOnly: true,
  limit: 20,
})

Notification Settings Page

// Load preferences
const preferences = await trpc.notifications.getPreferences.query()

// Toggle a preference
await trpc.notifications.updatePreferences.mutate({
  channel: 'email',
  type: 'weeklyReport',
  enabled: false,
})

Error Codes