Azure Web Pubsub Ts

1---
2name: azure-web-pubsub-ts
3description: Build real-time messaging applications using Azure Web PubSub SDKs for JavaScript (@azure/web-pubsub, @azure/web-pubsub-client). Use when implementing WebSocket-based real-time features, pub/sub messaging, group chat, or live notifications.
4package: "@azure/web-pubsub, @azure/web-pubsub-client"
5---
6 
7# Azure Web PubSub SDKs for TypeScript
8 
9Real-time messaging with WebSocket connections and pub/sub patterns.
10 
11## Installation
12 
13```bash
14# Server-side management
15npm install @azure/web-pubsub @azure/identity
16 
17# Client-side real-time messaging
18npm install @azure/web-pubsub-client
19 
20# Express middleware for event handlers
21npm install @azure/web-pubsub-express
22```
23 
24## Environment Variables
25 
26```bash
27WEBPUBSUB_CONNECTION_STRING=Endpoint=https://<resource>.webpubsub.azure.com;AccessKey=<key>;Version=1.0;
28WEBPUBSUB_ENDPOINT=https://<resource>.webpubsub.azure.com
29```
30 
31## Server-Side: WebPubSubServiceClient
32 
33### Authentication
34 
35```typescript
36import { WebPubSubServiceClient, AzureKeyCredential } from "@azure/web-pubsub";
37import { DefaultAzureCredential } from "@azure/identity";
38 
39// Connection string
40const client = new WebPubSubServiceClient(
41  process.env.WEBPUBSUB_CONNECTION_STRING!,
42  "chat"  // hub name
43);
44 
45// DefaultAzureCredential (recommended)
46const client2 = new WebPubSubServiceClient(
47  process.env.WEBPUBSUB_ENDPOINT!,
48  new DefaultAzureCredential(),
49  "chat"
50);
51 
52// AzureKeyCredential
53const client3 = new WebPubSubServiceClient(
54  process.env.WEBPUBSUB_ENDPOINT!,
55  new AzureKeyCredential("<access-key>"),
56  "chat"
57);
58```
59 
60### Generate Client Access Token
61 
62```typescript
63// Basic token
64const token = await client.getClientAccessToken();
65console.log(token.url);  // wss://...?access_token=...
66 
67// Token with user ID
68const userToken = await client.getClientAccessToken({
69  userId: "user123",
70});
71 
72// Token with permissions
73const permToken = await client.getClientAccessToken({
74  userId: "user123",
75  roles: [
76    "webpubsub.joinLeaveGroup",
77    "webpubsub.sendToGroup",
78    "webpubsub.sendToGroup.chat-room",  // specific group
79  ],
80  groups: ["chat-room"],  // auto-join on connect
81  expirationTimeInMinutes: 60,
82});
83```
84 
85### Send Messages
86 
87```typescript
88// Broadcast to all connections in hub
89await client.sendToAll({ message: "Hello everyone!" });
90await client.sendToAll("Plain text", { contentType: "text/plain" });
91 
92// Send to specific user (all their connections)
93await client.sendToUser("user123", { message: "Hello!" });
94 
95// Send to specific connection
96await client.sendToConnection("connectionId", { data: "Direct message" });
97 
98// Send with filter (OData syntax)
99await client.sendToAll({ message: "Filtered" }, {
100  filter: "userId ne 'admin'",
101});
102```
103 
104### Group Management
105 
106```typescript
107const group = client.group("chat-room");
108 
109// Add user/connection to group
110await group.addUser("user123");
111await group.addConnection("connectionId");
112 
113// Remove from group
114await group.removeUser("user123");
115 
116// Send to group
117await group.sendToAll({ message: "Group message" });
118 
119// Close all connections in group
120await group.closeAllConnections({ reason: "Maintenance" });
121```
122 
123### Connection Management
124 
125```typescript
126// Check existence
127const userExists = await client.userExists("user123");
128const connExists = await client.connectionExists("connectionId");
129 
130// Close connections
131await client.closeConnection("connectionId", { reason: "Kicked" });
132await client.closeUserConnections("user123");
133await client.closeAllConnections();
134 
135// Permissions
136await client.grantPermission("connectionId", "sendToGroup", { targetName: "chat" });
137await client.revokePermission("connectionId", "sendToGroup", { targetName: "chat" });
138```
139 
140## Client-Side: WebPubSubClient
141 
142### Connect
143 
144```typescript
145import { WebPubSubClient } from "@azure/web-pubsub-client";
146 
147// Direct URL
148const client = new WebPubSubClient("<client-access-url>");
149 
150// Dynamic URL from negotiate endpoint
151const client2 = new WebPubSubClient({
152  getClientAccessUrl: async () => {
153    const response = await fetch("/negotiate");
154    const { url } = await response.json();
155    return url;
156  },
157});
158 
159// Register handlers BEFORE starting
160client.on("connected", (e) => {
161  console.log(`Connected: ${e.connectionId}`);
162});
163 
164client.on("group-message", (e) => {
165  console.log(`${e.message.group}: ${e.message.data}`);
166});
167 
168await client.start();
169```
170 
171### Send Messages
172 
173```typescript
174// Join group first
175await client.joinGroup("chat-room");
176 
177// Send to group
178await client.sendToGroup("chat-room", "Hello!", "text");
179await client.sendToGroup("chat-room", { type: "message", content: "Hi" }, "json");
180 
181// Send options
182await client.sendToGroup("chat-room", "Hello", "text", {
183  noEcho: true,        // Don't echo back to sender
184  fireAndForget: true, // Don't wait for ack
185});
186 
187// Send event to server
188await client.sendEvent("userAction", { action: "typing" }, "json");
189```
190 
191### Event Handlers
192 
193```typescript
194// Connection lifecycle
195client.on("connected", (e) => {
196  console.log(`Connected: ${e.connectionId}, User: ${e.userId}`);
197});
198 
199client.on("disconnected", (e) => {
200  console.log(`Disconnected: ${e.message}`);
201});
202 
203client.on("stopped", () => {
204  console.log("Client stopped");
205});
206 
207// Messages
208client.on("group-message", (e) => {
209  console.log(`[${e.message.group}] ${e.message.fromUserId}: ${e.message.data}`);
210});
211 
212client.on("server-message", (e) => {
213  console.log(`Server: ${e.message.data}`);
214});
215 
216// Rejoin failure
217client.on("rejoin-group-failed", (e) => {
218  console.log(`Failed to rejoin ${e.group}: ${e.error}`);
219});
220```
221 
222## Express Event Handler
223 
224```typescript
225import express from "express";
226import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
227 
228const app = express();
229 
230const handler = new WebPubSubEventHandler("chat", {
231  path: "/api/webpubsub/hubs/chat/",
232  
233  // Blocking: approve/reject connection
234  handleConnect: (req, res) => {
235    if (!req.claims?.sub) {
236      res.fail(401, "Authentication required");
237      return;
238    }
239    res.success({
240      userId: req.claims.sub[0],
241      groups: ["general"],
242      roles: ["webpubsub.sendToGroup"],
243    });
244  },
245  
246  // Blocking: handle custom events
247  handleUserEvent: (req, res) => {
248    console.log(`Event from ${req.context.userId}:`, req.data);
249    res.success(`Received: ${req.data}`, "text");
250  },
251  
252  // Non-blocking
253  onConnected: (req) => {
254    console.log(`Client connected: ${req.context.connectionId}`);
255  },
256  
257  onDisconnected: (req) => {
258    console.log(`Client disconnected: ${req.context.connectionId}`);
259  },
260});
261 
262app.use(handler.getMiddleware());
263 
264// Negotiate endpoint
265app.get("/negotiate", async (req, res) => {
266  const token = await serviceClient.getClientAccessToken({
267    userId: req.user?.id,
268  });
269  res.json({ url: token.url });
270});
271 
272app.listen(8080);
273```
274 
275## Key Types
276 
277```typescript
278// Server
279import {
280  WebPubSubServiceClient,
281  WebPubSubGroup,
282  GenerateClientTokenOptions,
283  HubSendToAllOptions,
284} from "@azure/web-pubsub";
285 
286// Client
287import {
288  WebPubSubClient,
289  WebPubSubClientOptions,
290  OnConnectedArgs,
291  OnGroupDataMessageArgs,
292} from "@azure/web-pubsub-client";
293 
294// Express
295import {
296  WebPubSubEventHandler,
297  ConnectRequest,
298  UserEventRequest,
299  ConnectResponseHandler,
300} from "@azure/web-pubsub-express";
301```
302 
303## Best Practices
304 
3051. **Use Entra ID auth** - `DefaultAzureCredential` for production
3062. **Register handlers before start** - Don't miss initial events
3073. **Use groups for channels** - Organize messages by topic/room
3084. **Handle reconnection** - Client auto-reconnects by default
3095. **Validate in handleConnect** - Reject unauthorized connections early
3106. **Use noEcho** - Prevent message echo back to sender when needed
311