AI Seller

A turn, step by step#

A turn starts when a customer writes, or when a person answers from the console. Runs are debounced per conversation (a burst of messages is one turn), one run per conversation at a time, and idempotent on the last processed message. Each step is recorded on the execution, so every reply can be explained afterwards.

1. Load the conversation, its state, the summary and the remembered facts. The prompt never grows with the conversation: summary, retrieved facts, the last few messages.
2. Retrieve knowledge — the relevant chunks of the business's text, FAQ entries, offers, files and URLs, with the source versions used.
3. Ask JEV, in one batched request, what is happening: intent, stage, whether the stage advanced, the next action, interest, objection, whether a person is needed, whether a calendar action is meant, whether knowledge is needed, and whether the customer asked to stop.
4. Apply the strategy: the stage's objective, its allowed and prohibited actions, and its recommended questions.
5. Compose the context: the identity, the communication and language profiles, and the offer catalog.
6. Ask the model for a structured answer — a message and a list of actions — never free text.
7. Validate, then apply the business policy, the platform policy and the autonomy gate, in that order.
8. Execute: send, draft, block or hand off, then update the state, the funnel stage, the lead and the memory, and emit the events.

Nothing the model writes changes anything directly. Every side effect — a send, a stage change, a calendar action, a lead update, a handoff — goes through a validated structured action. Chain-of-thought is never stored or shown.

JEV decides, the LLM writes#

The two engines have separate jobs. JEV judges: it picks a case, gives a score and says how likely something is. Code does every count, sum and date calculation. The LLM writes only the words a person reads — the reply, a per-conversation explanation, a board narrative.

The state JEV sees

One request per turn, with every question batched. The state is minimal and structured: the current message, a short summary, the current stage and the known needs — never the whole history.

• Keys are tried in order: the platform key (JEV_API_KEY, which an administrator can turn off), then a key the organization saved for itself.
• With no key, a confidence below the per-question threshold, or an error, the same schema is answered by the LLM instead.
• Every decision is stored with its source (JEV or LLM), probabilities, confidence and thresholds, and the console shows them. A reply can always be traced back to what was decided and why.
• Text sent to TypeSafe is masked, and sharing data with JEV is an opt-in per organization, on the JEV settings screen.

Autonomy#

One level per business decides how far the Seller may go on its own. It is enforced in the gate before a send, never in the prompt.

Autonomy is set per business. There are no per-account or per-conversation overrides yet.

Drafts and recommendations#

• At level 2 the Seller prepares a reply instead of sending it. A draft is a message ready to send; a recommendation is advice for the person who is answering. There is one pending draft per conversation.
• A person approves or discards it from the console; approving sends it through the same path (and the same pacing, flood waits and account health checks) as any other reply. A draft is superseded when the next turn produces a new one.
• A reply that failed validation is never kept as a draft. An invented price therefore cannot be approved with one click.

Handoffs#

The triggers are configurable per business: the customer asks for a person, a complaint, a sensitive topic, a pricing exception or negotiation, a high-value lead, policy uncertainty, calendar ambiguity, repeated validation failures, or your own keywords. A funnel stage can add its own rules while a conversation is in it.

A handoff records a row, sets the conversation's AI state to PAUSED_HANDOFF, notifies the organization and emits an event — and the Seller stops sending in that conversation. People answer from the console; Resume AI hands the conversation back, and whatever the customer wrote meanwhile is then the Seller's to answer.

What it never does#

Honesty

• It never claims to be a human. A configured identity name is a persona name. If a customer sincerely asks whether they are talking to a person or a bot, it answers truthfully that it is an AI assistant, whatever the configuration says.
• Proactive disclosure — a short line at the start of the first AI message of a conversation — is a per-business setting, on by default, with text in uz, ru and en.

Only authorized conversations

• It answers inside a conversation the customer started, within the business's reply window.
• A proactive or follow-up message follows the consent rules recipients already have (OPTED_IN, AUTHORIZED, EXISTING_RELATIONSHIP — never OPTED_OUT or suppressed), and is capped by the follow-up limit.
• Research results never trigger outreach.
• On Instagram and Facebook the platform's own window applies on top: see Channels.

Opt-out wins

• An explicit stop request — “stop”, “стоп”, “отпишите” and the classifier — marks the recipient opted out, adds a suppression and is audited. The AI then stops for good in that conversation, with at most one confirmation message if the business allows it.
• Account health applies too: replies go through the same pacing and restriction handling as campaigns, and a restricted account stops everything. Nothing is re-routed to another account.

Validation

A reply must pass, in order: the schema; the length from the profile; the prohibited phrases; honesty; grounding; language; repetition against the recent AI messages; at most two questions; and no requests for card numbers, passwords or codes.

• Grounding is the important one: prices and other numbers, times, links, phone numbers, e-mail addresses and delivery or stock claims must come from the business, its offers, its knowledge, a colleague's message or the date. Repeating the customer's own words never makes a claim true.
• A failure leads to one regeneration with the failures as instructions, then BLOCK. With repeated failures on, it also hands the conversation over. When only the honesty checks fail on the “are you a bot?” question, Oqim sends a fixed truthful answer in the customer's language.

Where it is configured#

Prompt versions move through DRAFT, TESTING, ACTIVE and ARCHIVED, with one active version per agent and business. Changing a prompt or a model never touches the business's data — config, memory, knowledge, feedback and history stay where they are.

Watching it work#

• The live inbox shows every chat with the AI state, the current stage and the decision behind each message. See Live inbox.
• Every execution is inspectable: its steps, its tool calls, the JEV decision, the knowledge and memory it used, its tokens and its cost.
• The console updates live over GET /api/v1/events/stream. The events the Seller emits are listed under Webhooks: ai.turn.completed, ai.reply.sent, ai.reply.drafted, ai.reply.blocked, ai.draft.updated, ai.stage.changed, ai.lead.updated, the ai.conversation.* events and ai.handoff.*.

Endpoints#

All under /api/v1. Reads take ai:read and writes ai:manage unless the table says otherwise; see the API reference for bodies and responses.