When and how to use Daily’s new custom session data feature

Developers often find themselves needing to implement some sort of shared state in their web applications. Orchestrating this can be time consuming and introduces another layer of complexity to the work of writing, testing, and maintaining a codebase. Do you want a server-based approach with a database (or something like a Redis cache)? Do you want a client-side solution with clients passing data around to each other? Engineering a solution can take many different forms, and implementation can get complicated and time consuming.

Daily’s Client SDK for JavaScript already provides some tools to simplify this for client-side-only implementations, including our "app-message" events and custom user data features. For instances where data needs extend beyond the participant object, or where dispatching "app-message" events isn't suitable, having the ability to associate a blob of data for all participants can be useful.

This is why we’re expanding our JavaScript client-side state functionality with custom session data: a new set of call object instance methods allowing developers to store state at the level of a video call session. This feature simplifies per-session state, catering to common needs like stateful UIs, client-synced layout changes, and engagement features (such as polls or breakout rooms) without additional infrastructure.

In this post, I’ll start by exploring some use cases for custom session data. I’ll then go over our existing client-side state features and clarify when (and how!) to use each one.

In a followup post, we’ll go through a hands-on tutorial in which we'll use this new feature in a simple demo app.

Use cases for custom session data

Custom session data is available for call-object based implementations using daily-js. It is not available in Daily Prebuilt at this time. However, it does power our Daily Prebuilt breakout rooms feature under the hood, which is a great example of how this new functionality can be used.

Here are just a few other custom session data use cases that we’ve heard of from developers working with Daily:

  • State-powered UI/layout changes (common in events or live fitness, similar to OBS ‘scenes’)
  • Engagement features such as polls or Q&A
  • “Bring to stage” functionality

So how do you decide between using custom session data, ”app-message" events, custom user data, or a server-side implementation? Let’s take a closer look.

When to use custom session data

  • Use custom session state to send  session-scoped data to all existing and new call participants.
  • Any call participant can set custom session data, and custom session data is not tied to any one participant.

One example might be to set a session-wide message that any participant can update (this is what we’ll build in our upcoming custom session data tutorial!)

How to use custom session data

For custom session data, you’ll be using the following call object instance methods and events:

When to use  ”app-message” events

  • Use "app-message" events to send participant-scoped data between existing call participants.
  • Each participant can only send "app-message" events on behalf of themselves.

One example where "app-message" is preferred can be a chat implementation. Each call client would send an "app-message" event to all other clients to broadcast their chat message.

How to use "app-message"

For ”app-message” events, you’ll be using the following call object constructs:

When to use custom user data

  • Use custom user data to send participant-scoped data to all existing and new call participants.
  • A participant can only send their own local data.

One example where custom user data might be used is tracking whether a participant has their hand raised. In fact, actually use this for our own Daily Prebuilt hand-raising feature (we like to eat our dog food around here.)

How to use custom user data

For custom user data, you’ll be using the following call object instance methods and events:

  • setUserData() : Method to set your own user data.
  • participants(): Method to retrieve all call participants, which also provides access to each participant’s user data.
  • "participant-updated": Event alerting call participants when any participant has been updated. This will be emitted when a participant’s user data has been updated as well.

When to use a server component

You can also use your own server component for state handling and communicating relevant state to call participants. Two common approaches for this include WebSockets or HTTP. A few possible scenarios when a server component can be preferred to client-side handling include:

  • Handling sensitive data which requires an API key or other secret to access.
  • Handling data which requires additional validation outside of any one client’s control (i.e., avoiding tampering.)
  • Handling data which might need additional processing that you want to offload to a server for performance reasons.

I’ve previously written about choosing between "app-message" and WebSockets to send data to call participants, and most of that post applies to custom user data and custom session data as well.


You should now have all the information you need to get started using Daily’s new custom session data features. What’s more, you should have a solid grasp of when to use which client-side state functionality (and when to use a server!)

Keep an eye out for an upcoming post with a hands-on tutorial of custom session data usage.

If you have any questions about your specific use case, our support team is always happy to help. Alternatively, you can reach out at peerConnection, our WebRTC community.

Never miss a story

Get the latest direct to your inbox.