Skip to main content

​
Manual conversation-intelligence re-run for inbox threads

Orbit scores conversations in the background as customer messages accumulate. The automatic loop over agent conversations is described in Conversation intelligence; inbox threads are scored by the same classifier, and this guide covers the on-demand path: POST /conversations/:id/analyze-intelligence, which re-scores one inbox thread at the moment you call it.

​
What the endpoint does

POST /conversations/:id/analyze-intelligence runs the conversation-intelligence classifier over the thread’s message history and writes the fresh scores back onto that conversation’s record: a sentiment score and label, the primary intent with confidence and entities, the topic list, and the detected language. The response echoes exactly what was persisted, plus an intelligence_analyzed_at timestamp. The call is repeatable. Each run overwrites the intelligence fields with newly computed values and refreshes the timestamp; everything else stored on the conversation (custom fields, tags, escalation state) is preserved.

​
When to use it

  • Messages arrived after the automatic pass. A channel delivered part of the history late, or ingestion stalled, and the stored scores describe only part of the thread. Re-run once the thread is complete.
  • An update hook did not fire. Your integration drives re-analysis from a thread.update event and one thread was missed. Force the pass yourself instead of waiting for the next automatic scan.
  • You edited the thread. You adjusted tags or custom fields during a QA review and want a fresh analysis pass recorded against the thread in its current state.

​
Who can call it

The endpoint writes to the conversation record, so it carries the same gate as the other conversation write routes: an owner, admin, or developer role, and the conversations:write scope for API-key callers. Viewer and agent seats receive a 403, as do keys without the scope. Like the other conversation writes, it is rate-limited per authenticated caller.

​
Request and response

No request body is required; the conversation id travels in the path.
A successful run returns the standard envelope with the persisted fields under data:
The fields you will read most often: sentiment_label (positive / neutral / negative) with the numeric sentiment score behind it, primary_intent with intent_confidence, topics with primary_topic, and language. sentiment_trajectory is the per-customer-turn breakdown the overall score is averaged from.

​
What persists on the conversation

The same fields returned in the response are merged into the conversation’s metadata, alongside intelligence_analyzed_at. The merge touches only the intelligence keys, so other metadata you have written (custom fields, escalation state, translation pins) survives a re-run. Because the results live on the conversation record in your tenant schema, every read surface that shows conversation metadata (the Inbox, GET /conversations/:id, your warehouse sync) sees the re-run’s values, and the scores inherit the same tenant data-residency posture as the rest of your message traffic.

​
The same classifier as agent conversations

The endpoint invokes the exact classifier the agent-conversation endpoint (POST /agents/conversations/:conversationId/analyze-intelligence) uses; inbox messages are normalised into the same role/content transcript (inbound messages count as the customer turns) before scoring. The output shape is therefore identical to the scores recorded on automatically analyzed agent threads, and the dashboard aggregates read both without distinction. Long threads are bounded the same way on both paths: the pass reads at most the 500 most recent messages, and the sentiment trajectory covers the last 12 customer turns.

​
Errors

A re-run replaces the stored intelligence fields with the new pass’s values. If you need the previous scores for an audit trail, export them before calling the endpoint.