За пять минут вы соберёте минимальный контур поддержки: безопасный ключ на сервере, стабильный идентификатор клиента, первое обращение и операторский ответ. Для виджета ключ не нужен — браузер получает короткую visitor-сессию после проверки домена.
Ключ
Регистрация на sapportly.pro. В панели — Настройки → API-ключи. Секрет показывается один раз. Для этого старта достаточно прав messages:write, conversations:write, ws:connect.
Установить Sapportly TypeScript SDK
Пакет — @sapportly/sdk (npm-org sapportly), не @supportly/sdk: это имя на npm для SDK недоступно. Продукт остаётся Sapportly.
npm install @sapportly/sdkpnpm add @sapportly/sdkyarn add @sapportly/sdkbun add @sapportly/sdkПриём входящих и ответ
Base URL по умолчанию: https://staging-api.sapportly.pro. Ключ — SAPPORTLY_API_KEY (legacy alias: SUPPORTLY_API_KEY). Источник — custom:shop. Тред 1:1 появится из identity.external_id. Виджет на сайте — отдельный гайд, без ingest.
import { SapportlyClient } from "@sapportly/sdk";
const client = new SapportlyClient({
apiKey: process.env.SAPPORTLY_API_KEY ?? process.env.SUPPORTLY_API_KEY!,
});
const accepted = await client.ingest.send({
channel: "custom:shop",
body: "Где заказ #1042?",
identity: { email: "ada@example.com", external_id: "ord_1042" },
});
await client.conversations.reply(accepted.channel!, {
body: "Смотрим статус, ответим в течение часа.",
});Слушать в реальном времени
import { SapportlyInbox } from "@sapportly/sdk/realtime";
const inbox = new SapportlyInbox(client, { channels: ["custom:shop"] });
inbox.onVisitor((m) => console.log("in", m.body));
inbox.onAgent((m) => {
if (m.echo) return;
console.log("out", m.body);
});
await inbox.connect();После reconnect сокет не обещает replay. На событии open дочитайте историю через REST и дедуплицируйте по message_id. SDK делает ticket, backoff и дедупликацию за вас.
Если нужны файлы
Не отправляйте байты через API-сообщение. Сначала создайте upload intent, загрузите файл по presigned PUT в S3, вызовите complete и передайте полученный id в сообщение. Подробности — в разделе Вложения.