Skip to main content

Client Messages

In addition to publishing messages server-side, connected WebSocket clients can also publish messages if they're authorized to do so.

Publish Permissions​

A connected client can publish messages, but only if they have explicit publish permissions to do so for a given event in a particular channel.

Let's take a chat room example. Assume each person in the room.123 channel need to send two types of events - one to indicate to other subscribers that they are typing and another to pass each sent chat message.

Your token must authorize subscribe access to the channel and grant publish access to both the is-typing and chat events. Setting echo to true on chat events allows the sender to receive a copy of those messages despite also being the sender. There's no need for the sender to also know that they are typing, so is-typing is not echoed.

{
  "channels": {
    "room.123": {
      "subscribe": true,
      "messages": {
        "is-typing": {
          "publish": true
        },
        "chat": {
          "publish": true,
          "echo": true
        }
      }
    }
  }
}

On the WebSocket, the client can now send a message when they begin typing.

> {"channel":"room.123","event":"is-typing"}

Other members of the channel will receive a copy. All client-initiated messages include the sender uid and umd in the meta attribute.

< {"id":"01J663WM0781SKS3FDWVV0G884","event":"is-typing","channel":"room.123","data":null,"meta":{"uid":"Jim","umd":null}}

Similarly the client can publish chat messages on the WebSocket.

> {"channel":"room.123","event":"chat","data":"Hello! I just wanted to say hi ❤️"}

All channel subscribers will receive a copy of this message. But this one will also send a copy to the sender (because of the echo directive).

< {"id":"01J664PF9MFZPADFA0N5AJB42R","event":"chat","channel":"room.123","data":"Hello! I just wanted to say hi ❤️","meta":{"uid":"Jim","umd":null}}

You can see this chat example in action in the Real-Time Chat demo.

Broadcasting Without A Subscription​

In some cases, you may want clients to send messages to a channel without being subscribed to it. This is useful for scenarios like sending telemetry data, usage metrics, or notifications to channels where the sender doesn't need to receive messages back.

The broadcast claim allows clients to publish messages to channels they aren't subscribed to. This is particularly useful for one-way communication patterns.

Usage Metrics Example​

Consider a scenario where you want to collect product usage metrics from client applications. Each user has their own metrics channel (e.g., user.123.metrics) where usage data is sent and stored, but the client doesn't need to subscribe to receive messages from this channel.

{
  "scope": "connect",
  "uid": "123",
  "channels": {
    "user.123.metrics": {
      "messages": {
        "usage.*": {
          "broadcast": true,
          "store": 63072000
        }
      }
    }
  }
}

With this token, the client can send usage metrics without subscribing to the channel:

> {"channel":"user.123.metrics","event":"usage.feature-click","data":{"feature":"dashboard","timestamp":1695123456}}

The message is stored for 2 years (store: 63072000 seconds) but no subscribers receive it in real-time since no one is subscribed to the channel. This pattern is perfect for:

  • Analytics and telemetry: Send usage data, performance metrics, or error reports.
  • Audit logging: Record user actions for compliance or debugging.
  • Background notifications: Send status updates to channels monitored by backend systems.

Key Differences​

  • publish: Requires an active subscription to the channel, messages are received by all subscribers including the sender (if echo: true).
  • broadcast: Does not require subscription, allows sending messages to channels where you're not subscribed.
tip

Use broadcast when you need one-way communication to channels that serve as data collection points, and publish for interactive, real-time messaging between subscribed participants.