---
id: messages---comfyui
title: "Messages - ComfyUI"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: []
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.8
created_at: 2026-05-20
updated_at: 2026-05-20
review_reason: ""
merge_history: []
tags: ["web", "wikify"]
raw_sources: ["https://docs.comfy.org/development/comfyui-server/comms_messages"]
applied_in: []
github_commit: ""
---

# [[Messages - ComfyUI]]

## 🎯 한 줄 통찰 (One-line insight)
[[ComfyUI]] 서버와 클라이언트 간의 실시간 데이터 교환을 위해 [[PromptExecutor]]가 [[PromptServer]]를 통해 메시지를 전송하고, 클라이언트는 소켓 이벤트를 통해 이를 수신하여 처리하는 통신 메커니즘.

## 🧠 핵심 개념 (Core concepts)
- **메시지 전달 구조**: [[PromptExecutor]]가 실행 중 또는 큐 상태 변경 시 [[PromptServer]]의 `send_sync` 메서드를 통해 클라이언트로 메시지를 전송함.
- **클라이언트 수신 방식**: [[api.js]]에 정의된 소켓 이벤트 리스너가 `CustomEvent` 객체를 생성하여 등록된 리스너로 디스패치함.
- **확장성 (Extensibility)**: 기본 제공되는 메시지 타입 외에도 클라이언트와 서버 양측에서 사용자 정의 메시지 타입을 추가하고 처리할 수 있음.
- **데이터 구조**: 메시지 핸들러는 `CustomEvent`를 통해 전달받으며, `.detail` 속성을 통해 서버가 보낸 데이터 딕셔너리에 접근 가능함.

## 🧩 추출된 패턴 (Extracted patterns)
- **이벤트 기반 통신**: 클라이언트 측에서 `api.addEventListener(message_type, messageHandler)` 형식을 사용하여 특정 메시지 타입에 대한 이벤트를 등록하는 표준 JavaScript 관용구 사용.
- **자동 유형 인식**: 정의되지 않은 새로운 메시지 타입이 들어오면 클라이언트는 이를 자동으로 알려진 메시지 목록에 추가함.
 o **서버-클라이언트 동기화**: 서버 측에서는 `PromptServer.instance.send_sync`를 통해, 클라이언트 측에서는 리스너 등록을 통해 양방향 통신 구조를 형성함.

## 📖 세부 내용 (Details)

### 1. 내장 메시지 타입 (Built in message types)
[[PromptServer]]의 `send_sync` 메서드를 통해 전달되는 주요 이벤트와 그 데이터 구성은 다음과 같습니다.

| event | when data |
| :--- | :--- |
| execution_start | When a prompt is about to run: `prompt_id` |
| execution_error | When an error occurs during execution: `prompt_id`, plus additional information |
| execution_interrupted | When execution is stopped by a node raising `InterruptProcessingException`: `prompt_id`, `node_id`, `node_type` and executed (a list of executed nodes) |
| execution_cached | At the start of execution: `prompt_id`, `nodes` (a list of nodes which are being skipped because their cached outputs can be used) |
| execution_success | When all nodes from the prompt have been successfully executed: `prompt_id`, `timestamp` |
| executing | When a new node is about to be executed: `node` (node id or None to indicate completion), `prompt_id` |
| executed | When a node returns a ui element: `node` (node id), `prompt_id`, `output` |
| progress | During execution of a node that implements the required hook: `node` (node id), `prompt_id`, `value`, `max` |
| status | When the state of the queue changes: `exec_info`, a dictionary holding `queue_remaining` (the number of entries in the queue) |

### 2. 실행된 메시지 활용 (Using executed)
'executed' 메시지는 단순히 노드가 실행을 완료할 때 전송되는 것이 아니라, **노드가 UI 업데이트를 반환할 때만** 전송됩니다. 이를 위해 메인 함수는 튜플 대신 다음과 같은 구조의 딕셔 необходимо 합니다:
- `return { "ui": a_new_dictionary, "result": the_tuple_of_output_values }`
- `a_new_dictionary`는 `output` 값으로 전송되며, 결과 키(`result`)는 출력값이 없는 경우 생략 가능합니다.

### 3. 사용자 정의 메시지 타입 (Custom message types)
- **클라이언트 측**: `api.addEventListener("my.custom.message", messageHandler);`와 같이 고유한 이름으로 리스너를 등록하여 구현합니다.
- **서버 측**: `PromptServer.instance.send_sync("my.custom.message", a_dictionary)`를 사용하여 데이터를 전송합니다.

### 4. 노드 ID 획득 (Getting node_id)
내장 메시지에는 현재 노드의 ID가 포함되는 경우가 많습니다. 서버 측에서 이를 활용하기 위해 `INPUT_TYPES`의 `hidden` 키를 사용하여 `node_id`를 가져올 수 있습니다.
```python
@classmethod
def INPUT_TYPES(s):
    return {"required" : { }, "hidden": { "node_id": "UNIQUE_ID" } }
```

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
본문에서 'executed' 메시지라는 명칭과 실제 동작(UI 업데이트가 있을 때만 전송됨) 사이의 차이점에 대해 설명하고 있습니다.

## 🛠️ 적용 사례 (Applied in summary)
- **커스텀 노드 개발**: `INPUT_TYPES` 내 `hidden` 설정을 통해 서버 측에서 `node_id`를 식별하고 이를 메시지에 포함시켜 클라이언트에 전달하는 사례.
- **확장 기능(Extension) 구현**: `setup()` 함수 내에서 `api.addEventListener`를 사용하여 특정 이벤트에 대한 핸들러를 등록하는 사례.

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual
- **출처 신뢰도:** B (Primary Source — 웹사이트 본문 직접 추출)
- **중복 검사 결과:** 신규 생성 (New discovery)

## 🔗 관련 문서 링크 (Related document links)
- [[PromptExecutor]]: 메시지를 클라이언트로 전송하는 주체.
- [[PromptServer]]: `send_sync` 메서드를 통해 메시지 전달을 담당하는 서버 구성 요소.
- [[api.js]]: 소켓 이벤트 리스너가 정의되어 있는 클라이언트 측 핵심 파일.
- [[InterruptProcessingException]]: 실행 중단 시 발생하는 예외 타입.
- [[INPUT_TYPES]]: 노드의 입력 타입을 정의하며 `node_id`를 숨겨진 값으로 가져오는 데 사용됨.

## 📝 변경 이력 (Change history)
- 2026-05-20: Astra /wikify 로 https://docs.comfy.org/development/comfyui-server/comms_messages 본문에서 초안 생성.