#AI Seller Chat: Overview
Status: Available / Planned. The one-line widget and the client Chat API are Available. The server conversations API: reading is Available, writing is Planned. The widget JS API and widget v2 parameters are Planned. The status of each approach is given in the tables below.
Purpose: to explain what the AI seller chat can do, the three ways to embed it in your site, app, or messenger, and how to choose between them.
#Contents
- What the chat does
- Three ways to embed
- How to choose
- Data flow diagrams
- Cell addresses
- Money and limits
- Personal data and consent
- Where to read next
- Open questions
#What the chat does
The AI seller is a conversation partner on your site (or in your channel) that leads a visitor from a question to a lead.
| Capability | How it works | Status |
|---|---|---|
| Answers from the tenant's knowledge base | The answer is built from the materials you uploaded to your tenant's knowledge base and from the agent settings | Available |
| Knows which page the visitor is on | The widget passes the page address, title, and type; the model receives them in the prompt as browser data, not as instructions (Page, source, and UTM) | Available |
| Hands the conversation to an operator | An operator in the dashboard takes the conversation; while they handle it, the AI does not reply. The daily limit on AI replies also hands the conversation to an operator. In your own channel, the handoff request arrives as the conversation.handoff_requested event | Available (in your own channel, Planned) |
| Creates a lead with attribution | When the conversation gathers enough information, the platform creates a contact and a lead; the lead keeps the visit source | Available |
| Accepts files | Images and documents up to 10 MB | Available (with a limitation: client Chat API) |
| Works in your own channel (messenger, app, CRM) | Server API: you pass the customer's messages, the AI reply arrives asynchronously (202 and the conversation.ai_reply operation, or the message.created webhook), and operator messages arrive by webhook | Planned |
What the chat does not do: it does not show other visitors' conversations to anyone, does not follow instructions hidden in a page title or address, and does not promise a reply once the daily AI limit is exhausted (in that case the conversation goes to an operator).
#Three ways to embed
| Way 1. Widget | Way 2. Your own interface | Way 3. Your own channel | |
|---|---|---|---|
| In short | One <script> line on the page: the button and chat window are ready | You draw the chat yourself and call the client Chat API from the browser or app | Your server calls the server API: the customer talks in your messenger, and the AI and operator reply through the platform |
| Status | Available | Available (with a CORS limitation, see below) | Planned |
| What you need | A web_chat channel ID and your site's domain on the tenant's list | A web_chat channel ID | An API key (permissions conversations:*, ai_seller:invoke) and an api channel created in the dashboard together with the integration; GET /me returns the channel ID |
| Keys and secrets | Not needed. channel_id is public | Not needed. channel_id is public; the server issues the session token | A secret key on your server only |
| Who draws the interface | The platform | You | You (the messenger) |
| Billing | From the tenant's wallet, per AI reply | Same | Same, with reservation, spending caps, and the api channel's daily limit, as for the widget |
| Page | Embedding the widget | Client Chat API | Server conversations API, guide |
In addition to way 1, a widget JS API is planned (Sapport.open(), Sapport.on(), identify, and others): see the widget JS API, status Planned.
Important for way 2. The client Chat API routes (
messages,history,poll,events,upload) do not return CORS headers. From a browser they are reachable from pages opened on the cell's own domain, while from a third-party domain the browser will block reading the response. Working options are in the "Known limitations" section of the client API page.
#How to choose
| Your situation | Choice |
|---|---|
| You need a chat on your site, the design is not critical, and color, greeting, and position are enough | Way 1 (widget) |
| Your site runs on Bitrix or WordPress | The connector module installs the loader, and the loader attaches the widget (Loader) |
| You need your own chat design in an app or on a cell page | Way 2 (client Chat API) |
| You need the chat in your messenger, in another system's widget, or as an end-to-end channel with your own CRM | Way 3 (server API; still a design) |
| You need to open the chat from your own "Ask a question" button | Today: your own script cannot open the widget window (there is no JS API); see the interim options. After the JS API ships: Sapport.open() |
#Data flow diagrams
#Way 1. Widget
Host site page Sapport cell
┌──────────────────────────┐
│ <script src=…/widget.js │ POST /api/widget/init (CORS *)
│ data-channel=…> │ ───────────────────────────────► name, color, greeting,
│ │ ◄─────────────────────────────── pre-chat form, consent
│ [60 px button] │
│ │ click │
│ ▼ │ iframe: /widget/<channel_id>?page=…&title=…&ft=…
│ ┌─────────────────┐ │ ───────────────────────────────► chat page (our domain)
│ │ iframe 380×560 │ │
│ │ (our domain) │ ─── POST /api/widget/messages ───────► AI seller
│ │ │ ◄── reply, session_token ──────────── │ ├─ knowledge base
│ │ │ ◄── SSE /events (or /poll) ────────── │ ├─ contact, lead, attribution
│ └─────────────────┘ │ │ └─ operator in the dashboard
│ ▲ postMessage │
│ └ sapport:new-message │
│ sapport:close │
└──────────────────────────┘#Way 2. Your own interface
Your interface (a page on the cell domain or your proxy) Sapport cell
┌──────────────────────┐ POST /api/widget/init ┌─────────────────┐
│ input, message list, │ ──────────────────────────────────►│ web_chat channel│
│ typing indicator │ POST /api/widget/messages │ AI seller │
│ │ ──────────────────────────────────►│ operator │
│ stores session_token │ ◄── response + session_token │ │
│ │ GET /history /poll /events │ │
│ │ ◄──────────────────────────────────│ │
└──────────────────────┘ └─────────────────┘#Way 3. Your own channel (Planned)
Customer ──► your messenger ──► your server Sapport cell
│ POST /conversations ┌────────────────────┐
│ POST …/messages │ "api" channel │
│ (Idempotency-Key, Bearer) │ AI seller │
│ ─────────────────────────────►│ operator │
│ ◄── 202 + operation ──────────│ tenant wallet │
│ (GET /operations/{id}) │ │
│ ◄── message.created webhook ──│ outbox → delivery │
│ (AI reply, operator reply)└────────────────────┘
Customer ◄── your messenger ◄────┘#Cell addresses
There are three independent cells. Channels, keys, and data belong to one cell; use the address of the cell where your tenant is registered (Cells and data).
| Cell | Base URL |
|---|---|
| RU | https://formula-cream.pro |
| EN | https://wfacademy.org |
| ID | https://wfacademy.id |
Widget script: https://<cell domain>/widget.js. Client Chat API: https://<cell domain>/api/widget/…. Server API: https://<cell domain>/api/public/v1.
#Money and limits
- Every AI reply is a paid operation charged to the tenant's wallet. The route is open to any visitor, so it has its own limits.
- Message length is at most 4000 characters (
413 message_too_long). - Message rate: 20 per minute per visitor (channel + IP) and 240 per minute per channel. The counters are kept in server process memory.
- The daily limit on AI replies per tenant channel is 200 by default (the channel setting
ai_daily_limit, maximum 10,000). Once the limit is reached, the message is saved and the conversation goes to an operator; the client Chat API response containsqueued: true. In the server conversations API, the same limit applies to theapichannel: the message is saved, the conversation gets the statehandoff_pending, andai_replycarries{"status": "skipped", "reason": "daily_limit"}. - File upload: 10 MB, 5 per minute per IP, 30 per minute per channel.
- Server API: no more than 5 concurrent paid operations per integration, and the cost of one operation is capped at about 100 RUB (Conventions).
Detailed tables are on the client Chat API page.
#Personal data and consent
- If the tenant has set a consent-to-terms text, the visitor cannot send a message until they agree. The consent version depends on the text and the link: editing the text requires new consent.
- First-touch data (UTM, click IDs, referrer) is stored in the browser on the host site and reaches the platform only with the visitor's consent (when installed through the loader).
- More: Page, source, and UTM.
#Where to read next
| Task | Page |
|---|---|
| Install the widget, configure its look, copy a ready-made block | Embedding the widget |
| Control the widget from page code (open it, send a message, subscribe to events) | Widget JS API (Planned) |
| Understand where a lead came from and which page the customer was on | Page, source, and UTM |
| Build your own chat interface | Client Chat API |
| Manage conversations from a server | Server conversations API (reading: Available, writing: Planned) |
| Connect your own messenger | AI seller in your own channel (Planned) |
| Handle errors, retries, and limits | Conventions |
| Receive events instead of polling | Webhooks |
Ready-to-copy files are in the examples/ directory.
#Open questions
- When the server conversations API will be published, and in what order the widget JS API and v2 parameters will ship: the timing is not fixed in the design. For the owner.
- CORS headers for the client Chat API (
messages,history,poll,events,upload) are not described in the design; there are none today. Technical. - Where exactly
GET /mereturns theapichannel'schannel_id, and how the dashboard shows it when creating an integration: the response shape is preliminary. Technical.