Supabase.Realtime.Channel (supabase_realtime v0.5.0)

Copy Markdown

Represents a subscription channel for Supabase Realtime events.

A channel narrows the scope of data flow to subscribed clients. Each channel is created with a topic and can hold multiple event bindings.

Broadcast Options

When creating a channel, you can pass broadcast options:

  • broadcast: [self: true] - Receive your own broadcast messages on this channel. By default, the server does not echo your broadcasts back to you.
  • broadcast: [ack: true] - Enable delivery confirmation for broadcasts. Use broadcast_with_ack/3 and wait_for_ack/2 to send and confirm.
  • broadcast: [replay: [since: epoch, limit: n]] - Enable message replay for missed broadcasts. Only available on private channels. The since value is a Unix epoch timestamp (integer) and limit is the max number of messages to replay (server max: 25).

Presence

  • presence: [key: "user:123"] - Set a custom presence key for this channel. This key identifies the client in presence state maps.

Wildcard Events

You can subscribe to all events of a given type using event: :all or event: "*". This works for both broadcast and postgres_changes bindings.

Realtime.on(channel, "broadcast", event: "*")
Realtime.on(channel, "postgres_changes", event: :all, schema: "public")

Example

{:ok, channel} = MyApp.Realtime.channel("room:lobby",
  broadcast: [self: true, ack: true],
  presence: [key: "user:42"]
)

# With message replay on a private channel
{:ok, channel} = MyApp.Realtime.channel("private:room",
  broadcast: [replay: [since: 1_700_000_000, limit: 25]],
  private: true
)

Summary

Types

t()

Channel structure for Supabase Realtime subscriptions.

Functions

ack_enabled?(arg1)

Checks if acknowledgments are enabled for this channel.

add_binding(channel, type, filter, callback \\ nil)

Adds a binding for an event type.

add_pending_ack(channel, ack_ref, caller)

Adds a pending acknowledgment to the channel.

can_push?(arg1)

Checks if a push can be sent on this channel.

closed?(arg1)

Checks if the channel is closed.

errored?(arg1)

Checks if the channel is in an error state.

get_ack_caller(channel, ack_ref)

Gets the caller process for a pending acknowledgment.

joined?(arg1)

Checks if the channel is joined (subscribed).

joining?(arg1)

Checks if the channel is in the process of joining.

leaving?(arg1)

Checks if the channel is in the process of leaving.

new(topic, registry, opts \\ [])

Creates a new channel struct.

remove_binding(channel, type, filter)

Removes bindings for an event type.

remove_pending_ack(channel, ack_ref)

Removes a pending acknowledgment from the channel.

set_join_ref(channel, join_ref)

Sets the join reference for the channel.

update_state(channel, state)

Updates the channel state.

Types

t()

@type t() :: %Supabase.Realtime.Channel{
  bindings: map(),
  join_ref: Supabase.Realtime.ref() | nil,
  params: map(),
  pending_acks: map(),
  ref: String.t(),
  registry: pid() | atom(),
  state: Supabase.Realtime.channel_state(),
  timeout: pos_integer(),
  topic: String.t()
}

Channel structure for Supabase Realtime subscriptions.

Fields:

  • topic - The channel topic string
  • registry - The channel registry process or module
  • bindings - Event bindings for this channel
  • state - Current state of the channel
  • join_ref - Reference for the join message
  • timeout - Timeout for operations in milliseconds
  • params - Additional parameters for the channel
  • ref - Unique reference for this channel
  • pending_acks - Map of pending acknowledgment references and their details

Functions

ack_enabled?(arg1)

@spec ack_enabled?(t()) :: boolean()

Checks if acknowledgments are enabled for this channel.

Parameters

  • channel - The channel struct

Returns

  • boolean - True if acknowledgments are enabled, false otherwise

add_binding(channel, type, filter, callback \\ nil)

@spec add_binding(t(), String.t(), Enumerable.t(), (map() -> any()) | nil) :: t()

Adds a binding for an event type.

Parameters

  • channel - The channel struct
  • type - The event type
  • filter - The event filter
  • callback - Optional callback function

Returns

  • %Channel{} - Updated channel struct

add_pending_ack(channel, ack_ref, caller)

@spec add_pending_ack(t(), String.t(), pid()) :: t()

Adds a pending acknowledgment to the channel.

Parameters

  • channel - The channel struct
  • ack_ref - The acknowledgment reference
  • caller - The process that will receive the acknowledgment

Returns

  • %Channel{} - Updated channel struct

can_push?(arg1)

@spec can_push?(t()) :: boolean()

Checks if a push can be sent on this channel.

A push can be sent when the channel is joined and the client is connected.

Parameters

  • channel - The channel struct

Returns

  • boolean - True if a push can be sent, false otherwise

closed?(arg1)

@spec closed?(t()) :: boolean()

Checks if the channel is closed.

Parameters

  • channel - The channel struct

Returns

  • boolean - True if closed, false otherwise

errored?(arg1)

@spec errored?(t()) :: boolean()

Checks if the channel is in an error state.

Parameters

  • channel - The channel struct

Returns

  • boolean - True if errored, false otherwise

get_ack_caller(channel, ack_ref)

@spec get_ack_caller(t(), String.t()) :: {:ok, pid()} | :error

Gets the caller process for a pending acknowledgment.

Parameters

  • channel - The channel struct
  • ack_ref - The acknowledgment reference

Returns

  • {:ok, pid()} - The caller process
  • :error - Acknowledgment not found

joined?(arg1)

@spec joined?(t()) :: boolean()

Checks if the channel is joined (subscribed).

Parameters

  • channel - The channel struct

Returns

  • boolean - True if joined, false otherwise

joining?(arg1)

@spec joining?(t()) :: boolean()

Checks if the channel is in the process of joining.

Parameters

  • channel - The channel struct

Returns

  • boolean - True if joining, false otherwise

leaving?(arg1)

@spec leaving?(t()) :: boolean()

Checks if the channel is in the process of leaving.

Parameters

  • channel - The channel struct

Returns

  • boolean - True if leaving, false otherwise

new(topic, registry, opts \\ [])

@spec new(String.t(), pid() | atom(), keyword()) :: t()

Creates a new channel struct.

Parameters

  • topic - The topic to subscribe to
  • registry - The channel registry module or PID
  • opts - Additional options for the channel

Options

  • :timeout - Timeout for operations in milliseconds (default: 10000)
  • :params - Additional parameters for the channel
  • :ref - Optional reference for the channel

Returns

  • %Channel{} - A channel struct

remove_binding(channel, type, filter)

@spec remove_binding(t(), String.t(), map() | keyword()) :: t()

Removes bindings for an event type.

Parameters

  • channel - The channel struct
  • type - The event type
  • filter - The event filter

Returns

  • %Channel{} - Updated channel struct

remove_pending_ack(channel, ack_ref)

@spec remove_pending_ack(t(), String.t()) :: t()

Removes a pending acknowledgment from the channel.

Parameters

  • channel - The channel struct
  • ack_ref - The acknowledgment reference

Returns

  • %Channel{} - Updated channel struct

set_join_ref(channel, join_ref)

@spec set_join_ref(t(), Supabase.Realtime.ref()) :: t()

Sets the join reference for the channel.

Parameters

  • channel - The channel struct
  • join_ref - The join reference

Returns

  • %Channel{} - Updated channel struct

update_state(channel, state)

@spec update_state(t(), Supabase.Realtime.channel_state()) :: t()

Updates the channel state.

Parameters

  • channel - The channel struct
  • state - The new state

Returns

  • %Channel{} - Updated channel struct