Skip to content

Feedbacks ​

ags.feedbacks is the one place this client records something that happened, and the exception proves the rule everywhere else. Conversations, messages, action logs, buttons, attachments and spans are written by the tracking SDK because they are things that happened and the SDK watched them happen. Feedback is not telemetry. Nothing about a run of your agent reveals whether the person on the other end was satisfied with it — somebody has to say so, and the moment they say it is a click in your application, not an event any SDK could observe.

So there is no tracking-plane path for feedback, no span kind, and no inference. You call this when your user clicks the thumb.

python
ags.feedbacks.create_for_conversation("wa-3859", "positive")     # write role
ags.feedbacks.create_for_agent("negative", "Slow at peak hours")  # write role
ags.feedbacks.create_for_message(4821, "negative", topic="style", reason="too_bold")

Three kinds, three methods ​

Conversation feedback is how one specific conversation went. Agent feedback is how the agent is doing overall, optionally scoped to one environment. Message feedback is a reaction to one message in a conversation — the per-recommendation thumb, with a structured "why". They are separate methods rather than one method with a flag because they genuinely take different arguments — environment is accepted on agent feedback and refused on the other two, topic/reason exist only on message feedback.

python
ags.feedbacks.create_for_conversation("wa-3859", "negative", "Never got my refund")
ags.feedbacks.create_for_agent("positive", environment="production")
ags.feedbacks.create_for_message(4821, "negative", topic="price")
ParameterTypeDefault
conversationstr or intrequired, on conversation feedback
messageintrequired, on message feedback
sentimentstrrequired
commentstr—
topic, reasonstr— , message feedback only
agentintyour key's own agent
environmentstr—

sentiment is positive, neutral or negative. Anything else is rejected before the request is made, with a message naming the three.

conversation takes either id and costs no extra round trip either way — this is the one method where the string is resolved server-side rather than by the client.

message is the integer pk from the transcript (conversations.get(...)["messages"][n]["id"]); messages have no string alias.

topic and reason are your application's own slugs (max 50 chars each). AgentSight stores and counts them and never interprets them — topic is the dimension ("style", "price"), reason the drill-in within it ("too_bold"). Group by topic on your side to build a per-dimension profile.

agent on create_for_agent() fills itself in from me(), so ags.feedbacks.create_for_agent("positive") is the whole call. A key can only ever write to one agent, which made naming it redundant. Pass it explicitly only if you already have the number in hand.

environment is a slug — ags.environments() lists the ones this agent has. It is accepted on agent feedback only; conversation and message feedback derive theirs from the conversation.

One vote per message — create_for_message is safe to retry

A message holds at most one vote. Repeating create_for_message for the same message updates the stored vote instead of filing a second row (the server answers 200 rather than 201), which makes it the one write on this API that is safe to retry. Fields you send are applied, fields you omit keep their stored value — a bare repeat of a thumb never wipes an earlier topic/reason. The transcript carries the vote back nested on its message, as messages[n]["feedback"].

Reading it back ​

python
for feedback in ags.feedbacks.list(sentiment="negative"):
    print(feedback["conversation_id"], feedback["comment"])

ags.feedbacks.get(42)

Newest first. page() gives you the envelope instead of the iterator, which is how you read a count without walking the rows:

python
ags.feedbacks.page().count

page() also takes a page number and the same filters as list() — ags.feedbacks.page(2, sentiment="negative").

FilterSelects on
sentimentpositive, neutral or negative
kindconversation, agent or message feedback
conversation (pk), conversation_id (string)one conversation's feedback — message votes included, since every vote knows its conversation
message (pk)one message's vote
topic, reasonyour own slugs, matched exactly
agent, userwho it is about, and who left it — agent only accepts your key's own agent id, so it never narrows
environment (or env)the environment it was left in
has_comment, comment_containsthe free text
created_at_after, created_at_beforewhen it was left
include_ticketsthe gate to the ticket surface — see below
has_ticket, ticket_statusthe promoted state — only alongside include_tickets=True
search, orderingacross the searchable fields, and the sort

To go the other way — conversations that have feedback, rather than the feedback itself — filter conversations on has_feedback or feedback_sentiment.

Tickets: include_tickets narrows as it includes ​

A ticket is typically a promoted piece of feedback, and include_tickets=True is how you read that promotion back:

python
for feedback in ags.feedbacks.list(include_tickets=True):
    ticket = feedback["ticket"]
    print(ticket["status"], ticket["title"], ticket["comments_count"])

Each returned row carries its ticket — id, title, status, priority, tags, timestamps, comments_count and the full discussion thread under comments, oldest message first — or you can narrow further with has_ticket and ticket_status (which accepts a list and ORs it: ticket_status=["open", "in_progress"]).

It also narrows the result set

include_tickets=True does two things at once: it puts the ticket on each row, and it drops every feedback that was never promoted — with no error. Do not add it "just to see tickets" on a listing you expect to stay complete; the page's count is the promoted count. Without it, payloads carry no ticket key, counts collapses to {"all": N}, and has_ticket / ticket_status answer 400 — same contract as conversations.

get() needs no parameter: one feedback by id carries its ticket unconditionally, at the same full depth, or null when it was never promoted.

Correcting and removing ​

python
ags.feedbacks.update(42, sentiment="neutral")             # write role
ags.feedbacks.update(42, comment="Resolved on the second attempt")
ags.feedbacks.update(42, topic="fit")                     # message feedback only
ags.feedbacks.delete(42)                                  # write role

sentiment, comment, topic and reason are the changeable fields — the slugs on message-kind feedback only, and None values are dropped before the request, so update() can replace a slug but never clear one. Unlike a conversation, a feedback row deletes for real — it is a statement somebody made, and withdrawing it means it is gone rather than hidden.

Next ​