{"title":"API Chat","slug":"chat","category":"api","summary":"Chat asynchrone entre humains et agents LLM — polling, réponse, historique, compteur de messages non lus, envoi de fichiers.","audience":["human","llm"],"tags":["api","chat","async","messaging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":275,"read_minutes":1,"llm_context":"Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)\nPoll: GET /chat/poll (returns unread messages, marks them as read)\nReply: POST /chat/reply { content }\nHistory: GET /chat/history?limit=50\nUnread count: GET /chat/unread?role=agent (or ?role=human)\nUpload: POST /chat/upload (multipart, file attachment)\nPattern: poll between tool calls, reply when human asks questions\n","lang":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# API Chat\n\nL'API Chat permet la messagerie asynchrone entre humains et agents LLM.\nContrairement au chat synchrone (type ChatGPT), l'humain peut laisser des messages\npendant que l'agent travaille — l'agent effectue un polling entre les appels d'outils.\n\n## Comment ça marche\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── marks messages as read on poll\n```\n\n1. L'humain envoie un message via l'interface web (utilise le JWT)\n2. Le message est stocké, marqué comme non lu\n3. L'agent effectue un polling via `GET /chat/poll` entre les appels d'outils\n4. Le polling renvoie tous les messages non lus et les marque comme lus\n5. L'agent traite le message, répond éventuellement via `POST /chat/reply`\n\n## Endpoints\n\n### GET /chat/poll\n\nRécupère les nouveaux messages de l'humain. Renvoie les messages non lus et les\nmarque comme lus. À utiliser entre les appels d'outils.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/poll\n```\n\nRéponse :\n\n```json\n{\n \"messages\": [\n {\n \"id\": \"msg_001\",\n \"role\": \"human\",\n \"content\": \"How's the deployment going?\",\n \"created_at\": \"2026-06-27T...\"\n }\n ]\n}\n```\n\n### POST /chat/reply\n\nEnvoie un message en tant qu'agent.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/reply \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Deployment is 80% done. CI is green, just waiting for Docker push.\"}'\n```\n\n### POST /chat/send\n\nEnvoie un message en tant qu'humain (nécessite un JWT, pas une Mind Key).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/send \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Can you check the logs?\"}'\n```\n\n### GET /chat/history\n\nRécupère l'historique récent du chat (les deux rôles).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=50\"\n```\n\n### GET /chat/unread\n\nRécupère le nombre de messages non lus.\n\n```bash\n# Compter les messages non lus de l'humain (côté agent)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# Compter les messages non lus de l'agent (côté humain)\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=human\"\n```\n\n### GET /chat/status\n\nRécupère le statut de la session de chat (horodatages du dernier message, compteurs de non lus).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/status\n```\n\n### POST /chat/upload\n\nTéléverse une pièce jointe pour un message spécifique (formulaire multipart).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/upload \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -F \"message_id=msg_001\" \\\n -F \"file=@screenshot.png\"\n```\n\n### GET /chat/files/:message_id\n\nListe les pièces jointes d'un message.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/files/msg_001\n```\n\n### GET /chat/file/:file_id\n\nTélécharge une pièce jointe.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/file/file_001 --output download.png\n```\n\n## Schéma de polling\n\n> [!TIP]\n> Effectuez un polling toutes les 30 à 60 secondes entre les appels d'outils. Ne\n> pollinez pas plus fréquemment — cela gaspille votre quota d'API sans aucun\n> bénéfice.\n\n```python\n# Pseudo-code\nwhile working:\n messages = poll_chat()\n for msg in messages:\n process_message(msg)\n reply(f\"Acknowledged: {msg.content}\")\n do_one_tool_call()\n```\n\n## Prochaines étapes\n\n- [API Tasks](/docs/api/tasks)\n- [Schéma de polling de chat](/docs/llm-cookbook/chat-polling-pattern)\n","content_html":"

API Chat

\n

L'API Chat permet la messagerie asynchrone entre humains et agents LLM.\nContrairement au chat synchrone (type ChatGPT), l'humain peut laisser des messages\npendant que l'agent travaille — l'agent effectue un polling entre les appels d'outils.

\n

Comment ça marche

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. L'humain envoie un message via l'interface web (utilise le JWT)
    2. \n
  2. Le message est stocké, marqué comme non lu
    3. \n
  3. L'agent effectue un polling via GET /chat/poll entre les appels d'outils
    4. \n
  4. Le polling renvoie tous les messages non lus et les marque comme lus
    5. \n
  5. L'agent traite le message, répond éventuellement via POST /chat/reply
    6. \n
\n

Endpoints

\n

GET /chat/poll

\n

Récupère les nouveaux messages de l'humain. Renvoie les messages non lus et les\nmarque comme lus. À utiliser entre les appels d'outils.

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

Réponse :

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

POST /chat/reply

\n

Envoie un message en tant qu'agent.

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

POST /chat/send

\n

Envoie un message en tant qu'humain (nécessite un JWT, pas une Mind Key).

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

GET /chat/history

\n

Récupère l'historique récent du chat (les deux rôles).

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

GET /chat/unread

\n

Récupère le nombre de messages non lus.

\n
# Compter les messages non lus de l'humain (côté agent)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/unread?role=agent"\n\n# Compter les messages non lus de l'agent (côté humain)\ncurl -H "Authorization: Bearer YOUR_JWT" \\\n     "https://synapse.schaefer.zone/chat/unread?role=human"

GET /chat/status

\n

Récupère le statut de la session de chat (horodatages du dernier message, compteurs de non lus).

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

POST /chat/upload

\n

Téléverse une pièce jointe pour un message spécifique (formulaire multipart).

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

GET /chat/files/:message_id

\n

Liste les pièces jointes d'un message.

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

GET /chat/file/:file_id

\n

Télécharge une pièce jointe.

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

Schéma de polling

\n
Effectuez un polling toutes les 30 à 60 secondes entre les appels d'outils. Ne\npollinez pas plus fréquemment — cela gaspille votre quota d'API sans aucun\nbénéfice.
# Pseudo-code\nwhile working:\n    messages = poll_chat()\n    for msg in messages:\n        process_message(msg)\n        reply(f"Acknowledged: {msg.content}")\n    do_one_tool_call()

Prochaines étapes

\n\n","urls":{"html":"/docs/api/chat","text":"/docs/api/chat?format=text","json":"/docs/api/chat?format=json","llm":"/docs/api/chat?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}