​
Prerequisites

Before managing notifications, ensure you have:

​
Best Practices

Performance

Use pagination (25-50 per page), cache data, and implement virtual scrolling for large lists.

User Experience

Show unread counts, “mark all read” buttons, and relative timestamps with graceful empty states.

Real-time Updates

Poll summary endpoint periodically and update local state optimistically when marking as read.

​
Notification History

​
Get Full Notification History

Retrieve paginated notification history for the authenticated user:

const response = await fetch('https://alerts-api.dial.to/v2/history?limit=25', {
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY'
  }
});

const data = await response.json();

Query Parameters:

  • appId (optional): Filter notifications for a specific app
  • limit (optional): Number of notifications to return (default: 25, max: 50)
  • cursor (optional): Base64-encoded cursor for pagination

Response:

{
  "notifications": [
    {
      "id": "notification-uuid",
      "title": "Trade Executed! 📈",
      "body": "Your buy order for 10 SOL has been executed at $142.50",
      "image": "https://example.com/notification-image.png",
      "timestamp": "2024-01-15T10:30:00Z",
      "readAt": null,
      "app": {
        "id": "app-uuid",
        "name": "SolTrader",
        "image": "https://example.com/app-logo.png"
      },
      "actions": [
        {
          "type": "link",
          "label": "View Trade",
          "url": "https://soltrader.com/trades/123"
        }
      ],
      "data": {
        "tradeId": "123",
        "amount": "10",
        "price": "142.50"
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6ImFsZXJ0XzEyMyIsInRpbWVzdGFtcCI6MTcwNTMwNzQwMH0="
}

​
Pagination Example

async function getAllNotifications() {
  const notifications = [];
  let cursor = null;
  let hasMore = true;

  while (hasMore) {
    const url = cursor 
      ? `https://alerts-api.dial.to/v2/history?cursor=${cursor}&limit=50`
      : 'https://alerts-api.dial.to/v2/history?limit=50';

    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${jwtToken}`,
        'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY'
      }
    });

    const data = await response.json();
    notifications.push(...data.notifications);
    
    hasMore = data.hasMore;
    cursor = data.nextCursor;
  }

  return notifications;
}

​
Get Notification Summary

Get unread count and summary information without full notification data:

const response = await fetch('https://alerts-api.dial.to/v2/history/summary', {
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY'
  }
});

const summary = await response.json();

Query Parameters:

  • appId (optional): Filter summary for a specific app

Response:

{
  "unreadCount": 5,
  "lastUnreadNotification": {
    "id": "notification-uuid",
    "title": "Price Alert! 🚨",
    "body": "SOL reached your target price of $150",
    "timestamp": "2024-01-15T14:20:00Z",
    "app": {
      "id": "app-uuid",
      "name": "PriceTracker"
    }
  }
}

​
Mark Notifications as Read

Mark all notifications as read for the authenticated user:

const response = await fetch('https://alerts-api.dial.to/v2/history/read', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    appId: 'YOUR_APP_ID' // Optional: mark as read for specific app only
  })
});

Request Body:

  • appId (optional): If provided, only marks notifications from this app as read

Response:

{}

​
Clear Notification History

Clear all notifications for the authenticated user. This is a global action that applies across all clients:

const response = await fetch('https://alerts-api.dial.to/v2/history/clear', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'X-Dialect-Client-Key': 'YOUR_CLIENT_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    appId: 'YOUR_APP_ID' // Optional: clear notifications for specific app only
  })
});

Request Body:

  • appId (optional): Single app ID, array of app IDs, or omitted to clear notifications from all apps

Response:

{}

​
Next Steps

With notification management in place, you can:

  1. Setup Push Notifications - Enable mobile push notifications for your inbox
  2. Explore User Management - Manage user subscriptions and preferences