Skip to main content

​
Conversation operators

A conversation operator is a named classifier the inbox runs against every text thread. You define it once — a name, an instruction, and the type of value it returns — and the inbox classifier extracts that signal from each conversation on the channels you scope it to. Signals land on the conversation as typed metadata, so you can filter threads in the dashboard, read per-thread results, and roll them up into reports. Open Settings → Conversations → Conversation Intelligence in the dashboard to manage operators. This page covers the operator model, where signals land, and the API surface that backs the console. Base path: /api/v1/inbox

​
The operator model

An operator has four parts:
  • Name — how the signal reads in the dashboard and reports ("Billing intent").
  • Instruction — the natural-language rule the classifier applies to the thread ("Set to true when the customer asks about an invoice, a refund, or a payment method").
  • Output type — the shape of the signal: text, boolean, number, enum, or list. An enum operator also declares the allowed choices it picks from.
  • Channels — which text channels the operator runs on (SMS, WhatsApp, email, RCS, Viber, Instagram, Messenger, LINE, Telegram, Apple Messages, web chat). Voice conversations are classified by the voice speech-category pipeline instead, so the same taxonomy never applies two classifiers to one thread.
When an inbound message lands on a text conversation, the classifier reads the recent thread transcript and runs every active operator scoped to that channel. Each run emits a result: the typed value, a confidence score, and a short rationale. Results are merged into the conversation, so operators that did not run on a given pass keep their previous values. Until you define an operator, the pipeline makes no classifier calls at all — conversation intelligence is fully opt-in per tenant, capped at 25 active operators.

​
Where signals land

Every operator result is stored on the conversation itself:
  • Thread metadata — the conversation carries a result per operator: the value, confidence, rationale, which operator version produced it, and when it was classified.
  • Per-thread timeline — the conversation detail view and the GET /conversations/:id/intelligence/operators endpoint return the result set tagged on that thread.
  • Reports — because results are typed (boolean / number / enum rather than free text), they aggregate cleanly: share of threads flagged for escalation risk, average sentiment score by channel, billing-intent volume week over week.
Results record the operator version that produced them. When you change an operator’s instruction, output type, or choices, its version increments and results are recomputed under the new definition on the next pass — so a report across an edited operator always tells old-version values from new-version values.

​
The operator catalog

The catalog under Settings → Conversations → Conversation Intelligence is tenant-owned. Operators are your tenant’s private taxonomy — nothing you define is shared across workspaces, and operators are scoped to your organization only.
  • Create — name the signal, write the instruction, pick the output type, and scope the channels. Owners and admins can create; the console is role-gated the same way the API is.
  • Edit — send the full definition. Changing the instruction, output type, or enum choices bumps the operator’s version; changing only the channel scope does not.
  • Deactivate — a soft delete. The operator stops running against new messages and frees a slot against the 25-operator cap, but its definition and previously computed results stay readable.
  • System operators vs custom operators — the built-in fixed-function analytics (dispositions, QM scoring) are separate surfaces. Everything on this catalog is a custom operator your team defined; create, edit, and deactivate are all available to owners and admins.
Writes (create, edit, deactivate) require an owner or admin role. Reads — listing the catalog and reading per-thread results — are available to any authenticated teammate.

​
Example operators

The console and API support any signal you can phrase as an instruction. Three that work well as starting points: Detect billing intent
Flag escalation risk
Extract an order id
Keep instructions concrete: name the exact phrases or patterns to catch, and for enums declare a small, closed choice list. A vague instruction produces low-confidence values that pollute your reports.

​
Reporting

Operators roll up into the intelligence surface three ways:
  1. Thread-level filtering — results live on thread metadata, so conversation lists and the per-thread intelligence read can filter on operator outcomes (for example, every thread where Escalation risk = high).
  2. Aggregate views — boolean, number, and enum outcomes aggregate across a window: escalation-risk distribution by channel, billing-intent share of inbound volume, sentiment trends.
  3. Cross-channel taxonomy — the operator model mirrors the voice speech-category taxonomy, so a reporting layer can treat voice categories and text operators as one taxonomy across channels.
Operators on text threads complement the built-in analysis (sentiment, topics, quality score) described in Conversation Intelligence — built-ins are automatic; operators are the signals you define yourself. Because each result stores its operator version, a report window never silently mixes values computed under different definitions of the same operator.

​
API parity

Everything the console does goes through the inbox API, so the catalog is fully scriptable.

​
List operators

Returns { items: [...] } with each operator’s id, name, version, instruction, outputType, choices, channels, isActive, and timestamps. Active operators only by default; pass includeInactive=true to include deactivated ones.

​
Create an operator

Owner/admin only. An enum operator must declare a non-empty choices array — the request 422s otherwise. A tenant at the 25-active-operator cap gets 409 LIMIT_EXCEEDED.

​
Update an operator

Send the full definition. Instruction, output-type, or choices changes bump version; a channels-only edit does not. Unknown operator ids return 404 OPERATOR_NOT_FOUND.

​
Deactivate an operator

Soft delete: the operator stops running on new messages and frees a cap slot; its definition and results remain. Returns { id, deactivated: true }.

​
Read per-thread results

Returns each operator result tagged on that conversation: operatorId, operatorVersion, name, outputType, value, confidence, rationale, channel, and classifiedAt. Any authenticated teammate can read it; a conversation with no results returns an empty list with a 200.

​
Rules of scope

  • Operators run on message text only — voice and video conversations are classified by the voice speech-category surface instead.
  • All controls on this page are tenant-owned: you define the catalog, you scope its channels, you retire operators. Nothing in the pipeline messages your customers — it is reporting plumbing only.
  • PII redaction runs before any thread content reaches the classifier, so operator definitions never send raw message bodies out of your tenant.