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

Canonical outbound message target.

MessagingTarget provides a unified representation for outbound message routing,
supporting DMs, groups, threads, and various reply modes. It abstracts away
platform-specific targeting details while preserving the information needed
for accurate message delivery.

## Reply Modes

  * `:inline` - Reply as a direct response in the same context
  * `:thread` - Reply in a thread (creates one if needed)
  * `:platform_default` - Use the platform's default reply behavior

## Usage

    # Create target from incoming context
    target = MessagingTarget.from_context(msg_context)

    # Create reply target with specific mode
    target = MessagingTarget.for_reply(msg_context, :thread)

    # Create target for a specific room
    target = MessagingTarget.for_room("external_room_123")

# `context`

```elixir
@type context() :: %{
  :external_room_id => String.t() | integer(),
  optional(:chat_type) => atom(),
  optional(:external_thread_id) => String.t() | nil,
  optional(:external_message_id) => String.t() | nil,
  optional(:bridge_id) => String.t() | nil,
  optional(:instance_id) => String.t() | nil,
  optional(:channel_type) => atom() | nil
}
```

# `kind`

```elixir
@type kind() :: :room | :dm | :thread
```

# `reply_mode`

```elixir
@type reply_mode() :: :inline | :thread | :platform_default
```

# `t`

```elixir
@type t() :: %Jido.Chat.MessagingTarget{
  channel_type: nil | nil | atom(),
  external_id: binary(),
  instance_id: nil | nil | binary(),
  kind: :room | :dm | :thread,
  reply_to_id: nil | nil | binary(),
  reply_to_mode: :inline | :thread | :platform_default,
  thread_id: nil | nil | binary()
}
```

# `for_reply`

```elixir
@spec for_reply(context(), reply_mode()) :: t()
```

Creates a MessagingTarget configured for replying to a message.

## Parameters

  * `ctx` - The MsgContext of the message being replied to
  * `reply_mode` - How to reply: `:inline`, `:thread`, or `:platform_default`

## Examples

    # Reply in a thread
    target = MessagingTarget.for_reply(ctx, :thread)

    # Reply inline
    target = MessagingTarget.for_reply(ctx, :inline)

# `for_room`

```elixir
@spec for_room(
  String.t(),
  keyword()
) :: t()
```

Creates a MessagingTarget for a specific room/chat.

Use this when sending a proactive message (not a reply).

## Examples

    target = MessagingTarget.for_room("chat_123")
    target = MessagingTarget.for_room("chat_123", kind: :dm, channel_type: :telegram)

# `for_thread`

```elixir
@spec for_thread(String.t(), String.t(), keyword()) :: t()
```

Creates a MessagingTarget for a specific thread.

## Examples

    target = MessagingTarget.for_thread("chat_123", "thread_456")

# `from_context`

```elixir
@spec from_context(context()) :: t()
```

Creates a MessagingTarget from a normalized context map.

The target kind is inferred from the chat type:
  * `:direct` chat type -> `:dm` kind
  * `:thread` chat type -> `:thread` kind
  * otherwise -> `:room` kind

## Examples

    iex> ctx = %{external_room_id: "123", chat_type: :direct}
    iex> target = MessagingTarget.from_context(ctx)
    iex> target.kind
    :dm

# `schema`

Returns the Zoi schema for MessagingTarget

# `to_send_opts`

```elixir
@spec to_send_opts(t()) :: keyword()
```

Returns options suitable for passing to channel send_message functions.

Converts the target into keyword options that channels can use.

---

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