# Chat API

Chat API는 사람과 LLM 에이전트 간의 비동기 메시징을 지원합니다.
동기식 채팅(ChatGPT 스타일)과 달리, 사람은 에이전트가 작업 중인 동안에도
메시지를 남길 수 있으며 — 에이전트는 도구 호출 사이에 폴링합니다.

## 작동 방식

```
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)
                                     │
                                     └── marks messages as read on poll
```

1. 사람이 웹 UI를 통해 메시지를 전송합니다 (JWT 사용)
2. 메시지가 저장되고 읽지 않음으로 표시됩니다
3. 에이전트는 도구 호출 사이에 `GET /chat/poll`을 폴링합니다
4. 폴링은 모든 읽지 않은 메시지를 반환하고 읽음으로 표시합니다
5. 에이전트는 메시지를 처리하고, 선택적으로 `POST /chat/reply`로 응답합니다

## 엔드포인트

### GET /chat/poll

사람이 보낸 새 메시지를 폴링합니다. 읽지 않은 메시지를 반환하고 읽음으로
표시합니다. 도구 호출 사이에 사용하십시오.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/poll
```

응답:

```json
{
  "messages": [
    {
      "id": "msg_001",
      "role": "human",
      "content": "How's the deployment going?",
      "created_at": "2026-06-27T..."
    }
  ]
}
```

### POST /chat/reply

에이전트로 메시지를 전송합니다.

```bash
curl -X POST https://synapse.schaefer.zone/chat/reply \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deployment is 80% done. CI is green, just waiting for Docker push."}'
```

### POST /chat/send

사람으로 메시지를 전송합니다 (Mind Key가 아닌 JWT 필요).

```bash
curl -X POST https://synapse.schaefer.zone/chat/send \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"content": "Can you check the logs?"}'
```

### GET /chat/history

최근 채팅 기록을 가져옵니다 (양쪽 역할 모두).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?limit=50"
```

### GET /chat/unread

읽지 않은 메시지 수를 가져옵니다.

```bash
# Count unread messages from human (for agent)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# Count unread messages from agent (for human)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"
```

### GET /chat/status

채팅 세션 상태를 가져옵니다 (마지막 메시지 타임스탬프, 읽지 않은 메시지 수).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/status
```

### POST /chat/upload

특정 메시지의 파일 첨부를 업로드합니다 (multipart 폼).

```bash
curl -X POST https://synapse.schaefer.zone/chat/upload \
  -H "Authorization: Bearer YOUR_JWT" \
  -F "message_id=msg_001" \
  -F "file=@screenshot.png"
```

### GET /chat/files/:message_id

메시지의 파일 첨부 목록을 조회합니다.

```bash
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/files/msg_001
```

### GET /chat/file/:file_id

파일 첨부를 다운로드합니다.

```bash
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/file/file_001 --output download.png
```

## 폴링 패턴

> [!TIP]
> 도구 호출 사이에 30-60초마다 폴링하십시오. 더 자주 폴링하지 마십시오 —
> API 할당량을 낭비하고 이점이 없습니다.

```python
# Pseudo-code
while working:
    messages = poll_chat()
    for msg in messages:
        process_message(msg)
        reply(f"Acknowledged: {msg.content}")
    do_one_tool_call()
```

## 다음 단계

- [Tasks API](/docs/api/tasks)
- [Chat Polling Pattern](/docs/llm-cookbook/chat-polling-pattern)