Endpoint Reference

Full reference for every REST endpoint under /api/v1, plus the separate third-party-migration compatibility routes. This page mirrors the ACTUAL committed route/controller code, not just the original design proposal -- see the notes under each table for anywhere behavior is still evolving.

Conventions

• Base URL: https://<host>/api/v1. See Quickstart for a first request, Authentication & Scopes for tokens and scopes.
• Universal codes: every endpoint below can additionally return 401 (missing/invalid/expired token), 403 (token lacks the required scope), or 429 (rate limited) from the shared authentication/rate-limit layer -- these are omitted from the per-endpoint "Codes" columns below rather than repeated in every row; only the codes the endpoint's own logic produces are listed there.
• Idempotency: writes marked x-idempotency: required in OpenAPI require X-Smartbtn-Idempotency-Key. Missing: 400; reuse within 24 hours: 409. Not every DELETE is exempt. The exact exemptions are listed below; all other writes require the header.
• Pagination: list endpoints accept ?cursor=&limit= (limit capped at 100, default 20) and return {"data": [...], "next_cursor": "..." | null}.
• Errors: native /v1 error responses use RFC-7807 application/problem+json ({type, title, status, detail, instance, errors?}); compatibility routes state their wire-format exceptions explicitly.
• Ids: chats, files, webhook subscriptions, and compat Bot-API chat ids are internal numeric ids; contacts use a 32-character opaque guid instead (never the internal numeric id) -- both are tenant-scoped, so an id belonging to a different account always 404s rather than leaking existence.

Diagnose without workarounds. smartbtn.ru and smartbtn.me serve the same API and project data. Select one verified base URL; never automatically forward Bearer on redirects. Send a UUID in X-Smartbtn-Idempotency-Key on every POST/PATCH/PUT/DELETE as a safe convention; server requirements and exemptions are listed below. On 405 for a documented method, including KB-rule PATCH, stop and report method, path and status without secrets. Do not try another write method or host. For support, consider temperature:0.3–0.5 only on a model supporting the parameter; identical answers are not guaranteed. For a new launch keep autonomous_tuning_enabled:false until learning_target, binding and version are verified; do not silently disable an existing approved workflow.

Chats & Messages

transfer, rate-request, sending a message, and typing hand off to the internal chat/WS layer rather than writing synchronously, which is why they answer 202 (accepted) instead of the resource-style 200/201 a plain CRUD call might imply. close, state and seen are plain synchronous database writes and answer 200 once the update has actually happened. close is exactly state with {"state": "expired"} — one shared implementation, also used by the operator console, so the API and the web UI always agree. Closing a chat that is already closed is a 200 that does not re-deliver the chat.closed webhook. Chat state is also reconciled in the background, which limits how durable a written state is: a scheduled job re-derives every non-spam chat's state from the age of its last message every 5 minutes — 7 minutes or more idle becomes expired, anything younger becomes active. So ready is transient: it is accepted and written, but the next tick replaces it, and it is not a state you can read back reliably. active and expired hold only while they agree with that 7-minute clock — closing a conversation you have just been talking in reads back as active again within 5 minutes. And that job fires chat.closed on every move into expired, so both re-activating an idle chat and closing a still-fresh one deliver chat.closed a second time — the no-re-delivery guarantee above covers this API and the operator console, not the job, so treat chat.closed as at-least-once and deduplicate on your side. spam chats, and chats with no messages at all, are the only rows the job leaves alone. Note finally that the same value has two names: you POST {"state": ...}, but read it back as data.status and filter the list with ?status= — both refer to one field.

Messages with buttons (type: keyboard). Send text with up to 7 link buttons under it — a payment link, a file or config download, a docs page: {"type": "keyboard", "body": "Your order is ready.", "keyboard": {"buttons": [{"label": "Pay $5.99", "url": "https://pay.example.com/i/123", "style": "primary"}]}}. body is required; each button needs a label of 1–64 characters and an absolute https:// url (http:, javascript:, data:, relative URLs and URLs with user:password@ are refused); style is optional, primary (default) or secondary. An invalid button rejects the whole request with 422 and an errors entry such as keyboard.buttons.1.url — it is never silently dropped. A button only opens its link; it sends nothing into the chat. Every channel shows the message: the web widget and the operator console draw real buttons under the text, Telegram gets an inline keyboard (one URL button per row), and every other messenger, e-mail and export gets the text followed by one label: url line per button. GET /v1/chats/{id}/messages returns such an agent message as type: keyboard with keyboard.buttons.

Retrieving full history for a period. GET /v1/chats and GET /v1/chats/{id}/messages both accept from/to, filtering by the chat's or message's creation date — either, both, or neither may be sent, and they parse exactly like GET /v1/stats's own from/to: any Carbon-parseable value, interpreted in the application timezone, with an explicit UTC offset honoured rather than dropped. A bare date resolves to midnight of that date, so send a time (or the next day as to) to include a whole day. Sending neither is unchanged from before this parameter existed: an unbounded list, newest first. To pull every chat in a given period, page ?from=&to=&cursor= the same way you would page any other list — the range narrows the query before the cursor does, so a period from a year ago is one indexed range scan, not a walk through every chat created since. There is no equivalent filter on updated_at: a chat that reopens later still belongs to the period it was created in.

Every chat carries who answered it. accepted_by is the operator who answered first and handled_by the one handling it now; each is {agent_id, type, at} or null, where type is human or ai. handling sums the two up: missed (nobody answered), human, ai, ai_to_human (the AI operator answered, then a person took the chat -- an escalation, an explicit accept, or the person simply replying) and human_to_ai (a person accepted and then went silent long enough for the AI takeover to answer). The AI operator accepts a chat with its first message the visitor actually sees; a shadow-mode reply is never shown and never accepts anything. This is why these fields exist beside agent_id: that one is the chat's owner as used for routing, which the AI operator never becomes, so a chat the AI answered has a null agent_id and a filled accepted_by. at is null for chats accepted before attribution was recorded; the operator is still known.

GET /v1/chats/{id}/transcript returns a file, not JSON: a streamed text/plain; charset=UTF-8 attachment rendered by the same code that produces the operator console's own download, so the two can never disagree about what is public. Private operator notes, operator-only email and operator-to-operator messages are excluded by an allowlist; attachments appear as a canonicalized filename only, never a URL or path. It is bounded three ways — at most 50 000 messages, 10 MiB of output, and 64 Ki characters per message body — and the byte budget is applied whole lines at a time, so the body never ends mid-character; when it is reached the export stops after a marker line reading [Экспорт ограничен безопасным размером]. The response is streamed and therefore carries no Content-Length: read to EOF rather than trusting a declared length. It uses its own transcripts:read scope rather than messages:read, because handing over one artifact containing an entire conversation is a different decision from granting paginated message reads — a token may hold either without the other. A chat belonging to another account is a 404 like everywhere else in this API; a 403 means the chat is yours but is an internal department chat (reason: internal_room — those are operator-to-operator rooms, not customer conversations, and are refused to every caller including the web UI's platform admins), or the token lacks the scope (reason: missing_scope). There is no JSON representation on purpose: GET /v1/chats/{id}/messages is the structured, paginated view of the same conversation, and unlike this endpoint it does resolve a real attachment url for a file/image message (the transcript deliberately shows a filename only, never a URL or path -- that is a privacy decision specific to the bulk export, not a limit of the attachment data itself).

Contacts & Tags

Agents

Agents cannot be created through this API. A human operator only ever comes into existence by accepting an emailed invitation, and AI operators belong to the AI configuration surface -- DELETE /v1/agents/{id} refuses an AI operator, and refuses the widget owner's own agent row. DELETE is a soft delete: the agent's status becomes banned and the paid seat is released, but nothing is destroyed, so chats, ratings and the event log stay readable and POST /v1/agents/{id}/restore brings the agent back. PATCH is merge-safe and writes show_in_header only; the button-level operators_display_mode lives on PATCH /v1/widget/settings, and ai_assistant_id and the seat role are not writable over the API. Email address, password and account deletion have no API equivalent by design -- those stay in the web cabinet.

Read this before granting agents:write. POST /v1/agents/invitations sends mail on our sending reputation to an address you supply, and when the recipient follows the link it creates a new human principal with operator-console access to every chat on this widget -- every visitor's message body, name, email, phone and geolocation. That access is a database row, not a token grant: it outlives revocation of the API token that created it, and revoking the token does not revoke the person. Only the web cabinet can. Seat accounting is enforced rather than assumed: an invitation is refused with 409 seat_limit_reached unless free seats outnumber the invitations already outstanding, and POST /v1/agents/{id}/restore is refused the same way when no seat is free. Invitations are additionally limited to 10 per hour per widget. Mail is sent before anything is stored, so a mail failure (502) leaves no half-created account behind.

Every write that moves status or show_in_header, and both avatar routes, invalidate the served widget cache before responding -- the widget's chat header renders exactly the active agents flagged show_in_header, with their newest avatar, so the change is live on the next visitor's page load rather than after a cache TTL.

Per-agent metrics use stats:read, not agents:read -- they are statistics, they share the window vocabulary and the metric definitions of GET /v1/stats, and they carry no operator identity beyond an agent id. The event log has its own agents:events:read, because its rows are free-text console strings rather than counts. Every agent on a /v1/agents/stats page is present with zero-filled metrics, so "no activity" and "not in the response" are never confused, and an average that is undefined is null rather than a misleading 0. Note which rows belong to whom differs per metric: chats_total and avg_response_time_seconds are chats assigned to the agent, while messages_total counts messages the agent actually sent -- agents routinely reply in chats that were never assigned to anyone, and counting through the assignment would drop those. Every row also carries the agent's name and type (human or ai) and six attribution metrics: chats_accepted (chats opened in the window this agent answered first), chats_handled (chats it handles now -- brought to an end, if the chat is over), chats_transferred_out / chats_transferred_in (handovers in the window from / to this agent: transfers, the AI's escalations to a person, the AI taking over an abandoned chat), chats_missed (chats nobody answered that were last routed to this agent; always 0 for an AI operator, which is never a routing target) and rating_distribution ({"1": n, ..., "5": n} behind rating_average). Ratings are attributed to the agent who was handling the chat when the visitor rated it, which for a chat the AI answered is the AI operator. On the event log, type is a stable slug and is the contract, type_code is the raw internal action code (so an action with no slug yet still arrives, as type unknown, instead of vanishing), and message is the stored console string in Russian -- human-readable, not a contract, do not parse it.

Each agent object carries id, user_id, name, surname, email, avatar_url, role, type (human|ai|webhook), status (active|relaxation|banned), online, show_in_header, ai_assistant_id, departments and created_at. online is live websocket presence, not the stored status column, and name is the full display name with surname repeated separately so you need not parse it. With no ?status= the listing excludes banned agents, exactly as it did before that filter existed; GET /v1/agents/{id} applies no such exclusion, so a suspended agent is readable there and reports banned. A department_id that does not exist, or belongs to another account, is a 404 -- never an empty list.

Files

Fetch-by-url is guarded against SSRF (private/loopback/link-local ranges are rejected, and the resolved IP is re-validated on the one redirect hop this endpoint follows) -- a blocked or unreachable url is reported as 422, not 500.

Stats

Finding dialogs, and replying after a chat has expired. GET /v1/chats lists every state, expired included: a chat becomes expired a few minutes after its last message and returns to active when either side writes again. ?has_client_messages=1 keeps only the chats in which the visitor actually wrote (the same rule as chats_with_client_message in GET /v1/stats, AI-only chats included) and ?q= (2–100 characters) keeps only the chats in which a visible message contains that text; combine them with status and from/to. POST /v1/chats/{id}/messages into an expired chat is accepted, stored in that same chat and reopens it; the visitor sees the reply the next time the same visitor opens the widget on the same site in the same browser — there is no push or e-mail. agent_id is required when the chat has no assigned agent (use a human agent, never the AI operator); 202 only means the message was handed to the websocket daemon, so confirm it with GET /v1/chats/{id}/messages. In GET /v1/stats, chats_accepted_human counts the chats a person answered first — a chat the AI answered and a person then took over is in chats_handled_human and chats_ai_to_human — and avg_response_time_seconds is kept unchanged but is measured from the room's creation, so returning visitors inflate it; use the opt-in avg_first_response_seconds instead.

period accepts today, yesterday, week or month. All four are calendar-anchored in Europe/Moscow -- week starts on Monday and month on the 1st, both running up to now, and yesterday is the whole previous day. It is mutually exclusive with from/to: sending both is a 422, not a silent preference for one of them. chats_missed counts chats opened in the window that nobody answered -- neither a person nor the AI operator -- the same definition as the missed figure in your cabinet's analytics. It used to count chats with no assigned owner, and because the AI operator never becomes a chat's owner, every chat the AI answered was reported as missed; that is corrected. chats_accepted is chats_total minus chats_missed, split by who answered first into chats_accepted_ai and chats_accepted_human, and by who handles the chat now into chats_handled_ai and chats_handled_human; chats_ai_to_human counts chats the AI answered that a person then took over, and chats_human_to_ai the reverse. /v1/stats/channels reports chats_accepted, chats_accepted_ai and chats_accepted_human per channel alongside chats_missed. /v1/stats/timeseries refuses a window that would produce more than 366 buckets with a 422 rather than truncating the series -- ask for a coarser interval instead.

from/to are interpreted in Europe/Moscow, and an explicit UTC offset on them is honoured: 2026-09-01T10:00:00+05:00 selects rows from 2026-09-01T08:00:00+03:00, the same instant. Every timestamp in a response -- from, to and each timeseries bucket boundary -- is returned in Europe/Moscow, so the window you are shown is always the window that was queried.

/v1/stats/channels counts only the channels a customer can reach you through. Internal department chats -- your operators talking to each other or to a department -- are excluded from it. chats_total on /v1/stats keeps its original meaning and still counts every chat, so for a team that uses department chats the channel totals add up to less than chats_total, by exactly that number.

Webhook Subscriptions

events currently accepts one or more of the 7 frozen native event names (see Webhooks for the full catalog and payload shapes), or, when is_jivo_compat is true, one or more of the 5 compat event names instead. A 6th unique-constraint case is also reported as 409: creating a second subscription for a url already registered on this account.

Rotating a secret is an immediate cutover. A subscription holds one secret; the old value is overwritten, not retired alongside the new one, and the delivery worker reads the secret when a queued job runs rather than when it was enqueued. Every delivery signed before the rotation response used the old secret; every delivery signed after it -- including one already queued or already mid-retry-backoff -- uses the new one. Accept both values until the queue can no longer hold work signed with the old one (4 attempts, exponential backoff capped at 60s), then drop it. For the authoritative, always-current list of event names -- and, per event, whether it is currently enabled platform-wide -- call GET /v1/webhook-events rather than relying on any list restated in prose.

Reading the delivery log. payload is what your receiver was actually sent: the stored event ids with the internal numeric button_id removed and personal data (phone numbers, email addresses, card-like digit runs) replaced with the same [скрыто] placeholder the signed body carries, so it never reveals data the webhook itself withholds. A redelivery is re-sent in the envelope the subscription uses right now, not the one in force when the row was recorded, and the 202 body names it as envelope; a native row whose event type has no Jivo-compat equivalent is is_redeliverable: false and 422 while is_jivo_compat is true, and redeliverable again once you switch it back. On an is_jivo_compat subscription this log records final failures only -- no pending row, no success row and no stored payload -- so you will see nothing but failed entries, all is_redeliverable: false; that is expected for compat mode, not a broken integration. Native subscriptions log the full pending/delivered/failed/skipped lifecycle.

AI Replies

The base route scope is responder:inject. Caller-directed handoff via escalate=true or the exact [KEY_TO_OPERATOR] marker also requires responder:escalate. If it is missing, the RFC-7807 403 happens before causation is read or consumed, so the same callback can be retried after the grant is fixed. Empty content and Smartbtn-owned safety floors may still hand off with the base scope alone. All errors here, including validation 422, are RFC-7807. Foreign/nonexistent causation ids share the same non-disclosing 404; malformed or mismatched bindings use 409 without consuming the callback.

AI Configuration

Three objects, and it is worth getting them straight before you write any code. An assistant is a brain — persona, system prompt, temperature, escalation triggers. An AI operator is an identity — the avatar in the widget header, the name replies are attributed to, and the row the chat runtime resolves before it looks up a brain at all. A credential is the provider key and endpoint the reply is actually generated with. A working bot needs all three, plus the master switch on /v1/ai/settings — with that switch off nothing replies, however well everything else is configured.

Free configuration inspection. GET /v1/ai/assistants/{id}/test requires ai:read, no body, Content-Type or idempotency key. Only optional operator_id: one canonical positive decimal integer within the server range, raw query at most 128 bytes; duplicates, arrays, unknown parameters and nonempty bodies return 422 invalid_input. The same resolver as POST returns 404 for missing/foreign assistant or operator and 409 for ambiguous_operator, credential_unavailable or unsupported_transport (including webhook). Success data: assistant_id, operator_id, assistant_enabled, configured_provider, configured_model, configuration_resolved:true, provider_verified:false, provider_http_operations:0, chat_created:false, limits and limitations. Limits: max_body_bytes 131072; max_question_characters/max_history_content_characters 4000; max_history_messages 20; max_total_characters 20000; max_starts 10; rate_window_seconds 60; max_in_flight 1; idempotency_retention_seconds 86400; max_provider_http_operations 10; provider_io_deadline_seconds 45. These are policy limits, not remaining quota. No provider/OAuth/model-list/context/RAG/presence/admission work occurs; normal API auth/rate/diagnostic metadata remains. Disabled assistants stay disabled. Numeric-path GET/HEAD success and errors, including 401/403/429, are no-store. Local resolution does not verify keys, connectivity, quota, models, embeddings, answer safety/quality or delivery. Test approved paid answers before an authorized new launch; preserve existing audit flags.

Detached assistant test. POST /v1/ai/assistants/{id}/test requires ai:write and the normal widget/token access gates. It uses the saved internal provider with normal PII masking and assistant/operator-scoped KB. Disabled assistants remain testable without enabling them. One binding auto-resolves; several require operator_id (otherwise 409 ambiguous_operator). A supplied operator must belong to this widget and assistant (otherwise 404). Without a binding, only assistant/widget credentials and shared KB apply. Webhook/external transport returns 409 unsupported_transport before network; no hidden chat, callback or substitute provider is used.

Input. JSON object only, maximum 131072 raw bytes. question and each history content are non-whitespace strings of 1–4000 Unicode characters; question plus history totals at most 20000 characters. history defaults to [], at most 20 objects with exactly role:user|assistant and content. Unknown fields, duplicate members, forbidden controls and system-role history are rejected. Optional fields reject null. operator_id is a positive JSON integer. locale is exactly ru/en/el/de/es/ar/zh, not auto; omitted uses the customer-message/widget resolver. operators:online|offline|unknown explicitly simulates availability; omitted reads presence without mutation. Saved presence_context_enabled still controls context injection. No model, provider, key, endpoint, prompt or room overrides.

Result: {data:{...}}. answer is safe simulated final text, not rejected raw generation. Identity/provenance: assistant_id, operator_id, assistant_enabled, configured_provider, configured_model, provider_path, locale, operators:{state,source}, presence_context_enabled. configured_provider/configured_model describe the configured primary; provider_path:fallback means a declared backup answered, not that these labels changed. rag_status is disabled/unavailable/empty/included. transformation is answer/social_reply/empty_response/answer_only_recovery/untrusted_handoff_fallback/escalation_outcome; classifier is not_needed/unavailable/escalate/no_escalation. escalation is only a simulated decision; outcome is null or handover_notice/handover_offline/handover_unknown, with offline_outcome_suppressed reported separately. Also returned: provider_http_operations, chat_created:false, limitations[]. No messages, chats, human assignment, learning/statistics writes, queues, notifications or webhook delivery. Normal operational rate-limit, admission/replay and standard diagnostic/auth metadata may be recorded; no customer content or presence is changed. Presence is not transfer confirmation; browser/channel parity and deterministic model answers are not promised.

Cost, limits and recovery. Calls are real and may be billed by your configured provider: agree a budget and run batches sequentially. At most 10 started tests per 60-second widget window and one in-flight test per widget. Each admitted test allows at most 10 actual provider HTTP operations (including embedding, generation, classifier, fallback, OAuth, parameter self-heal and one possible answer-only recovery) under one shared 45-second provider-I/O deadline, not an end-to-end handler SLA. X-Smartbtn-Idempotency-Key: 1–64 bytes, no ASCII whitespace/controls; UUID recommended. The key is claimed atomically before paid work and retained for 86400 seconds even after provider failure or timeout; repeated keys return 409, not a saved answer. Do not automatically retry an uncertain test with a new key. 429 test_rate_limited (busy/quota) includes Retry-After; 503 admission_unavailable fails closed before paid work. Other typed code values: 400 invalid_json/invalid_idempotency_key; 413 body_too_large; 415 unsupported_media_type; 422 invalid_input/duplicate_member; 404 assistant_not_found/operator_not_found; 409 ambiguous_operator/unsupported_transport/credential_unavailable/idempotency_reused; 502 provider_failure; 503 test_unavailable; 504 test_budget_exhausted. Claimed keys survive these failure paths. Inspect configuration and report uncertainty rather than assuming success.

POST /api/v1/ai/assistants/123/test
Authorization: Bearer <SMARTBTN_API_KEY>
Content-Type: application/json
X-Smartbtn-Idempotency-Key: 95684e40-c061-44f8-a183-edf37c39693c

{"question":"What are the published refund conditions?","locale":"en","operators":"offline","history":[]}

/v1/ai/messages is what the platform itself says to your customer on the AI path — not the model's answers. Seven phrases: handoff_to_human (no usable AI reply — it says that and nothing more), the three handover outcomes handover_notice / handover_offline / handover_unknown (operator availability is measured at the moment of the handover and exactly one of them is sent whenever a person is actually asked for, promised or a support ticket is opened (a plain AI answer to a problem statement carries none): an eligible operator was found and the transfer was requested, nobody eligible is online, or availability could not be established — so none of these three, and no override you store for them, may promise a person the platform has not found), social_reply (a bare greeting or thanks the model could not answer; the chat stays with the AI), handoff_to_ai (the AI takes over an unaccepted chat after takeover_timeout_sec) and pii_restore_fallback (the fail-safe text when a masked personal-data placeholder could not be restored). All seven widget languages have platform defaults: ru, en, el, de, es, ar, zh. Each phrase always goes out in the customer's language: when the widget supplies a supported effective locale, it takes priority and is snapshotted for the turn that triggers the reply. Later language changes do not relabel an already queued reply. For legacy clients or messages without a locale, the runtime uses the customer's own messages (Cyrillic → ru, CJK → zh, Latin → the widget's default language), then widget_default_language, then en. This resource stores the wording per language. An override is plain text of up to 500 characters — tags and control characters are stripped, and a value that would be nothing but tags is a 422, never a silently empty phrase. No cache purge is involved: the phrases travel over the chat socket, so a change is live on the next AI turn.

Provider keys are never returned. Not masked, not partially, not once at creation — GET /v1/ai/credentials reports has_api_key and has_signing_secret as booleans and nothing more. ai:credentials:write is a dangerous scope for two reasons: it stores a third-party key the platform then spends on your behalf, and it stores a base_url the platform then calls outbound. That URL is validated far more strictly than the web form validates it — https only, no user:pass@ in the URL, and the host is resolved and refused if it lands in a private, loopback, link-local or cloud-metadata range (including 169.254.169.254). That check runs when you save; DNS can be re-pointed afterwards, so treat it as a guard rather than a guarantee. ai:write deserves similar care for a different reason: it writes persona and system_prompt, the instructions your bot speaks to your customers under.

provider means two different things, so read this once. On a credential it is the real driver key and it decides what actually runs: openai_compatible (with a base_url — this is what you use for OpenAI, OpenRouter, Mistral, YandexGPT and any self-hosted OpenAI-compatible gateway), gemini, anthropic, gigachat, or webhook for an external AI system. The last three address their own vendor endpoint and reject a base_url rather than storing one that would do nothing. On an assistant, provider and model are display labels only — the driver and the model that actually generate a reply come from the credential resolved for that assistant. A credential resolves in three tiers: one scoped to the assistant wins, then one scoped to the operator, then the widget-wide one; scope in the response tells you which tier a row sits in. While auto-translation is enabled, when a create or patch changes the effective active widget-wide non-webhook credential, the old AI widget-text identity is invalidated, the localization revision advances once, the exact widget cache is purged, and current translations are queued asynchronously. With auto-translation disabled, or for scoped, inactive, webhook and older non-winning credential changes, widget localization stays untouched.

Failover chains. A credential can name another active credential on the same widget as its backup via backup_credential_id, up to three links deep, and the runtime walks that cascade under an overall time budget when a provider is unreachable. Cycles and cross-widget links are rejected when you save, not silently at reply time, and backup_chain on a read shows you the cascade as the runtime would resolve it — including a link marked "usable": false when it has since been deactivated. That is also why there is no DELETE on a credential: other rows name it by id. Retire one with {"is_active": false}, which is reversible.

Learning changes the selected assistant. Read learning_target on GET /v1/ai/settings?assistant_id=123. One eligible assistant resolves automatically; none selects legacy_button; several require assistant_id. Approved manual and autonomous improvements update that target’s persona/system_prompt, version and audit history. An old button-level persona does not override a resolved assistant.

Cache and side effects. Changed assistant create/update/delete, migration and marketplace creation purge the widget cache after commit, as do relevant settings/operator writes. No-op and failed assistant mutations do not purge. Cache failure does not roll back committed data. Alerts do not affect widget rendering. Translation-credential changes retain their documented localization invalidation. There are no ai.* webhooks; poll to observe changes. Marketplace creation remains additive, capped at five applications/hour/widget.

Platform behavior around assistant replies

Five built-in categories: explicit_human_request — a direct request for a human; repeated_request — a repeated unresolved question; angry_emotion — signs of dissatisfaction; low_confidence — no reliable answer obtained; complex_billing_legal — a concrete financial/legal operation requiring a person. Asking about general refund conditions is not itself a request to execute a refund. Custom escalation_triggers complement the built-in rules. These are assessment categories, not a trigger-to-guaranteed-phrase mapping: the result depends on content, server assessment and availability. The model’s [KEY_TO_OPERATOR] marker or flag is an untrusted hint, never transfer confirmation.

presence_context_enabled opts into measured human-presence context in the system message. Do not assume that block exists when the flag is off. An online candidate has not accepted the chat; offline or unknown availability must not become a transfer promise. A rejected untrusted handoff hint may trigger one bounded answer-only attempt on the internal synchronous path. On the server-authorized escalation branch, recovery additionally requires a substantive question and no online candidate; a bare operator request does not qualify. Both branches remain budget-limited. An asynchronous webhook is not re-queried.

Default wording and configuration. With no usable answer, handoff_to_human: “I could not prepare an answer — that is a failure on our side, not a problem with your question. Please send the same message again in a minute and I will answer it afresh.” Candidate outcome handover_notice: “I am checking specialist availability. The transfer is not confirmed yet.” Measured offline handover_offline: “All our specialists are busy right now, so I will keep helping you here in the chat. You can also leave your contact details and question in the "Call order" tab.” Unknown handover_unknown: “I could not confirm human availability. I will not claim a transfer and will continue helping here. You can also leave your contact details and question in the "Call order" tab.” Read current wording for all seven locales from GET /v1/ai/messages; PATCH updates supplied phrase/locales, null resets one override, and PUT replaces all overrides. Wording changes do not disable safety checks or authorize false promises. offline_outcome_mode below controls the duplicate addendum, not actual operator presence.

Channels

Outbound deliveries — what Smartbtn sends to your outbound_url

Everything above is a request you make. This is the request you receive: when an operator (or the AI operator) replies in a chat that arrived through your custom channel, Smartbtn POSTs that reply to the outbound_url you registered. Setting that field is what this section's endpoints exist for, so here is what you have to be able to consume.

The request line and body are exactly:

POST <your outbound_url>
Content-Type: application/json
X-Smartbtn-Event: channel.outbound
X-Smartbtn-Signature: sha256=v1:<hex hmac>

{
  "external_channel_id": "your-channel-thread-42",
  "external_client_id": "your-end-user-7",
  "message": {
    "id": 918273,
    "body": "Yes, that is covered by the warranty.",
    "created_at": "2026-09-01T12:34:56+03:00"
  }
}

external_channel_id and external_client_id are the values your channel sent on the way in via POST /v1/channels/{id}/messages, echoed back verbatim — route the reply by them. Smartbtn's own internal room, button and client ids are deliberately never included. message.body is the operator's text after the platform's PII scrubber has run, so it can differ from what the operator typed.

Verification is identical to the webhook one — compute sha256=v1: + HMAC-SHA256 over the raw request body (the exact bytes, before any JSON parsing) using your channel's signing secret, and compare it in constant time; the worked example under Webhooks → Signature verification applies unchanged, substituting the channel secret returned once by POST /v1/channels or POST /v1/channels/{id}/rotate-secret. A rotation takes effect on the very next delivery, with no overlap window.

This is not the webhook transport, and it does not carry the webhook envelope: there is no X-Smartbtn-Idempotency-Key, no X-Smartbtn-Delivery, no X-Smartbtn-Timestamp and no {"id", "type", "data"} wrapper — the three fields above are the whole body. Dedupe on message.id, which is stable across every retry of the same reply. A delivery is retried on a transport error or on any non-2xx status, up to 4 attempts, backing off 10s, then 20s, then 40s; answer 2xx as soon as you have durably accepted the body. Nothing is sent at all while the channel is inactive, has no outbound_url, or has no signing secret — an unsigned delivery is never made.

The https rule on outbound_url is a rule about the URL you register, not an end-to-end TLS guarantee. Only the blocked address ranges are re-checked at delivery time; the delivery job still permits the http scheme on the wire, so if your endpoint answers a delivery with a 3xx to an http:// target, that single re-validated hop is followed in cleartext, carrying the message body and its HMAC. Tightening this belongs to the delivery job and the shared SSRF guard, which serve webhook delivery too; until that lands, do not redirect deliveries — answer them 2xx at the URL you registered.

An inactive channel is not a deleted one, but its inbound endpoint cannot tell you apart from one: POST /v1/channels/{id}/messages answers 404 while is_active is false — the same code an id that does not exist returns, because this API does not distinguish the two. If inbound suddenly 404s, read the channel back with GET /v1/channels/{id}: a 200 with "is_active": false means disabled, and a 404 there too means gone.

Widget Settings

Discover before writing. GET /v1/widget/settings/schema describes every writable and read-only field without customer settings. validation_rules come from the live validator; type and response_type may differ: legacy numeric settings are returned as strings. accepted_types/accepted_values, enum, ranges and strict_json_type describe input. pattern is PHP PCRE with delimiters, not JavaScript regex. default means an absent/normalized GET value, not rendered appearance; read default_semantics and effective_default. Discover dynamic values through catalog_url. This is metadata, not a ready-to-send PATCH body or JSON Schema. Remove read-only fields. device_profiles merges deeply: omission preserves, leaf null removes its override, root null removes profiles; enabled:false preserves data but uses legacy behavior. In contrast, widget_text_translations replaces the entire matrix; {} clears it. Do not automatically materialize a described fallback into an absent field.

PATCH here is merge-safe and deliberately diverges from the web constructor: the constructor's save writes every field on every submit, so anything its form did not send is nulled -- this endpoint writes only the keys present in your body. Sending an appearance field as null clears it: the stored key is removed and the widget falls back to its render default. For every widget_show_* toggle that default is on, so a field you read back as null from GET can be PATCHed straight back with no effect -- send false when you actually want a feature switched off. The six localization-policy fields reject null with 422. Six members GET returns are read-only (widget_id, api_enabled, widget_language_policy_revision, widget_translation_revision, widget_translation_status, updated_at); drop them before you send the resource back, or you get a 422 naming them. It is also stricter: invalid input is a 422, never a silent fall-back to the previously stored value, and widget_button_size is restricted to 50|75|100 even though the web stores it unvalidated. Social/messenger credentials (buttons[]) and the AI, map, price-list, logo and quick-phrase subtrees are not part of this resource and are never returned by it; the api kill switch is read-only here (api_enabled) because disabling it over the API would lock every token out with no way back. Any successful write purges the served widget's cache for you, so the change is live immediately -- POST /v1/widget/cache/purge is only needed when something changed the widget out-of-band.

Localization uses the canonical settings widget_default_language (auto|ru|en|el|de|es|ar|zh), widget_supported_languages, widget_fallback_language, widget_auto_translate_custom_texts, widget_content_source_language, widget_text_translations, and the existing widget_show_lang_switcher. Implicit compatibility defaults remain narrow: legacy widgets use ru/[ru,en]/ru/AI false, while unrelated new widgets use auto/[ru,en]/en/AI false; any additional locale is enabled only by explicit settings. The manual translation matrix is closed to widget_name, widget_signature and widget_greeting, keyed by enabled locales. The read-only widget_translation_revision is an alias of widget_language_policy_revision; the translation collection returns the same value as revision. Its items expose status and provenance but never translated text. Resolution is manual override → current AI value for the exact source hash → tenant source → locale catalogue fallback. With no translation table, settings report {available:false, enabled, reason:schema_unavailable, revision, total:0, counts:{ready:0,stale:0,pending:0,failed:0}}, the collection is empty, and rendering still uses a non-empty source/catalogue fallback. Regeneration is asynchronous and requires an active widget-wide provider credential with neither operator_id nor ai_assistant_id; otherwise status reports credential_missing and rendering keeps the fallback. It requires X-Smartbtn-Idempotency-Key and returns 202. For forced regeneration, stale-while-revalidate keeps the last validated exact-current AI text visible while its replacement is pending and after a failed attempt, under the same revision. A successful publish atomically replaces that text, advances the revision and purges the served-widget cache. A command rejected before dispatch with 422, 429 or the endpoint's 503 releases that key, so it can be retried after the condition is corrected. Every save, API/admin regeneration and recovery job shares one atomic budget of 42 provider-job reservations per widget per 3600-second Redis window; a batch is accepted whole or rejected whole, and an accepted reservation remains spent even if later enqueueing fails. Exhaustion returns 429 with Retry-After and code widget_translation_rate_limited. If the translation store is unavailable, reads degrade safely while explicit regeneration returns RFC-7807 503 with code widget_translation_store_unavailable. If the atomic budget reservation itself is unavailable, provider calls fail closed while explicit regeneration returns 503 with code widget_translation_budget_unavailable. While auto-translation is enabled, creating, rotating, deactivating or re-scoping the effective widget-wide translation credential also invalidates its old AI text, advances this revision once, purges the widget cache and queues the new exact identities. With auto-translation disabled, or for scoped, inactive, webhook or older non-winning credentials, the change is a localization no-op.

/v1/widget/language is the same widget_default_language that /v1/widget/settings carries, on its own, for an integration that only cares about language and should not have to read or risk writing forty appearance fields. It is a PUT because the resource is exactly one field and the body always states it whole. It also shows the server-side consequence the settings resource does not: effective_language is the language the AI's client-facing phrases (/v1/ai/messages) fall back to when no accepted widget client locale is available and a customer's own messages carry no readable script — auto resolves to en there, as the server-side fallback, and a widget that never set a language resolves to ru, the historical default. The language-policy revision advances only on an effective change, with the same rule the web constructor uses.

Account

This is the one resource where a widget-scoped token reads account-scoped data, so read this before you grant account:read. Your token belongs to a single widget, but an account does not: this endpoint returns the profile of the user who owns that widget, together with every legal entity registered on the account — full bank requisites (bank_name, bik, checking_account, correspondent_account) and registration identifiers (inn, kpp, ogrn) included. If the same person owns several widgets, a token minted for any one of them reads the same account object. There is no id to pass and no way to reach a different account — the owner is resolved from your own token — but there is also no narrower variant of this scope: if that width is more than your integration needs, leave account:read off the token.

PATCH writes exactly three fields — name, surname, phone — and is merge-safe: only keys present in your body are written, and an explicit null clears one. Everything else GET returns is read-only and is refused by name with a 422 that says why, so the ordinary read-modify-write round trip tells you which keys to drop rather than failing on a generic "unknown field". It is stricter than the web, which validates none of these: phone accepts an optional +, a leading digit, then digits, spaces, parentheses or hyphens, up to 32 characters, and name/surname reject control characters. Three refusals are permanent, not "not yet": changing the account email, changing the password, and deleting the account. The web email change requires your current password as a step-up and a bearer token cannot supply one, so allowing any of the three would turn a leaked token into full account takeover — use the web cabinet. Minting API tokens is web-only for the same reason. legal_entities is refused too. Those records carry account-wide bank details: read them here with account:read, or create/change/delete them through the dedicated billing entity operations under billing:write. Finally, changing name changes what the served widget renders — it is your operator label in the widget header — so a name change purges the widget cache of every button this account owns. surname and phone are not rendered by the widget and purge nothing. One residual: if this user is also an operator on someone else's widget, that widget keeps the old label until its own 60-second cache entry expires; this endpoint will not purge another account's cache.

Departments

A department is a routing rule, not a container: it pairs a set of agents with a set of channels and a working week, and the platform consults it when it decides whether an agent is on duty for an incoming chat. That is why the agent set and the week are replaced whole with PUT rather than merged — neither has per-item identity, so "add this one" and "this is the set" would be indistinguishable in a PATCH. Sending either of them to PATCH /v1/departments/{id} is a 422, never a silent no-op. Four members GET returns are read-only (id, avatar_url, created_at, updated_at); drop them before you send a department back, or you get a 422 naming them.

This resource is stricter than the web constructor in three places, on purpose. (1) Every agent_id you send is checked against this widget before anything is written; the constructor does not check at all, so an id it would have accepted can be a 422 here. The same check applies to an av__<n> Avito channel. Unknown and cross-account ids report identically, so neither can be used to probe what exists elsewhere. (2) channels is a closed vocabulary (tg, vk, wa, vb, fb, ok, smb for the on-site widget, or av__<avito_cabinet_id>); anything else is a 422 rather than a stored value that would simply never match a chat. A provider does not have to be connected yet. (3) In a {from, to} day, from must be strictly earlier than to — the constructor quietly rewrites an inverted range into "open all day", which this API refuses instead. Overnight ranges are not supported; use "full".

schedule always comes back with all seven days, in Monday-to-Sunday order, whatever is stored: a department created in the web cabinet can have a partial week, and the days it never wrote read back as null (closed), which is exactly how the routing check already treats them. agent_ids is read from the agent links the routing runtime actually consults, intersected with this widget's own agents, so a stale link the web cabinet left pointing at another account's agent is dropped rather than returned. It carries ids only — for the full agent objects call GET /v1/agents?department_id={id}, which is what that filter is for. A suspended agent stays in the set: suspension is reversible, and this API never silently rewrites the set you send, so the set you send is the set you read back. Note that the department chat fan-out does not currently filter suspended agents, so one left in the set is still attached to new department chats. Deleting a department leaves the chats it already produced in place; they keep their internal-chat marker with no department behind them, exactly as the web cabinet's own delete behaves.

Billing (read-only)

Everything here is a read except the three entity writes, and the entity endpoints are wider than your token. Billing records are stored per account, while your token is issued for a single widget. The balance, transaction, subscription and invoice endpoints are narrowed back down for you — they require the record to match both this widget and its owning account, so a record belonging to a sibling widget is invisible to you. /v1/billing/entities cannot be narrowed that way: legal entities are stored against the account and the table carries no widget column at all. So a token issued for one widget can read, and with billing:write also change, the owning account's legal entities, including entities used to pay for that account's other widgets. It can never reach another account's. If that is wider than you want to grant an integration, leave those scopes out of the token.

Every monetary value is an integer in minor units (kopecks) and is named with a _minor suffix, next to a currency and the minor_unit_scale returned by /v1/billing/balance. There are no decimals and no float rounding anywhere in this domain. This is a deliberate divergence from storage: the underlying tables are not consistent — balances and ledger movements are stored in kopecks while catalogue prices, subscription charges and invoice totals are stored in whole roubles — and the API resolves that to one unit rather than passing the ambiguity on to you.

Statuses are stable slugs, never the stored integers. The internal status vocabularies here are legacy magic integers drawn from two unrelated constant tables whose values overlap and whose meanings do not; they are an implementation detail and they will change. Every one of them is mapped to a snake_case slug, and every filter accepts slugs only — an unrecognised value is a 422, never a filter that silently returns the whole collection. unknown is a member of every enum on purpose: a status the platform starts writing after your integration ships arrives as unknown rather than as a new raw integer, so switch on the slugs you know and treat the rest as unknown.

What this domain deliberately does not expose. There is no card data anywhere in it, and no endpoint takes a card id — the stored card records hold the number, expiry and CVC in the clear, so they are neither serialised nor joined. Invoices for physical persons (transaction_cards) are not exposed for that reason; only bank-transfer invoices raised against a legal entity are. Invoice PDFs are not linked: has_document tells you one exists, and files are served by the files domain behind its own scope. Invoice items are returned only where the line-item record unambiguously belongs to the invoice you asked for; invoices raised by the legacy admin path report an empty items array rather than risk attributing another payment's lines to yours. And billing:write buys exactly three things — create, change and delete a legal entity — and nothing else. No endpoint in this domain accepts a price, an amount or a total; no endpoint raises an invoice; no endpoint moves money. Those are computed server-side or they do not ship.

Before you automate entity writes, read this. A legal entity is the payee record a partner withdrawal is resolved against, and it is resolved when an administrator approves the payment, not when the request is raised — nothing about the recipient is copied at request time. So while an unpaid withdrawal names an entity, PATCH and DELETE on it are refused with 409 and entity_locked_by_pending_withdrawal. Settle or cancel the withdrawal first. DELETE has a second refusal, entity_referenced_by_financial_record, when an invoice or a transaction already names the entity: those are issued documents and the counterparty they name has to keep existing. Creating is strict on purpose — every field is required, and the bank identifiers are digits-only and exact-length, because the underlying columns cannot be null and the web form only survives that by storing an empty string for anything you leave out. Send account numbers as JSON strings. All three writes share one budget of ten per hour counted per account, not per widget, since every widget on an account addresses the same entities.

Messengers, VK communities & Avito

Three related surfaces: the messenger credentials stored on the widget itself, the VK communities wired to it, and its Avito cabinets. Every write here needs messengers:write, which is a dangerous scope for a concrete reason: these calls store third-party bot credentials and change webhook registration on the provider's side. A wrong call can silently repoint or remove a live bot's webhook and take that channel's inbound down. Read the webhook object in every write response — a 200 on its own does not mean inbound is working.

What a write does on the provider's side

PUT /v1/messengers/{provider} runs three steps in this order: a read-only probe of your credential (Telegram only — no other provider offers a call that changes nothing), then the local write, then webhook registration with the provider. If the probe gets a real rejection you get a 422 and nothing is stored and nothing is touched at the provider. If the registration afterwards fails, your credential is saved and only inbound is not live yet: retry with POST /v1/messengers/{provider}/verify. We never do it the other way round, because repointing your live bot at us for a credential we might then fail to store is the one outcome with no cheap way back. What each provider actually does: tg setWebhook — or, if this deployment runs Telegram in long-poll mode, deleteWebhook plus getMe, because a live webhook would break the poller; vb set_webhook; ok graph/me/subscribe; mx POST /subscriptions; cian its webhook subscribe; ali a subscribe call whose contract is unverified, so it is reported as unconfirmed_provider_api and never as success. fb, wa and apple have no webhook mechanism on this platform at all and report attempted: false.

Deletes. DELETE /v1/messengers/{provider} tries the provider-side removal first but never lets it block the delete — a provider outage must not leave you unable to remove a channel. If that call fails we remove our record anyway, so a webhook may remain registered on the provider side. It is inert (inbound for a removed channel is dropped), and you can clear it from the provider's own console or by re-connecting the same token and deleting again. Only tg and cian have a real unregister call. VK is the deliberate exception: DELETE /v1/messengers/vk/communities/{id} keeps the community and answers 502 if VK does not confirm, because that row holds the only copy of the community token and server id — dropping it would strand a callback server still injecting into your chat with nothing left to address it with.

Secrets are write-only. No read ever returns a token, sid or community key — you get has_token / has_sid booleans. Webhook URLs are not returned either, because Telegram's and AliExpress's embed the bot token in the path by protocol design.

Stricter than the web cabinet, on purpose. The constructor checks only that a field is non-empty; this API validates types, lengths and the provider vocabulary and answers 422, never falling back to your previously stored value. apple and custom carry a real URL, which must be https and must not resolve to a private or link-local address. Connecting, verifying and enabling require a paid plan — on the free plan the served widget renders no messenger channels at all, so the write would have no visible effect — but removing never does: if you downgrade you can still disconnect your bots rather than having credentials and live webhooks stranded behind a paywall. vk and custom are readable and deletable but not writable — connect VK through POST /v1/messengers/vk/communities. Avito status accepts enabled and disabled only: suspended_by_billing belongs to the billing system, so you can neither set it nor leave it here, and enabling is capped by the Avito slots your plan actually includes.

There is no way to create an Avito cabinet over this API. A cabinet only exists after the interactive Avito OAuth redirect, which is what produces its access token, refresh token and expiry — all of them required columns. A bearer token cannot complete that redirect, so cabinets are created in the web cabinet and read, enabled, disabled and deleted here. Deleting one is permanent as far as this API is concerned. VK is the same story in reverse: the old user-OAuth connection flow was retired by VK in 2024, so a community access token is the only supported way in.

Every endpoint that talks to a provider carries its own limit of 10 calls per minute per widget, on top of the shared token limit. It is counted per widget, not per token, so minting a second token does not raise it — what is being protected is your account with the provider. Any successful write also purges the served widget's cache, so the social row updates immediately.

Migration-compat routes

The three routes below exist specifically to make migrating an existing bot/channel integration from a third-party chat platform to Smartbtn a base-URL-and-token swap rather than a rewrite. They accept that platform's webhook wire shapes verbatim and translate internally onto the native endpoints above -- they are not part of the native /v1 resource surface, live under their own /compat/jivo prefix, and are authenticated differently (a token or secret embedded in the URL path, matching the legacy convention, rather than an Authorization header).

Writing knowledge rules (POST /v1/kb/rules, PATCH /v1/kb/rules/{id}). Only content and doc_id are writable. A rule you read carries more than you may send back: button_id, operator_id, source_ref and chunk_index are refused by name with 422 and code kb_read_only_field, and every other field of a read rule (id, source, source_label, source_is_managed, token_count, has_embedding, embedding_dimensions, created_at, updated_at) is refused as an unknown field — so read the rule, change the text, and send back only content (and doc_id if you use one). The rule is embedded with the widget's LLM key: the widget-wide key or, when the key was saved for one assistant, the key of the widget's enabled assistants (the default assistant's first); with neither, the answer is 422 kb_embed_credential_missing. A 502 kb_embed_provider_failed means the embedding provider failed: nothing was written and the idempotency key is released, so the same request can be retried with the same key.

Header exemptions: DELETE /v1/agents/{id}, DELETE /v1/agents/{id}/avatar, DELETE /v1/agents/invitations/{id}, DELETE /v1/channels/{id}, DELETE /v1/webhook-subscriptions/{id}, DELETE /v1/departments/{id}, DELETE /v1/ai/assistants/{id}, DELETE /v1/ai/operators/{id}, DELETE /v1/messengers/{provider}, DELETE /v1/messengers/vk/communities/{id}, DELETE /v1/messengers/avito/cabinets/{id}, DELETE /v1/kb/rules, DELETE /v1/kb/rules/{id}, DELETE /v1/kb/crawler, DELETE /v1/kb/uploads/{id}, DELETE /v1/external-operators/{public_id}, DELETE /v1/billing/entities/{id}. POST /v1/ai/replies instead deduplicates with its single-use causation_id.

Desktop and mobile profiles. PATCH /v1/widget/settings accepts device_profiles: {version:1,enabled:true,desktop:{},mobile:{}}. Mobile is width ≤480px; desktop ≥481px. GET is null or a sparse canonical envelope; no inherited leaves or breakpoint field. PATCH merges recursively; omitted leaves preserve, leaf null removes an override, root null removes profiles. The first partial PATCH starts at version 1, disabled, with empty profiles. Profile values must be objects, never null/arrays; unknown keys and wrong JSON types are 422. Use JSON integers for launcher_size_px (44–160), all four launcher_offset_x_px/y_px and chat_offset_x_px/y_px (0–9999), launcher_reveal_delay_sec (0/30/60/90/180), auto_open_delay_sec (0/15/30/60/90; 0 disables). show_signature and show_logo are booleans. All fields apply on both profiles. position accepts smartbtn-position-widget-in-page-bottom-left, smartbtn-position-widget-in-page-bottom-right, smartbtn-position-widget-in-page-top-left, smartbtn-position-widget-in-page-top-right. Chat offsets anchor at that corner; mobile offsets shrink the fullscreen rectangle.

Profile defaults and aliases. Missing values inherit legacy settings: size 100px, bottom-right, launcher offsets 20px, chat offsets 0px, auto-open 0, signature/logo true when legacy values are absent. Signature inherits widget_show_copyright and means the copyright footer, not header widget_signature. Enabled profile reveal defaults to 0; disabled/absent profiles retain 1-second legacy reveal. Reveal happens once; breakpoint changes rearm pending timers, user open/close consumes auto-open. Profile-local widget_button_freeze aliases launcher_reveal_delay_sec, and widget_button_open aliases auto_open_delay_sec. Alias plus canonical key is 422; GET returns only canonical names. Top-level widget_button_freeze still means operator-assignment delay. Legacy widget_button_size remains 50/75/100; use profiles for intermediate sizes. widget_offset_x/y replace the default 20px edge distance, not add to it.

Localized assistants. POST/PATCH assistants accept greeting_i18n as locale → string and quick_phrases_i18n as locale → array of strings. Supported locales: ru/en/el/de/es/ar/zh. Omission preserves, null clears, a supplied map replaces the whole field; GET returns object or null. Empty maps, unsupported locales, duplicate/canonically colliding keys such as en and en-US, and invalid leaf types fail atomically with 422. Greeting: 1–4000 characters; each locale has 1–200 quick phrases, each 1–500 characters and ≤2000 bytes. Text is trimmed, line endings normalized, phrases deduplicated preserving order; each encoded map ≤60000 bytes. Raw assistant JSON >2097152 bytes gives 413; malformed JSON 400; depth/member complexity 422. Legacy greeting/quick_phrases remain supported. The widget resolves current locale → configured fallback locale → same assistant legacy value → widget greeting/no phrases. A unique eligible assistant initializes the widget; later authoritative operator-authored messages select the target. Ambiguous/stale/foreign targets use generic content, never another assistant’s phrases. Phrase clicks send through the normal message API.

Learning target and audit. learning_target has exactly status, storage, assistant_id, operator_id, persona_version, eligible_targets. Implicit GET statuses resolved|legacy|assistant_target_required|overflow all return 200; storage is assistant|legacy_button|null. Ambiguity includes sorted eligible id pairs (≤100); overflow includes no partial list. Optional positive assistant_id selects an eligible owned target; invalid query is 422, foreign/disabled/unbound target 404. Learning settings, cycles, history, persona-version list/detail and tune accept ?assistant_id=123; version revert and wish creation accept it in JSON. Wishes retain their creation target. Read /v1/ai/learning/history for patches and /v1/ai/learning/persona-versions/{version} for snapshots; version numbers belong to the target. Revert requires expected_active_version and appends a new version; stale writes are 409. confirm_legacy_persona_target is no longer accepted. Shadow probation can roll back a change automatically; overlapping targets keep shadow enabled until the final probation releases it.

Offline addendum. PATCH /v1/ai/settings accepts offline_outcome_mode: always|suppress_after_safe_reply; null resets to always, also the default. The opt-in mode omits only the measured-offline addendum after a verified safe substantive assistant reply. Unknown/online presence, provider errors, unsafe/fallback replies and bare human requests do not gain suppression. Customize handover text in /v1/ai/messages. A mixed PATCH containing shadow_mode during probation returns 409 shadow_mode_probation_active, deferred:true, and saves none of the submitted settings. A corrupt lease returns 409 shadow_probation_lease_corrupt, preserves sibling settings and keeps shadow true; neither conflict purges cache.

Wire formats. /v1/kb/search returns results in data.hits. Messages are application/json; transcript is text/plain; both use UTF-8 without BOM. icon_custom_animated accepts exactly false/0/"0" → "0", true/1/"1" → "1", 2/"2" → "2", or null to clear. GET remains string "0"/"1"/"2" or null; "false", "true", floats and "01" are invalid.

Page language and translations. widget_default_language: auto/ru/en/el/de/es/ar/zh. A fixed/default fallback locale must be enabled in widget_supported_languages. Initial priority: saved visitor choice when the switcher is enabled → supported window.SmartbtnLocale set before the embed script → fixed widget default → supported <html lang> → browser languages → configured fallback. Region tags resolve to a supported primary locale. Only auto mode follows dynamic html lang changes; fixed widget language, an explicit host override and a current saved visitor choice remain authoritative. widget_text_translations is field → locale → text, restricted to widget_name, widget_signature, widget_greeting; for example {"widget_greeting":{"ru":"Здравствуйте","en":"Hello"}}.