API Reference

🔌 API Reference

All API traffic flows through the Express server on port 3000. Admin endpoints require the X-Admin-Token header.

---

→ Navigation: Home · Architecture · Setup

---

Base URL

Environment	URL
Local development	http://localhost:3000
Production	Proxied by Nginx — see Deployment

---

Authentication

Two auth mechanisms are used depending on the endpoint:

Type	Header	Used for
Bearer token	Authorization: Bearer {token}	Token refresh only — token comes from POST /conversation
Admin token	X-Admin-Token: {ADMIN_TOKEN}	All admin-protected endpoints

⚠️ The ADMIN_TOKEN value is set in server/.env and must match the token used in the admin dashboard login form exactly (case-sensitive).

---

Direct Line — Conversation Endpoints

POST /conversation

Start a new Direct Line conversation.

Auth: None required.

Response:

{
  "conversationId": "abc123",
  "token": "eyJ...",
  "expires_in": 1800,
  "streamUrl": "wss://directline.botframework.com/..."
}

The conversationId is automatically persisted to SQLite. The client opens a WebSocket to streamUrl using the returned token.

---

POST /conversation/:conversationId

Send a message to the Copilot Studio agent.

Auth: None required.

Request body:

{
  "text": "What are the graduation requirements?",
  "from": "student"
}

from is optional and defaults to "student" if omitted.

Response: Forwards the Direct Line activity response from Azure.

---

POST /conversation/:conversationId/refresh-token

Refresh an expiring Direct Line token.

Auth: Authorization: Bearer {current_token}

Response:

{
  "token": "eyJ...",
  "expires_in": 1800
}

Direct Line tokens expire after 30 minutes. The client should refresh proactively before expiry to keep long sessions alive.

---

Conversation Storage Endpoints

🔒 All endpoints in this section require the X-Admin-Token header.

GET /conversations

List all stored conversation records from SQLite.

Auth: X-Admin-Token: {ADMIN_TOKEN}

Response:

[
  { "id": 1, "conversationId": "abc123", "createdAt": "2024-01-15T10:30:00Z" },
  { "id": 2, "conversationId": "def456", "createdAt": "2024-01-15T11:15:00Z" }
]

---

GET /conversations/:id

Retrieve a single conversation by its SQLite row ID.

Auth: X-Admin-Token: {ADMIN_TOKEN}

URL parameter: id — the integer row ID from the database (not the conversationId string).

---

Feedback Endpoints

POST /feedback/:conversationId

Submit a star rating for a conversation.

Auth: None required.

Request body:

{
  "rating": 4
}

rating must be an integer from 1 to 5. Values outside this range are rejected.

---

GET /feedback

Retrieve all feedback entries, counts, and average rating.

Auth: X-Admin-Token: {ADMIN_TOKEN}

Response:

{
  "average": 4.2,
  "total": 38,
  "distribution": { "1": 2, "2": 3, "3": 5, "4": 14, "5": 14 },
  "entries": [...]
}

---

Error Responses

Status	Meaning
400	Bad request — missing or invalid body field (e.g. rating out of range)
401	Unauthorized — missing or incorrect X-Admin-Token
404	Not found — conversation ID does not exist
500	Server error — check DIRECT_LINE_SECRET is set correctly

---

sessionStorage Keys (Client)

These keys are managed entirely by the client and are not sent to the server as headers — they are used for local state persistence only.

Key	Contents
opotin_chat_messages	Serialised chat history array
opotin_conversation	Conversation metadata object
opotin_watermark	Last seen Direct Line watermark
opotin_admin_token	Admin token (admin app only)

---

→ Next: 🚀 Setup & Configuration · 🌍 Deployment