Realtime overview

A durable function can run for minutes or hours, retry after failures, and continue after the request that started it has ended. Realtime lets that function report back to the user as it goes. It publishes messages from inside the run, and every authorized client watching the same channel receives them.

For example, a document-processing function can publish Analyzing as it starts, stream generated text as a model returns it, and publish the final result when it finishes.

The pieces

• Channel. A named stream for one thing users watch, such as document:abc123. You define a channel once and reuse it in your function, your token route, and your UI.
• Topic. A message type within a channel, such as status, tokens, or result. Each topic has a schema, so publishers and subscribers agree on the payload.
• Publish. Your function or other server-side code sends a message to one topic on one channel.
• Subscription token. Your server mints a token for one channel and a list of topics after it checks that the user may read them. The browser can't subscribe without one.
• Subscriber. A browser, through the useRealtime React hook, or server-side code that reads a stream of messages.

How a message reaches the browser

Realtime delivers each message to the clients connected when it's published. Subscribe before the function publishes the updates you need to show. The quick start does this by starting the function only after the connection opens.

Durable and immediate publishing

Choose a publish method based on what a retry should do.

• step.realtime.publish() is a durable step. Inngest memoizes it like any other step, so a retry after it completes doesn't publish the message again. Use it for state changes and final results.
• inngest.realtime.publish() sends immediately and isn't memoized. If the surrounding work retries, it can publish the same message again. Use it for streamed tokens and frequent progress updates, where a repeat is acceptable. It also works in API routes, webhooks, and other server-side code outside a function.

Inside a function, call inngest.realtime.publish() from within step.run(). Code outside a step can run again when the function resumes after a wait or retry, so a publish there can repeat.

Security model

A channel name routes messages; it doesn't grant access. Your server grants access when it mints a token. Check that the signed-in user may read the underlying document, job, or thread before you mint one, and include only the topics that view needs. Your Inngest signing key stays on the server.

Next steps

• Quick start builds a working publish-and-subscribe example.
• Channels and topics explains channel names, topics, and schemas.
• Subscription tokens shows how to authorize viewers.
• Reference lists every Realtime API.