Server-Side Usage - Upstash Documentation

Use Upstash Realtime on the server to emit events, subscribe to channels, and retrieve message history.

Emit Events#

Emit events from any server context:

route.ts

import { realtime } from "@/lib/realtime"export const POST = async () => {  await realtime.emit("notification.alert", "hello world!")  return new Response("OK")}

Emit to specific channels:

route.ts

import { realtime } from "@/lib/realtime"export const POST = async () => {  const channel = realtime.channel("user-123")  await channel.emit("notification.alert", "hello world!")  return new Response("OK")}

Subscribe to events on a channel:

route.ts

import { realtime } from "@/lib/realtime"const unsubscribe = await realtime.channel("notifications").subscribe({  events: ["notification.alert"],  onData({ event, data, channel }) {    console.log("New notification:", data)  },})

Subscribe to multiple events:

route.ts

import { realtime } from "@/lib/realtime"const unsubscribe = await realtime.channel("room-123").subscribe({  events: ["chat.message", "user.joined", "user.left"],  onData({ event, data, channel }) {    // 👇 data is automatically typed based on the event    if (event === "chat.message") console.log("New message:", data)    if (event === "user.joined") console.log("User joined:", data)    if (event === "user.left") console.log("User left:", data)  },})

Unsubscribe#

Clean up subscriptions when done:

route.ts

import { realtime } from "@/lib/realtime"const channel = realtime.channel("room-123")const unsubscribe = await channel.subscribe({  events: ["chat.message"],  onData({ data }) {    console.log("Message:", data)  },})unsubscribe()// or: channel.unsubscribe()

Retrieve History#

Fetch past messages from a channel:

route.ts

import { realtime } from "@/lib/realtime"export const GET = async () => {  const messages = await realtime.channel("room-123").history()  return new Response(JSON.stringify(messages))}

History Options#

limitnumber#

Maximum number of messages to retrieve (capped at 1000)

Default: "1000"

startnumber#

Fetch messages after this Unix timestamp (in milliseconds)

endnumber#

Fetch messages before this Unix timestamp (in milliseconds)

route.ts

const messages = await realtime.channel("room-123").history({  limit: 100,  start: Date.now() - 86400000,})

History Response#

Each history message contains:

type HistoryMessage = {  id: string  event: string  channel: string  data: unknown}

Replay past messages and continue subscribing to new ones:

route.ts

import { realtime } from "@/lib/realtime"const channel = realtime.channel("room-123")await channel.subscribe({  events: ["chat.message"],  history: true,  onData({ event, data, channel }) {    console.log("Message:", data)  },})

Pass history options:

route.ts

await channel.subscribe({  events: ["chat.message"],  history: {    limit: 50,    start: Date.now() - 3600000,  },  onData({ data }) {    console.log("Message:", data)  },})

This pattern:

Fetches messages matching the history criteria
Replays them in chronological order
Continues to listen for new messages

Use Cases#

Background Jobs

Stream progress updates from long-running tasks:

app/api/job/route.ts

import { realtime } from "@/lib/realtime"export const POST = async (req: Request) => {  const { jobId } = await req.json()  const channel = realtime.channel(jobId)  await channel.emit("job.started", { progress: 0 })  for (let i = 0; i <= 100; i += 10) {    await processChunk()    await channel.emit("job.progress", { progress: i })  }  await channel.emit("job.completed", { progress: 100 })  return new Response("OK")}

Event Processing

Process events with server-side logic:

route.ts

import { realtime } from "@/lib/realtime"import { sendEmail } from "@/lib/email"await realtime.channel("notifications").subscribe({  events: ["notification.alert"],  onData: async ({ data }) => {    if (data.priority === "high") {      await sendEmail({        to: data.userId,        subject: "Urgent Notification",        body: data.message,      })    }  },})

Multi-Channel Broadcasting

Emit events to multiple channels:

route.ts

import { realtime } from "@/lib/realtime"export const POST = async (req: Request) => {  const { teamIds, message } = await req.json()  await Promise.all(    teamIds.map((teamId: string) =>      realtime.channel(`team-${teamId}`).emit("announcement", message)    )  )  return new Response("Broadcast sent")}

Webhook Processing

Forward webhook events to realtime channels:

app/api/webhook/route.ts

import { realtime } from "@/lib/realtime"export const POST = async (req: Request) => {  const payload = await req.json()  const channel = realtime.channel(`user-${payload.userId}`)  await channel.emit("webhook.received", payload)  return new Response("OK")}

Next Steps#

History

Configure message retention and expiration

Channels

Scope events to specific rooms or users

Emit Events#

Subscribe to Events#

Unsubscribe#

Retrieve History#

History Options#

History Response#

Subscribe with History#

Use Cases#

Next Steps#