Jido.Chat (Jido Chat v1.0.0)

Copy Markdown View Source

Core adapter-contract facade and lightweight event-loop state container.

jido_chat owns canonical chat types, adapter contracts, typed handles, and deterministic fallback behavior. It does not define the supervised runtime or process tree for production messaging systems; that responsibility belongs in jido_messaging.

Summary

Types

action_handler()

Action event handler callback.

assistant_context_changed_handler()

Assistant context changed handler callback.

assistant_thread_started_handler()

Assistant thread started handler callback.

handlers()
mention_handler()

Mention handler callback.

message_handler()

Regex-routed message handler callback.

modal_close_handler()

Modal close handler callback.

modal_submit_handler()

Modal submit handler callback.

reaction_handler()

Reaction event handler callback.

route_request_handler()
slash_command_handler()

Slash command handler callback.

subscribed_handler()

Subscribed-thread handler callback.

t()
webhook_handler()
webhook_request_handler()
webhook_request_handler_with_chat()

Functions

acquire_lock(chat, key, owner, opts \\ [])

Attempts to acquire a concurrency lock for a message-processing key.

adapter_capabilities(chat, adapter_name)

Returns adapter capability matrix wrapped in typed struct.

channel(chat, adapter_name, external_id)

Builds a channel reference from adapter + external channel id.

channel_state(chat, channel_id)

Gets channel state map by id.

concurrency(chat)

Returns normalized overlapping-message concurrency config.

configure_concurrency(chat, opts)

Updates chat-level concurrency configuration.

emoji(value, opts \\ [])

Resolves a cross-platform emoji token into a rendered value.

force_release_lock(chat, key)

Force-releases a concurrency lock regardless of owner.

from_map(map)

Builds chat state from serialized map.

get_adapter(chat, adapter_name)

Returns adapter module by name.

handle_webhook(chat, adapter_name, payload, opts \\ [])

Handles a webhook payload for the given adapter.

handle_webhook_request(chat, adapter_name, request_or_payload, opts \\ [])

Handles a typed webhook request for the given adapter.

initialize(chat)

Marks chat instance as initialized and initializes adapters when available.

lock_snapshot(chat)

Returns the current concurrency lock snapshot.

message(attrs)

Creates a normalized Chat SDK-style message.

new(opts \\ [])

Creates a new chat state struct.

new_participant(attrs)
new_room(attrs)
on_action(chat, handler)

Registers an action-event handler.

on_action(chat, selector, handler)

Registers a filtered action-event handler.

on_assistant_context_changed(chat, handler)

Registers assistant context changed handlers.

on_assistant_thread_started(chat, handler)

Registers assistant thread started handlers.

on_modal_close(chat, handler)

Registers a modal-close handler.

on_modal_close(chat, selector, handler)

Registers a filtered modal-close handler.

on_modal_submit(chat, handler)

Registers a modal-submit handler.

on_modal_submit(chat, selector, handler)

Registers a filtered modal-submit handler.

on_new_mention(chat, handler)

Registers a new-mention handler.

on_new_message(chat, pattern, handler)

Registers a new-message regex handler.

on_reaction(chat, handler)

Registers a reaction-event handler.

on_reaction(chat, selector, handler)

Registers a filtered reaction-event handler.

on_slash_command(chat, handler)

Registers a slash-command handler.

on_slash_command(chat, selector, handler)

Registers a filtered slash-command handler.

on_subscribed_message(chat, handler)

Registers a subscribed-thread handler.

open_dm(chat, adapter_name, external_user_id)

Opens a DM thread with an adapter when supported.

open_thread(chat, adapter_name, external_room_id, external_message_id, opts \\ [])

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

process_action(chat, adapter_name, event, opts \\ [])

Processes normalized action events and dispatches handlers.

process_assistant_context_changed(chat, adapter_name, event)

Processes assistant context changed events and dispatches handlers.

process_assistant_thread_started(chat, adapter_name, event)

Processes assistant thread started events and dispatches handlers.

process_event(chat, adapter_name, event, opts \\ [])

Canonical typed event router used by webhook and gateway ingestion.

process_message(chat, adapter_name, thread_id, incoming, opts \\ [])

Adapter-internal entrypoint for processing normalized incoming message events.

process_modal_close(chat, adapter_name, event, opts \\ [])

Processes normalized modal close events and dispatches handlers.

process_modal_submit(chat, adapter_name, event, opts \\ [])

Processes normalized modal submit events and dispatches handlers.

process_reaction(chat, adapter_name, event, opts \\ [])

Processes normalized reaction events and dispatches handlers.

process_slash_command(chat, adapter_name, event, opts \\ [])

Processes normalized slash command events and dispatches handlers.

put_channel_state(chat, channel_id, state)

Sets channel state map by id.

put_thread_state(chat, thread_id, state)

Sets thread state map by id.

release_lock(chat, key, owner)

Releases a held concurrency lock and returns queued/debounced entries.

reviver()

Returns a reviver function for serialized core structs.

route_event(chat, adapter_name, event, opts \\ [])

Routes an event-style inbound input (polling/gateway/listener) through process_event/4.

route_request(chat, adapter_name, request_or_payload, opts \\ [])

Routes a request-style inbound input through verification/parsing/event dispatch.

schema()

Returns the Zoi schema for Chat.

shutdown(chat)

Marks chat instance as shut down and shuts down adapters when available.

subscribe(chat, thread_id)

Subscribes a thread id.

subscribed?(chat, thread_id)

Returns true when a thread id is currently subscribed.

text(value)
thread(chat, adapter_name, external_room_id, opts \\ [])

Builds a thread reference from adapter + external room id.

thread_state(chat, thread_id)

Gets thread state map by id.

to_map(chat)

Serializes chat state to a revivable map.

unsubscribe(chat, thread_id)

Unsubscribes a thread id.

webhooks(chat)

Returns adapter-keyed request-first webhook handlers.

webhooks_with_chat(chat)

Compatibility helper returning adapter-keyed webhook handlers with explicit chat argument.

Types

action_handler()

@type action_handler() ::
  (Jido.Chat.ActionEvent.t() -> term())
  | (t(), Jido.Chat.ActionEvent.t() -> t() | term())

Action event handler callback.

assistant_context_changed_handler()

@type assistant_context_changed_handler() ::
  (Jido.Chat.AssistantContextChangedEvent.t() -> term())
  | (t(), Jido.Chat.AssistantContextChangedEvent.t() -> t() | term())

Assistant context changed handler callback.

assistant_thread_started_handler()

@type assistant_thread_started_handler() ::
  (Jido.Chat.AssistantThreadStartedEvent.t() -> term())
  | (t(), Jido.Chat.AssistantThreadStartedEvent.t() -> t() | term())

Assistant thread started handler callback.

handlers()

@type handlers() :: %{
  mention: [mention_handler()],
  message: [{Regex.t(), message_handler()}],
  subscribed: [subscribed_handler()],
  reaction: [reaction_handler()],
  action: [action_handler()],
  modal_submit: [modal_submit_handler()],
  modal_close: [modal_close_handler()],
  slash_command: [slash_command_handler()],
  assistant_thread_started: [assistant_thread_started_handler()],
  assistant_context_changed: [assistant_context_changed_handler()]
}

mention_handler()

@type mention_handler() ::
  (Jido.Chat.Thread.t(), Jido.Chat.Incoming.t() -> term())
  | (t(), Jido.Chat.Thread.t(), Jido.Chat.Incoming.t() -> t() | term())

Mention handler callback.

message_handler()

@type message_handler() :: mention_handler()

Regex-routed message handler callback.

modal_close_handler()

@type modal_close_handler() ::
  (Jido.Chat.ModalCloseEvent.t() -> term())
  | (t(), Jido.Chat.ModalCloseEvent.t() -> t() | term())

Modal close handler callback.

modal_submit_handler()

@type modal_submit_handler() ::
  (Jido.Chat.ModalSubmitEvent.t() -> term())
  | (t(), Jido.Chat.ModalSubmitEvent.t() -> t() | term())

Modal submit handler callback.

reaction_handler()

@type reaction_handler() ::
  (Jido.Chat.ReactionEvent.t() -> term())
  | (t(), Jido.Chat.ReactionEvent.t() -> t() | term())

Reaction event handler callback.

route_request_handler()

@type route_request_handler() :: (Jido.Chat.WebhookRequest.t() | map(), keyword() ->
                              {:ok, Jido.Chat.IngressResult.t()}
                              | {:error, Exception.t()})

slash_command_handler()

@type slash_command_handler() ::
  (Jido.Chat.SlashCommandEvent.t() -> term())
  | (t(), Jido.Chat.SlashCommandEvent.t() -> t() | term())

Slash command handler callback.

subscribed_handler()

@type subscribed_handler() :: mention_handler()

Subscribed-thread handler callback.

t()

@type t() :: %Jido.Chat{
  adapters: %{optional(atom()) => module()},
  channel_state: %{optional(String.t()) => map()},
  dedupe: MapSet.t({atom(), String.t()}),
  dedupe_order: [{atom(), String.t()}],
  handlers: handlers(),
  id: String.t(),
  initialized: boolean(),
  metadata: map(),
  state: term(),
  state_adapter: module(),
  subscriptions: MapSet.t(String.t()),
  thread_state: %{optional(String.t()) => map()},
  user_name: String.t()
}

webhook_handler()

@type webhook_handler() :: (t(), map(), keyword() ->
                        {:ok, t(), Jido.Chat.Incoming.t()} | {:error, term()})

webhook_request_handler()

@type webhook_request_handler() :: (Jido.Chat.WebhookRequest.t() | map(), keyword() ->
                                {:ok, t(), Jido.Chat.EventEnvelope.t() | nil,
                                 Jido.Chat.WebhookResponse.t()})

webhook_request_handler_with_chat()

@type webhook_request_handler_with_chat() :: (t(),
                                        Jido.Chat.WebhookRequest.t()
                                        | map(),
                                        keyword() ->
                                          {:ok, t(),
                                           Jido.Chat.EventEnvelope.t() | nil,
                                           Jido.Chat.WebhookResponse.t()})

Functions

acquire_lock(chat, key, owner, opts \\ [])

@spec acquire_lock(t(), String.t(), String.t(), keyword() | map()) ::
  {:acquired | :queued | :debounced | :busy, t()}

Attempts to acquire a concurrency lock for a message-processing key.

adapter_capabilities(chat, adapter_name)

@spec adapter_capabilities(t(), atom()) ::
  {:ok, Jido.Chat.CapabilityMatrix.t()} | {:error, term()}

Returns adapter capability matrix wrapped in typed struct.

channel(chat, adapter_name, external_id)

@spec channel(t(), atom(), String.t() | integer()) :: Jido.Chat.ChannelRef.t()

Builds a channel reference from adapter + external channel id.

channel_state(chat, channel_id)

@spec channel_state(t(), String.t()) :: map()

Gets channel state map by id.

concurrency(chat)

@spec concurrency(t()) :: Jido.Chat.Concurrency.t()

Returns normalized overlapping-message concurrency config.

configure_concurrency(chat, opts)

@spec configure_concurrency(t(), keyword() | map()) :: t()

Updates chat-level concurrency configuration.

emoji(value, opts \\ [])

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

Resolves a cross-platform emoji token into a rendered value.

force_release_lock(chat, key)

@spec force_release_lock(t(), String.t()) :: {{:released, [map()]}, t()}

Force-releases a concurrency lock regardless of owner.

from_map(map)

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

Builds chat state from serialized map.

get_adapter(chat, adapter_name)

@spec get_adapter(t(), atom()) :: {:ok, module()} | {:error, term()}

Returns adapter module by name.

handle_webhook(chat, adapter_name, payload, opts \\ [])

@spec handle_webhook(t(), atom(), map(), keyword()) ::
  {:ok, t(), Jido.Chat.Incoming.t()} | {:error, term()}

Handles a webhook payload for the given adapter.

handle_webhook_request(chat, adapter_name, request_or_payload, opts \\ [])

@spec handle_webhook_request(
  t(),
  atom(),
  Jido.Chat.WebhookRequest.t() | map(),
  keyword()
) ::
  {:ok, t(), Jido.Chat.EventEnvelope.t() | nil, Jido.Chat.WebhookResponse.t()}

Handles a typed webhook request for the given adapter.

Returns the updated chat state, normalized event envelope, and typed webhook response.

initialize(chat)

@spec initialize(t()) :: t()

Marks chat instance as initialized and initializes adapters when available.

lock_snapshot(chat)

@spec lock_snapshot(t()) :: %{locks: map(), pending_locks: map()}

Returns the current concurrency lock snapshot.

message(attrs)

@spec message(map()) :: Jido.Chat.Message.t()

Creates a normalized Chat SDK-style message.

new(opts \\ [])

@spec new(keyword() | map()) :: t()

Creates a new chat state struct.

Supported options:

  • :id
  • :user_name
  • :adapters - map %{telegram: Jido.Chat.Telegram.Adapter, ...}
  • :metadata
  • :state_adapter - state backend module, defaults to Jido.Chat.StateAdapters.Memory
  • :state_opts - adapter-specific initialization options
  • :state - explicit adapter state, overrides legacy snapshot inputs

new_participant(attrs)

@spec new_participant(map()) :: Jido.Chat.Participant.t()

new_room(attrs)

@spec new_room(map()) :: Jido.Chat.Room.t()

on_action(chat, handler)

@spec on_action(t(), action_handler()) :: t()

Registers an action-event handler.

on_action(chat, selector, handler)

@spec on_action(
  t(),
  String.t() | atom() | [String.t() | atom()] | Regex.t(),
  action_handler()
) :: t()

Registers a filtered action-event handler.

on_assistant_context_changed(chat, handler)

@spec on_assistant_context_changed(t(), assistant_context_changed_handler()) :: t()

Registers assistant context changed handlers.

on_assistant_thread_started(chat, handler)

@spec on_assistant_thread_started(t(), assistant_thread_started_handler()) :: t()

Registers assistant thread started handlers.

on_modal_close(chat, handler)

@spec on_modal_close(t(), modal_close_handler()) :: t()

Registers a modal-close handler.

on_modal_close(chat, selector, handler)

@spec on_modal_close(
  t(),
  String.t() | atom() | [String.t() | atom()] | Regex.t(),
  modal_close_handler()
) :: t()

Registers a filtered modal-close handler.

on_modal_submit(chat, handler)

@spec on_modal_submit(t(), modal_submit_handler()) :: t()

Registers a modal-submit handler.

on_modal_submit(chat, selector, handler)

@spec on_modal_submit(
  t(),
  String.t() | atom() | [String.t() | atom()] | Regex.t(),
  modal_submit_handler()
) :: t()

Registers a filtered modal-submit handler.

on_new_mention(chat, handler)

@spec on_new_mention(t(), mention_handler()) :: t()

Registers a new-mention handler.

on_new_message(chat, pattern, handler)

@spec on_new_message(t(), Regex.t() | String.t(), message_handler()) :: t()

Registers a new-message regex handler.

on_reaction(chat, handler)

@spec on_reaction(t(), reaction_handler()) :: t()

Registers a reaction-event handler.

on_reaction(chat, selector, handler)

@spec on_reaction(
  t(),
  String.t() | atom() | [String.t() | atom()] | Regex.t(),
  reaction_handler()
) :: t()

Registers a filtered reaction-event handler.

on_slash_command(chat, handler)

@spec on_slash_command(t(), slash_command_handler()) :: t()

Registers a slash-command handler.

on_slash_command(chat, selector, handler)

@spec on_slash_command(
  t(),
  String.t() | atom() | [String.t() | atom()] | Regex.t(),
  slash_command_handler()
) :: t()

Registers a filtered slash-command handler.

on_subscribed_message(chat, handler)

@spec on_subscribed_message(t(), subscribed_handler()) :: t()

Registers a subscribed-thread handler.

open_dm(chat, adapter_name, external_user_id)

@spec open_dm(
  t(),
  atom() | Jido.Chat.Author.t() | map() | String.t() | integer(),
  String.t() | integer() | keyword() | map()
) :: {:ok, Jido.Chat.Thread.t()} | {:error, term()}

Opens a DM thread with an adapter when supported.

open_thread(chat, adapter_name, external_room_id, external_message_id, opts \\ [])

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

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

process_action(chat, adapter_name, event, opts \\ [])

@spec process_action(t(), atom(), Jido.Chat.ActionEvent.t() | map(), keyword()) ::
  {:ok, t(), Jido.Chat.ActionEvent.t()} | {:error, term()}

Processes normalized action events and dispatches handlers.

process_assistant_context_changed(chat, adapter_name, event)

@spec process_assistant_context_changed(
  t(),
  atom(),
  Jido.Chat.AssistantContextChangedEvent.t() | map()
) :: {:ok, t(), Jido.Chat.AssistantContextChangedEvent.t()} | {:error, term()}

Processes assistant context changed events and dispatches handlers.

process_assistant_thread_started(chat, adapter_name, event)

@spec process_assistant_thread_started(
  t(),
  atom(),
  Jido.Chat.AssistantThreadStartedEvent.t() | map()
) :: {:ok, t(), Jido.Chat.AssistantThreadStartedEvent.t()} | {:error, term()}

Processes assistant thread started events and dispatches handlers.

process_event(chat, adapter_name, event, opts \\ [])

@spec process_event(t(), atom(), Jido.Chat.EventEnvelope.t() | map(), keyword()) ::
  {:ok, t(), Jido.Chat.EventEnvelope.t()} | {:error, term()}

Canonical typed event router used by webhook and gateway ingestion.

process_message(chat, adapter_name, thread_id, incoming, opts \\ [])

@spec process_message(
  t(),
  atom(),
  String.t(),
  Jido.Chat.Incoming.t() | map(),
  keyword()
) ::
  {:ok, t(), Jido.Chat.Incoming.t()} | {:error, term()}

Adapter-internal entrypoint for processing normalized incoming message events.

process_modal_close(chat, adapter_name, event, opts \\ [])

@spec process_modal_close(
  t(),
  atom(),
  Jido.Chat.ModalCloseEvent.t() | map(),
  keyword()
) ::
  {:ok, t(), Jido.Chat.ModalCloseEvent.t()} | {:error, term()}

Processes normalized modal close events and dispatches handlers.

process_modal_submit(chat, adapter_name, event, opts \\ [])

@spec process_modal_submit(
  t(),
  atom(),
  Jido.Chat.ModalSubmitEvent.t() | map(),
  keyword()
) ::
  {:ok, t(), Jido.Chat.ModalSubmitEvent.t()} | {:error, term()}

Processes normalized modal submit events and dispatches handlers.

process_reaction(chat, adapter_name, event, opts \\ [])

@spec process_reaction(t(), atom(), Jido.Chat.ReactionEvent.t() | map(), keyword()) ::
  {:ok, t(), Jido.Chat.ReactionEvent.t()} | {:error, term()}

Processes normalized reaction events and dispatches handlers.

process_slash_command(chat, adapter_name, event, opts \\ [])

@spec process_slash_command(
  t(),
  atom(),
  Jido.Chat.SlashCommandEvent.t() | map(),
  keyword()
) ::
  {:ok, t(), Jido.Chat.SlashCommandEvent.t()} | {:error, term()}

Processes normalized slash command events and dispatches handlers.

put_channel_state(chat, channel_id, state)

@spec put_channel_state(t(), String.t(), map()) :: t()

Sets channel state map by id.

put_thread_state(chat, thread_id, state)

@spec put_thread_state(t(), String.t(), map()) :: t()

Sets thread state map by id.

release_lock(chat, key, owner)

@spec release_lock(t(), String.t(), String.t()) ::
  {{:released, [map()]} | {:error, :not_owner}, t()}

Releases a held concurrency lock and returns queued/debounced entries.

reviver()

@spec reviver() :: (map() -> term())

Returns a reviver function for serialized core structs.

route_event(chat, adapter_name, event, opts \\ [])

@spec route_event(t(), atom(), Jido.Chat.EventEnvelope.t() | map() | :noop, keyword()) ::
  {:ok, Jido.Chat.IngressResult.t()} | {:error, Exception.t()}

Routes an event-style inbound input (polling/gateway/listener) through process_event/4.

This is transport-agnostic and returns a typed IngressResult.

route_request(chat, adapter_name, request_or_payload, opts \\ [])

@spec route_request(
  t(),
  atom(),
  Jido.Chat.WebhookRequest.t() | map(),
  keyword()
) :: {:ok, Jido.Chat.IngressResult.t()} | {:error, Exception.t()}

Routes a request-style inbound input through verification/parsing/event dispatch.

This is transport-agnostic and returns a typed IngressResult.

schema()

Returns the Zoi schema for Chat.

shutdown(chat)

@spec shutdown(t()) :: t()

Marks chat instance as shut down and shuts down adapters when available.

subscribe(chat, thread_id)

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

Subscribes a thread id.

subscribed?(chat, thread_id)

@spec subscribed?(t(), String.t()) :: boolean()

Returns true when a thread id is currently subscribed.

text(value)

@spec text(String.t()) :: Jido.Chat.Content.Text.t()

thread(chat, adapter_name, external_room_id, opts \\ [])

@spec thread(t(), atom(), String.t() | integer(), keyword()) :: Jido.Chat.Thread.t()

Builds a thread reference from adapter + external room id.

thread_state(chat, thread_id)

@spec thread_state(t(), String.t()) :: map()

Gets thread state map by id.

to_map(chat)

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

Serializes chat state to a revivable map.

unsubscribe(chat, thread_id)

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

Unsubscribes a thread id.

webhooks(chat)

@spec webhooks(t()) :: %{optional(atom()) => webhook_request_handler()}

Returns adapter-keyed request-first webhook handlers.

webhooks_with_chat(chat)

@spec webhooks_with_chat(t()) :: %{
  optional(atom()) => webhook_request_handler_with_chat()
}

Compatibility helper returning adapter-keyed webhook handlers with explicit chat argument.