Jido.Chat.MessagingTarget (Jido Chat v1.0.0)

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")

Summary

Types

context()

kind()

reply_mode()

t()

Functions

for_reply(ctx, reply_mode)

Creates a MessagingTarget configured for replying to a message.

for_room(external_id, opts \\ [])

Creates a MessagingTarget for a specific room/chat.

for_thread(external_id, thread_id, opts \\ [])

Creates a MessagingTarget for a specific thread.

from_context(ctx)

Creates a MessagingTarget from a normalized context map.

schema()

Returns the Zoi schema for MessagingTarget

to_send_opts(target)

Returns options suitable for passing to channel send_message functions.

Types

context()

@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()

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

reply_mode()

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

t()

@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()
}

Functions

for_reply(ctx, reply_mode)

@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(external_id, opts \\ [])

@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(external_id, thread_id, opts \\ [])

@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(ctx)

@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(target)

@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.