Home Documentation Messaging Service Notifications Integration Guides Quick Start Guide

Quick Start Guide

Last updated: January 2026

Welcome to the Agglestone Messaging Service notifications integration guide. This quick start will help you get notification functionality working in your application in minutes.

Getting Started

The Agglestone Messaging Service is available at https://messaging.agglestone.com/ and uses standard WebSocket (SignalR) and REST API protocols for real-time notification delivery.

Don’t have your Tenant ID yet? Log into your account at https://portal.agglestone.com to find your Tenant ID. Then replace {tenantId} or your-tenant-id in the examples below with your own Tenant ID.

Using the SignalR Client Library (Recommended)

The easiest way to integrate real-time notifications into your application is to use a standard SignalR client library. We recommend @microsoft/signalr@^10.0.0 for TypeScript applications. This client-side library handles WebSocket connections, automatic reconnection, and message delivery – all the client-side communication complexity is handled for you.

npm install @microsoft/signalr@^10.0.0

> 🤖 Quick Integration Tip: Why not point your favourite AI software development tool at this page, and tell it you want to add Agglestone Messaging Service notification functionality to your application – speed up development, with the reliability of battle tested backend services!

Here’s a basic setup to get you started:

// Install: npm install @microsoft/signalr@^10.0.0
import * as signalR from '@microsoft/signalr';

const tenantId = 'your-tenant-id'; // Get this from https://portal.agglestone.com
const apiBaseUrl = 'https://messaging.agglestone.com'; // Agglestone's messaging service URL

// Generate a unique client ID for this browser tab/window
const clientId = crypto.randomUUID();

// Create SignalR connection
const connection = new signalR.HubConnectionBuilder()
  .withUrl(`${apiBaseUrl}/tenant/${tenantId}/v1/hub?clientId=${encodeURIComponent(clientId)}`, {
    accessTokenFactory: () => accessToken // JWT token from authentication service
  })
  .withAutomaticReconnect()
  .build();

// Listen for notification events
connection.on("MessagingEvent", async (event) => {
  // IMPORTANT: The WebSocket event only contains lightweight information
  // You must fetch the full notification details using the REST API
});

// Start the connection
try {
  await connection.start();
  console.log('Connected to SignalR hub');
} catch (error) {
  console.error('Connection error:', error);
}

What the SignalR client library handles automatically:

  • WebSocket connection management
  • Automatic reconnection when connection is lost
  • Token-based authentication via accessTokenFactory
  • Message delivery and event handling

What you need to implement:

  • Provide JWT access token via accessTokenFactory
  • Handle MessagingEvent messages from the WebSocket
  • Fetch full notification details from the REST API when a notification is received
  • Update your UI with new notifications
  • Handle connection state changes (disconnected, reconnecting, reconnected)

What Happens When a Notification is Created

When a notification is created for a user, here’s what happens behind the scenes:

  1. Notification Creation: Your application (or another service) sends a POST request to /tenant/{tenantId}/v1/Notifications with the notification content.
  2. Notification Persistence: The notification is immediately stored in the user’s inbox and assigned a unique notification ID.
  3. Real-Time Notification: If the user is currently connected via WebSocket, the service sends a lightweight MessagingEvent through the SignalR WebSocket connection. This event contains:
    • id: The notification ID
    • type: “Message” (indicating this is a notification message)
    • timestamp: When the notification was sent
  4. Email Delivery (Optional): If email delivery is configured, the notification may also be sent via email to ensure the user doesn’t miss it.
  5. Client Processing: When your application receives the MessagingEvent, it calls the REST API to fetch the full notification details using the notification ID.
  6. UI Update: Your application displays the new notification in the user’s inbox or notification center.

Important: The WebSocket notification is intentionally lightweight – it only tells you that a new notification exists. You must fetch the full notification details from the REST API to get the subject, message content, priority, timestamp, and other details.

Making Your First API Call

Once you have a WebSocket connection established, you can start using the REST API to manage notifications. For example, to create a new notification:

POST https://messaging.agglestone.com/tenant/{tenantId}/v1/Notifications

Example: Let’s say your Tenant ID is 79199f3a-6669-4a21-ac5f-5dec93d90b57, then the call to create a notification would be:

POST https://messaging.agglestone.com/tenant/79199f3a-6669-4a21-ac5f-5dec93d90b57/v1/Notifications

⚠️ Authorization Required: The create notification endpoint requires Admin privileges or API Key authentication:

  • Admin Users: Include a valid JWT access token in the Authorization: Bearer {token} header. The user must have Admin group privileges.
  • Backend Services: Include your API Key in the X-API-Key header. ⚠️ Security Warning: API Keys should NEVER be exposed in frontend code. They should only be used in secure backend services that cannot be accessed by end users.

For more information on creating and sending notifications, see Creating and Sending Notifications.

> 📚 API Documentation: For detailed API documentation, request/response schemas, and to try out the endpoints interactively, visit the Swagger UI.

—

Next Steps

Once you have basic notification functionality working, you can: