Chat & Streaming Guide

The Agrinet conversation engine provides real-time messaging, bot responders, and streaming status updates via Server-Sent Events (SSE). Use this guide to integrate chat UX, automate support flows, and monitor conversation state changes.

Conversations

Create Conversation

POST /conversations

{
  "title": "Contract 45AB Support",
  "participants": ["user_prod7", "user_buyer1"],
  "metadata": {
    "contractId": "contract_45ab",
    "channel": "web"
  }
}

Response:

{
  "id": "conv_91c2",
  "title": "Contract 45AB Support",
  "createdAt": "2025-03-02T11:20:01.002Z"
}

List Conversations

GET /conversations?participant=user_prod7

Returns conversation summaries including unread counts, last message preview, and linked contract IDs.

Messages

Send Message

POST /messages/:conversationId

{
  "from": "user_prod7",
  "to": "user_buyer1",
  "type": "text",
  "content": "Shipment is on schedule.",
  "attachments": [
    {
      "url": "https://cdn.example.org/uploads/photo.jpg",
      "contentType": "image/jpeg"
    }
  ]
}

Supported message type values: text, image, file, ping. Files are stored under /uploads.

Fetch Messages

GET /messages/:conversationId?limit=50&before=<messageId>

Returns a paginated array of message objects with read receipts and metadata such as isAutomated when generated by responders.

Streaming (SSE)

Subscribe to Conversation Stream

GET /stream/:conversationId

Headers:

Accept: text/event-stream
x-api-key: <service-key>

Sample event payload:

event: message
id: msg_ae12
data: {"conversationId":"conv_91c2","messageId":"msg_ae12","type":"text","from":"agrinet-responder","content":"Here is the delivery checklist."}

Global Event Feed

GET /events

Use this feed to capture contract pings, notifications, and background job status changes. Events emit type fields such as ping.update, federation.sync, and notification.read.

Bot Responders

Two responder services are available:

• Agrinet responder (backend/services/agrinetResponder.js) — Provides rule-based knowledge and contextual prompts.
• OpenAI responder (backend/services/openAIResponder.js) — Optional integration with external LLMs for advanced replies.

Enable or disable responders per conversation by sending:

POST /conversations/:conversationId/bots

{
  "bot": "agrinet",
  "enabled": true
}

Authentication & Security

• JWTs secure user-driven chat; API keys (x-api-key) secure SSE and bot control calls.
• OAuth2 providers can exchange access tokens through /api/auth/oauth/callback.
• McEliese key issuance endpoints (/api/keys) set streaming limits and expiration.

Monitoring & Troubleshooting

• Track message delivery via /messages/:conversationId/delivery logs.
• Inspect SSE heartbeats (event: ping) to detect dropped connections.
• Use background workers to retry failed bot invocations and queue SMS fallbacks for offline participants.

Combine chat with the notifications and SMS guides to implement omnichannel support for producers and buyers.