# Chat API

Chat API मानव और LLM एजेंट्स के बीच अतुल्यकालिक मैसेजिंग सक्षम करता है। तुल्यकालिक चैट (ChatGPT-शैली) के विपरीत, मानव एजेंट के काम कर रहे होने पर भी संदेश छोड़ सकता है — एजेंट टूल कॉल्स के बीच poll करता है।

## यह कैसे काम करता है

```
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. Poll सभी अपठित संदेश लौटाता है और उन्हें पठित के रूप में चिह्नित करता है
5. एजेंट संदेश को प्रोसेस करता है, वैकल्पिक रूप से `POST /chat/reply` के माध्यम से उत्तर देता है

## एंडपॉइंट्स

### GET /chat/poll

मानव के नए संदेशों के लिए 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
```

## Polling पैटर्न

> [!TIP]
> टूल कॉल्स के बीच हर 30-60 सेकंड में poll करें। अधिक बार poll न करें — यह 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)