#Introduction

Status: Available / Planned. This page describes the platform as a whole. The status of each module is shown in the tables below. The server API authenticated by a secret key is Planned; the widget, the loader, the JS tracker, the CMS modules, and the connector are Available.

This page explains what the Sapport platform is from an integrator's point of view: which modules exist, which kinds of API there are, how everything fits together, and where to start reading.

#Who this documentation is for

• A developer on the tenant's side connects the AI seller chat to their site or messenger, pulls analytics into BI, publishes articles to their own site, and receives leads in their CRM.
• A developer of an external system (CRM, BI, CMS, mobile app) works with the platform through the server API.
• A site owner's technical specialist installs the loader or the Bitrix/WordPress module and connects the chat widget.

The documentation does not describe the platform's internals or the staff dashboard. It describes what you can call, embed, and retrieve.

#Core concepts

For the full vocabulary, see the Glossary.

#Platform modules

This document records the current state and the intent, not a calendar.

#Two kinds of API

The platform offers two fundamentally different ways to interact with it. Do not confuse them: they have different trust levels.

#Server API (secret key)

• Called only from your server, server to server. CORS is intentionally not enabled.
• Authorization is a secret key in the Authorization: Bearer … header. GET /me verifies the key and your permissions.
• The tenant is determined by the key only; you cannot pass another tenant's identifier.
• Each cell has its own base address: https://<cell domain>/api/public/v1.
• Covers: conversations and the AI seller, leads and CRM, analytics and dashboards, articles, the strategist, webhooks.
• Status: Available (reading, wallet, webhooks v2); writing, events, conversions, generation, and the sandbox are Planned.

#Client interfaces (from the browser and from pages)

Security rule. The server API secret key never ends up in a browser, a mobile app, a repository, or logs. Anything that runs in the browser uses only the client interfaces.

#How everything fits together

                         Your side                                      Sapport platform (cell: RU / EN / ID)
 ┌────────────────────────────────────────────┐                     ┌─────────────────────────────────────────────────┐
 │  Visitor                                   │                     │                                                 │
 │   │                                        │                     │   ┌──────────────┐    ┌───────────────────┐     │
 │   ▼                                        │  widget / Chat API  │   │ Chats        │◄──►│ AI seller         │     │
 │  Your site ── <script widget.js> ──────────┼────────────────────►│   │ (conversa-   │    │ (paid, wallet)    │     │
 │   │        └ <script loader.js> ───────────┼──── events, UTM ───►│   │  tions)      │    │                   │     │
 │   │                                        │                     │   └──────┬───────┘    └─────────┬─────────┘     │
 │   ▼                                        │  signed beacon      │          │ leads                │               │
 │  CMS module (Bitrix / WP / …) ─────────────┼────────────────────►│          ▼                      ▼               │
 │   ▲   article publishing ◄─────────────────┼─────── jobs ────────│   ┌──────────────┐    ┌───────────────────┐     │
 │   │                                        │                     │   │ CRM & agents │    │ Analytics         │     │
 │                                            │                     │   └──────┬───────┘    └─────────┬─────────┘     │
 │  Your servers                              │   Bearer key, TLS   │          │                      │               │
 │  (CRM, BI, own channel, messenger) ◄──────►┼◄───────────────────►│   ┌──────▼──────────────────────▼─────────┐     │
 │   ▲                                        │                     │   │ Server API  /api/public/v1            │     │
 │   │ webhooks (signature, retries)          │                     │   │ scopes · idempotency · limits         │     │
 │   └────────────────────────────────────────┼◄────────────────────│   └──────┬──────────────────────┬─────────┘     │
 └────────────────────────────────────────────┘     events           │          ▼                      ▼               │
                                                                     │   ┌──────────────┐    ┌───────────────────┐     │
                                                                     │   │ Strategist   │    │ Dashboards        │     │
                                                                     │   │ (reports)    │    │ ("Overview",      │     │
                                                                     │   │              │    │  "Pulse")         │     │
                                                                     │   └──────────────┘    └───────────────────┘     │
                                                                     └─────────────────────────────────────────────────┘

How to read the diagram:

1. A visitor lands on your site. The loader and the CMS module pass the referral source, UTM, behavior, and (at your option) a signed server beacon to the platform.
2. The widget opens a conversation. The AI seller replies, creates a lead when needed, and calls an operator.
3. Leads, conversations, and analytics flow into the CRM, analytics, and strategist modules.
4. Your servers retrieve and manage data through the server API and learn about changes from webhooks.
5. Articles prepared by the platform go to your site through the connector (signed jobs), or you pick them up yourself on the article.ready event.

#Principles behind the API

• The tenant comes only from the key. The identifier of another tenant's resource yields 404 not_found, not 403: the platform does not confirm that someone else's data exists.
• A key lives in one cell. Cell data is never mixed; a key from another cell is rejected with wrong_cell.
• Least privilege. A key receives only the scopes it needs; the effective permissions are the intersection of the scopes, the integration's role, the owner's current permissions, and the plan.
• Money is visible. Paid operations are separate scopes; the cost is returned in the response (usage), and spending is capped by limits. See Conventions.
• Slow work is asynchronous. Operations that take longer than a few seconds (an AI reply, lead scoring, article generation, a strategist turn) return 202 and an operation envelope; you get the result with a GET /operations/{id} request or the operation.completed event (Conventions).
• The contract comes first. The OpenAPI 3.1 specification is built from the same schemas that validate requests and responses at runtime.
• Platform-internal stays closed. The platform's own internal tables and services (its own blog, courses, public pages) are not exposed in the public API.

#Where to start

For the full table of contents, see the README.

#Notes

• Server API examples in this documentation are illustrative until the OpenAPI specification is published: names of optional fields may be refined. The mandatory conventions (authentication, error format, pagination, webhook signing) are fixed on pages 03–06.
• The documentation is maintained in Russian and English.