# `ClaudeAgentSDK.Message`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.17.2/lib/claude_agent_sdk/message.ex#L1)

Represents a message from Claude Code CLI.

Messages are the core data structure returned by the Claude Code SDK. They represent
different types of communication during a conversation with Claude, including system
initialization, user inputs, assistant responses, and final results.

This SDK is CLI-faithful: when the Claude CLI emits distinct message frames, the Elixir
SDK prefers surfacing them directly even if the current Python SDK filters some unknown
message types for forward compatibility.

## Message Types

- `:system` - Session initialization messages with metadata
- `:user` - User input messages (echoed back from CLI)
- `:assistant` - Claude's response messages containing the actual AI output
- `:rate_limit_event` - Rate limit state changes emitted by the CLI
- `:result` - Final result messages with cost, duration, and completion status

Assistant messages may optionally include an `error` code when the CLI surfaces
an issue (e.g., `:rate_limit` or `:authentication_failed`).

## Result Subtypes

- `:success` - Successful completion
- `:error_max_turns` - Terminated due to max turns limit
- `:error_during_execution` - Error occurred during execution

## System Subtypes

- `:init` - Initial system message with session setup

## Examples

    # Assistant message
    %ClaudeAgentSDK.Message{
      type: :assistant,
      subtype: nil,
      data: %{
        message: %{"content" => "Hello! How can I help?"},
        session_id: "session-123"
      }
    }

    # Assistant message with error metadata
    %ClaudeAgentSDK.Message{
      type: :assistant,
      subtype: nil,
      data: %{
        message: %{"content" => "Please try again later."},
        session_id: "session-123",
        error: :rate_limit
      }
    }

    # Result message
    %ClaudeAgentSDK.Message{
      type: :result,
      subtype: :success,
      data: %{
        total_cost_usd: 0.001,
        duration_ms: 1500,
        num_turns: 2,
        session_id: "session-123"
      }
    }

# `assistant_data`

```elixir
@type assistant_data() :: %{
  :message => map(),
  :session_id => String.t() | nil,
  optional(:parent_tool_use_id) => String.t() | nil,
  optional(:error) => assistant_error() | nil
}
```

# `assistant_error`

```elixir
@type assistant_error() :: ClaudeAgentSDK.AssistantError.t()
```

# `message_type`

```elixir
@type message_type() ::
  :assistant
  | :user
  | :result
  | :system
  | :stream_event
  | :rate_limit_event
  | :unknown
  | String.t()
```

# `rate_limit_data`

```elixir
@type rate_limit_data() :: %{
  rate_limit_info: rate_limit_info(),
  uuid: String.t(),
  session_id: String.t()
}
```

# `rate_limit_info`

```elixir
@type rate_limit_info() :: %{
  :status => String.t(),
  optional(:resets_at) => integer() | nil,
  optional(:rate_limit_type) => String.t() | nil,
  optional(:utilization) => float() | integer() | nil,
  optional(:is_using_overage) => boolean() | nil,
  optional(:overage_status) => String.t() | nil,
  optional(:overage_resets_at) => integer() | nil,
  optional(:overage_disabled_reason) => String.t() | nil,
  optional(:raw) => map()
}
```

# `result_subtype`

```elixir
@type result_subtype() ::
  :success | :error_max_turns | :error_during_execution | String.t()
```

# `system_subtype`

```elixir
@type system_subtype() :: :init | String.t()
```

# `t`

```elixir
@type t() :: %ClaudeAgentSDK.Message{
  data: assistant_data() | map(),
  raw: map(),
  subtype: result_subtype() | system_subtype() | nil,
  type: message_type()
}
```

# `content_blocks`

```elixir
@spec content_blocks(t()) :: [map()]
```

Returns parsed content blocks for `:user` and `:assistant` messages.

This is an ergonomic alternative to the Python SDK's typed content-block objects.

# `error?`

```elixir
@spec error?(t()) :: boolean()
```

Checks if the message indicates an error.

Returns `true` for result messages with error subtypes
(`:error_max_turns` or `:error_during_execution`).

# `final?`

```elixir
@spec final?(t()) :: boolean()
```

Checks if the message is a final result message.

Final messages indicate the end of a conversation or query.

## Parameters

- `message` - The message to check

## Returns

`true` if the message is a final result, `false` otherwise.

## Examples

    iex> ClaudeAgentSDK.Message.final?(%ClaudeAgentSDK.Message{type: :result})
    true

    iex> ClaudeAgentSDK.Message.final?(%ClaudeAgentSDK.Message{type: :assistant})
    false

# `from_json`

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

Parses a JSON message from Claude Code into a Message struct.

## Parameters

- `json_string` - Raw JSON string from Claude CLI

## Returns

- `{:ok, message}` - Successfully parsed message
- `{:error, reason}` - Parsing failed

## Examples

    iex> ClaudeAgentSDK.Message.from_json(~s({"type":"assistant","message":{"content":"Hello"}}))
    {:ok, %ClaudeAgentSDK.Message{type: :assistant, ...}}

# `session_id`

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

Gets the session ID from a message.

Returns `nil` if the message does not contain a session ID.

# `user_uuid`

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

Returns the checkpoint UUID from a user message, or nil.

Used with file checkpointing to identify rewind targets.

---

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