Home Documentation Messaging Service Chat Integration Guides Quick Start Guide

Quick Start Guide

Last updated: January 2026

Welcome to the Agglestone Messaging Service chat integration guide. This quick start will help you get real-time chat 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 chat functionality.

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 chat 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 chat 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
// This allows the server to exclude this specific client from messaging events when you send a message
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 chat message notifications
connection.on("MessagingEvent", async (event) => {
  // IMPORTANT: The WebSocket event only contains lightweight information
  // You must fetch the full message 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 message details from the REST API when a notification is received
  • Update your UI with new messages
  • Handle connection state changes (disconnected, reconnecting, reconnected)

What Happens When a Message is Sent

When a user sends a message in a chat, here’s what happens behind the scenes:

  1. Message Creation: Your application sends a POST request to /tenant/{tenantId}/v1/Chat/{chatId}/messages with the message content.
  2. Message Persistence: The message is immediately stored in the database and assigned a unique message ID.
  3. Real-Time Notification: The service sends a lightweight MessagingEvent through the SignalR WebSocket connection to all members of the chat who are currently connected. This event contains:
    • id: The message ID
    • type: “Chat” (indicating this is a chat message)
    • parentId: The chat ID this message belongs to
    • timestamp: When the notification was sent
  4. Client Processing: When your application receives the MessagingEvent, it calls the REST API to fetch the full message details using the message ID and chat ID.
  5. UI Update: Your application displays the new message in the chat interface.

Important: The WebSocket notification is intentionally lightweight – it only tells you that a new message exists. You must fetch the full message details from the REST API to get the sender information, message content, 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 chats and messages. For example, to create a new chat:

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

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

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

Note: All API calls require a valid JWT access token in the Authorization: Bearer {token} header.

For more information on creating chats and sending messages, see Creating Chats and Sending Messages.

> 📚 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 chat functionality working, you can: