Feedback

Overview

Use the feedback API to rate persisted assistant responses. Feedback is recorded per assistant turn and can include a star rating, category, and optional free-text comment.

note

Capture conversationSk and assistant turnNumber from the chat done event before calling this endpoint.

Authentication

Widget feedback submission uses the same-origin widget proxy and the widget token boundary. Direct runtime feedback stats should be called through APIM only when the environment publishes that route.

Direct APIM callers require:

• Authorization: Bearer {access_token}
• Ocp-Apim-Subscription-Key: {subscription_key}

See Authentication for the full header contract.

Submit Feedback

Attribute	Value
Endpoint	POST /api/ingestion/sdac/feedback
Method	POST
Content-Type	application/json
Response	JSON

Request

{
  "agentId": "sdac-coordinator-release",
  "conversationSk": 12345,
  "reportId": "b377a9be-9d4a-434a-9688-ba828b39c9f7",
  "userId": "jsmith@contoso.com",
  "sessionId": "sess-abc-123",
  "turnNumber": 2,
  "rating": 4,
  "category": "clarity",
  "comment": "Could use less jargon"
}

Field	Type	Required	Description
agentId	string	Yes	Agent that produced the response
conversationSk	number	Yes	Persisted assistant turn key from the chat done event
reportId	UUID string	Yes	Cost report identifier
userId	string	Yes	Authenticated user ID
sessionId	string	Yes	Browser or client session ID
turnNumber	number	Yes	Assistant turn number from the chat done event
rating	number	Yes	1 to 5 star rating
category	string	No	One of accuracy, clarity, relevance, helpfulness, tone, other
comment	string	No	Optional note, maximum 2000 characters

Response (200)

{
  "feedbackSk": 42,
  "success": true
}

Side Effects

• Feedback is upserted per persisted assistant turn. Re-rating the same turn updates the existing row.
• rating is the only opinion field required. category and comment are optional.
• Aggregate feedback stats for the same agentId change immediately after a successful submission.

Submit Example

curl -X POST "$WIDGET_BASE_URL/api/ingestion/sdac/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "sdac-coordinator-release",
    "conversationSk": 12345,
    "reportId": "b377a9be-9d4a-434a-9688-ba828b39c9f7",
    "userId": "jsmith@contoso.com",
    "sessionId": "sess-abc-123",
    "turnNumber": 2,
    "rating": 4,
    "category": "clarity",
    "comment": "Could use less jargon"
  }'

---

Feedback Stats

Attribute	Value
Endpoint	GET /sdac/feedback/stats/{agentId}
Method	GET
Response	JSON

Path Parameters

Parameter	Type	Required	Description
agentId	string	Yes	Agent identifier whose aggregated feedback metrics should be returned

Response (200)

{
  "agentId": "sdac-coordinator-release",
  "totalCount": 10,
  "avgRating": 2.8,
  "ratingDistribution": {
    "1": 2,
    "2": 3,
    "3": 2,
    "4": 1,
    "5": 2
  },
  "categoryBreakdown": {
    "accuracy": 3,
    "clarity": 2,
    "relevance": 1,
    "helpfulness": 2,
    "tone": 1
  }
}

Field	Type	Description
agentId	string	Agent identifier that was queried
totalCount	number	Total feedback submissions in the query window
avgRating	number	Average star rating
ratingDistribution	object	Count of each star rating
categoryBreakdown	object	Count of feedback by category

Example

curl -X GET "$BASE_URL/sdac/feedback/stats/sdac-coordinator-release" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY"

---

Rating Categories

Value	When to Use
accuracy	The answer was incorrect or missed material facts
clarity	The answer was hard to understand
relevance	The answer drifted away from the request
helpfulness	The answer identified issues without clear next actions
tone	The communication style was not appropriate for the audience
other	Catch-all for anything else

Error Responses

Status	Description
400	Invalid request body or unsupported rating value
401	Missing or expired bearer token
403	Invalid subscription key or insufficient scope
500	Failed to store or aggregate feedback

Operational Notes

• Keep conversationSk and assistant turnNumber with each assistant response in your client state.
• Feedback rows expire after 90 days and are excluded from aggregate stats after expiration.
• Stats are aggregated by agentId, so pass the same agent ID used for the corresponding chat turn.