# `Lightning.AiAssistant.ChatMessage`
[🔗](https://github.com/OpenFn/lightning/blob/main/lib/lightning/ai_assistant/chat_message.ex#L1)

Represents a message within an AI chat session.

Messages can be from users (role: :user) or from the AI assistant (role: :assistant).
User messages start with :pending status and are updated based on processing results.
Assistant messages typically have :success status when created.

## Schema Fields

* `content` - The text content of the message (required, 1-10,000 characters)
* `code` - Optional code associated with the message (e.g., generated workflows)
* `response_segments` - Optional display timeline of text and status segments
  for assistant messages (global chat); `[]` for flat messages (the column
  is NULL, which `embeds_many` loads as an empty list)
* `role` - Who sent the message: `:user` or `:assistant`
* `status` - Processing status: `:pending`, `:processing`, `:success`,
  `:error`, or `:cancelled`
* `failure_category` - Why a failed message failed, for grouping; `nil` on
  anything that has not failed
* `failure_message` - The sentence a person reads for that failure, at most
  500 characters; `nil` alongside a `nil` category
* `is_deleted` - Soft deletion flag (defaults to false)
* `is_public` - Whether the message is publicly visible (defaults to true)
* `meta` - Additional metadata (e.g., `"unsaved_job"` for job data not yet saved)
* `chat_session_id` - Reference to the parent chat session
* `user_id` - Reference to the user who sent the message (required for user messages)

# `role`

```elixir
@type role() :: :user | :assistant
```

# `status`

```elixir
@type status() :: :pending | :processing | :success | :error | :cancelled
```

# `t`

```elixir
@type t() :: %Lightning.AiAssistant.ChatMessage{
  __meta__: term(),
  chat_session: term(),
  chat_session_id: Ecto.UUID.t(),
  code: String.t() | nil,
  content: String.t() | nil,
  failure_category: term(),
  failure_message: term(),
  id: Ecto.UUID.t(),
  inserted_at: DateTime.t(),
  is_deleted: boolean(),
  is_public: boolean(),
  job: term(),
  job_id: Ecto.UUID.t() | nil,
  meta: map() | nil,
  processing_completed_at: DateTime.t() | nil,
  processing_started_at: DateTime.t() | nil,
  response_segments: [Lightning.AiAssistant.ChatMessage.Segment.t()],
  role: role(),
  status: status(),
  updated_at: DateTime.t(),
  user: term(),
  user_id: Ecto.UUID.t() | nil
}
```

# `changeset`

Creates a changeset for a chat message.

## Parameters

* `chat_message` - The ChatMessage struct to update (typically `%ChatMessage{}`)
* `attrs` - Map of attributes to set/update

## Validation Rules

* `content` and `role` are required
* `content` must be between 1 and 10,000 characters
* `response_segments`, when present, must be `200` or
  fewer segments, each with a `type` of `text` or `status` and a `content`
  string of at most `10000` characters
* User messages (role: `:user`) require an associated user
* Status defaults based on role: `:pending` for users, `:success` for assistant
* If status is explicitly provided, it takes precedence over role-based defaults

# `max_content_length`

Maximum length of a message's `content`.

# `max_failure_message_length`

Maximum length of a message's `failure_message`.

# `max_response_segments`

Maximum number of segments accepted on a message.

# `status_changeset`

Creates a changeset for updating message status.

This is a focused changeset that only updates the status field,
useful for updating message state during processing.

## Parameters

* `chat_message` - The existing ChatMessage struct
* `status` - New status (`:pending`, `:success`, `:error`, or `:cancelled`)

## Examples

    # Mark message as successful
    ChatMessage.status_changeset(message, :success)

    # Mark message as failed
    ChatMessage.status_changeset(message, :error)

---

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