Broadcast

Get up and running with Realtime's Broadcast feature

Realtime Broadcast follows the publish-subscribe pattern where a client publishes messages to a channel based on a unique topic. For example, a user could send a message to a channel with topic room-1.

Other clients can receive the message in real-time by subscribing to the channel with topic room-1. These clients can continue to receive messages as long as they continue to be online and subscribed to the same channel topic.

An example use-case is sharing a user's cursor position with other clients in an online tool or game.

Quick start#

Let's explore how to implement Realtime Broadcast so you can integrate it into your use case.

Install the client

Install the Supabase JavaScript client.

  npm install @supabase/supabase-js

Create the first client

This client will be used to listen for messages.

Go to your Supabase project's API Settings and grab the URL and anon public API key.

  import {
    createClient
  } from '@supabase/supabase-js'
  const clientA = createClient(
    'https://<project>.supabase.co',
    '<your-anon-key>'
  )

Create a channel

A channel's topic can be anything except for 'realtime'.

  const channelA = clientA.channel('room-1')

Listen for messages

Specify the Broadcast event you want the on handler to listen for. This event name can be anything you want. We'll send a broadcast message with this event name later on.

  channelA
    .on(
      'broadcast',
      { event: 'test' },
      (payload) => console.log(payload)
    )
    .subscribe()

Create the second client

This client will be used to send a message.

  const clientB = createClient(
    'https://<project>.supabase.co',
    '<your-anon-key>'
  )

Create another channel

This channel's topic must match channelA's.

  const channelB = clientB.channel('room-1')

Send message

Subscribe to channel and send a message.

The payload's event must match channelA's event in the on handler.

  channelB.subscribe((status) => {
    if (status === 'SUBSCRIBED') {
      channelB.send({
        type: 'broadcast',
        event: 'test',
        payload: {
          message: 'hello, world'
        },
      })
    }
  })

First client receives message

clientA receives the message clientB sent.

Broadcast options#

There are additional Broadcast functionality that you can enable when creating a channel.

Self-send messages#

You can have a client broadcast a message and then receive the same message by setting Broadcast's self config to true. Without this, broadcast messages are only sent to other clients.

const channelC = clientC.channel('room-2', {
  config: {
    broadcast: {
      self: true,
    },
  },
})
channelC.on('broadcast', { event: 'test-my-messages' }, (payload) => console.log(payload))
channelC.subscribe((status) => {
  if (status === 'SUBSCRIBED') {
    channelC.send({
      type: 'broadcast',
      event: 'test-my-messages',
      payload: { message: 'talking to myself' },
    })
  }
})

Acknowledge messages#

You can confirm that Realtime received your message by setting Broadcast's ack config to true.

const channelD = clientD.channel('room-3', {
  config: {
    broadcast: {
      ack: true,
    },
  },
})
channelD.subscribe(async (status) => {
  if (status === 'SUBSCRIBED') {
    const resp = await channelD.send({
      type: 'broadcast',
      event: 'acknowledge',
      payload: {},
    })
    console.log('resp', resp)
  }
})

Use this to guarantee that the server has received the message before resolving channelD.send's promise. If the ack config is not set to true when creating the channel, the promise returned by channelD.send will resolve immediately.

Client-side rate limit#

By default the client will rate limit itself at 10 messages per second (1 message every 100 milliseconds). You can customize this when creating the client:

import { createClient } from '@supabase/supabase-js'
const clientE = createClient('https://<project>.supabase.co', '<your-anon-key>', {
  realtime: {
    params: {
      eventsPerSecond: 20,
    },
  },
})

By setting eventsPerSecond to 20, you can send one message every 50 milliseconds on a per client basis.

Learn more by visiting the Quotas section.

More Realtime Quickstarts#

Edit this page on GitHub