# `Jido.Chat.ChannelRef`
[🔗](https://github.com/agentjido/jido_chat/blob/v1.0.0/lib/jido/chat/channel_ref.ex#L1)

Channel handle for adapter-routed posting, state, and metadata access.

# `t`

```elixir
@type t() :: %Jido.Chat.ChannelRef{
  adapter: any(),
  adapter_name: atom(),
  external_id: any(),
  id: binary(),
  metadata: map()
}
```

# `fetch_metadata`

```elixir
@spec fetch_metadata(
  t(),
  keyword()
) :: {:ok, Jido.Chat.ChannelInfo.t()} | {:error, term()}
```

Fetches channel metadata as `Jido.Chat.ChannelInfo`.

# `from_map`

```elixir
@spec from_map(map()) :: t()
```

Builds a channel ref from serialized map data.

# `mention_user`

```elixir
@spec mention_user(t(), String.t() | integer()) :: String.t()
```

Renders adapter-specific mention format for a user id.

# `messages`

```elixir
@spec messages(t(), keyword() | map() | Jido.Chat.FetchOptions.t()) ::
  {:ok, Jido.Chat.MessagePage.t()} | {:error, term()}
```

Fetches a page of channel-level messages when supported.

# `messages_stream`

```elixir
@spec messages_stream(t(), keyword() | map() | Jido.Chat.FetchOptions.t()) ::
  Enumerable.t()
```

Returns a lazy stream over channel messages using cursor pagination.

# `name`

```elixir
@spec name(t()) :: String.t() | nil
```

Returns cached channel name from metadata when present.

# `new`

Creates a channel reference.

# `open_modal`

```elixir
@spec open_modal(t(), Jido.Chat.Modal.t() | map(), keyword()) ::
  {:ok, Jido.Chat.ModalResult.t()} | {:error, term()}
```

Opens a modal in the channel when supported by the adapter.

# `open_thread`

```elixir
@spec open_thread(t(), String.t() | integer(), keyword()) ::
  {:ok, Jido.Chat.Thread.t()} | {:error, term()}
```

Opens a native platform thread from an existing channel message when supported.

# `post`

```elixir
@spec post(
  t(),
  String.t() | Jido.Chat.Postable.t() | map() | Enumerable.t(),
  keyword()
) ::
  {:ok, Jido.Chat.SentMessage.t()} | {:error, term()}
```

Posts string/postable/stream content to channel via adapter.

# `post_ephemeral`

```elixir
@spec post_ephemeral(
  t(),
  String.t() | integer(),
  String.t() | Jido.Chat.Postable.t() | map(),
  keyword()
) :: {:ok, Jido.Chat.EphemeralMessage.t()} | {:error, term()}
```

Posts an ephemeral message via adapter when supported.

# `schema`

Returns the Zoi schema for ChannelRef.

# `send_file`

```elixir
@spec send_file(t(), Jido.Chat.FileUpload.input(), keyword()) ::
  {:ok, Jido.Chat.SentMessage.t()} | {:error, term()}
```

Uploads a file to the channel when supported by the adapter.

# `set_state`

```elixir
@spec set_state(Jido.Chat.t(), t(), atom() | term(), map() | term()) :: Jido.Chat.t()
```

Sets channel state in chat struct using :replace, :merge, or key/value modes.

# `start_typing`

```elixir
@spec start_typing(t(), String.t() | nil) :: :ok | {:error, term()}
```

Starts typing indicator on channel when supported.

# `state`

```elixir
@spec state(Jido.Chat.t(), t(), term() | nil) :: map() | term()
```

Gets channel state map or a single key from chat struct state.

# `threads`

```elixir
@spec threads(
  t(),
  keyword()
) :: {:ok, Jido.Chat.ThreadPage.t()} | {:error, term()}
```

Lists thread summaries in this channel when supported.

# `threads_stream`

```elixir
@spec threads_stream(
  t(),
  keyword()
) :: Enumerable.t()
```

Returns a lazy stream over channel thread summaries using cursor pagination.

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

Serializes channel ref into a plain map with type marker.

---

*Consult [api-reference.md](api-reference.md) for complete listing*