Типичный сценарий: клиент пишет вам в продукт (чат магазина, форма, бот, почтовый шлюз). Вы знаете, кто это. Sapportly хранит ленту источника, AI и операторов. Доставку ответа обратно человеку делаете вы — кроме виджета, который Sapportly доставляет сам.
Создать канал
В панели или через client.channels.create. Дальше приём входящих шлёт в источник, например custom:shop. Тред появится сам из identity.external_id.
Класть входящие
const CHANNEL = "custom:shop";
await client.ingest.send({
channel: CHANNEL,
body: comment.text,
idempotency_key: `shop:${order.id}:${comment.id}`,
identity: {
email: customer.email,
external_id: customer.id,
},
});Слушать исходящие
Оператор отвечает в панели, AI шлёт черновик, ваш код может ответить через inbox.reply. Кадры приходят в SapportlyInbox или на вебхук. Можно не ставить вебхуки вообще — держать только сокет. Полный протокол и догон истории: Входящие и живой канал.
import { SapportlyInbox } from "@sapportly/sdk/realtime";
const inbox = new SapportlyInbox(client, { channels: [CHANNEL] });
inbox.onVisitor((m) => persistLocally(m));
inbox.onAgent(async (m) => {
if (m.echo) return;
await deliverToCustomer(m.externalId, m.body);
});
inbox.onAi((draft) => {
if (draft.partial) return;
showSuggestedReply(draft.draft_body);
});
await inbox.connect();Ответить самому
Если отвечает ваш бот, а не оператор: сначала доставьте текст человеку, затем запишите исходящее в ленту. Кадр своего ответа придёт с echo: true.
await deliverToCustomer(customerId, text);
const thread = await bindThreadKey(CHANNEL, { externalId: customerId });
await inbox.reply(thread, text);Только HTTP, без сокета
Если процесс не может держать WebSocket: включите вебхук, слушайте message.received и agent.reply, отвечайте conversations.reply. Черновики ИИ (ai.draft) на вебхук не приходят — только финальный автоответ, если он включён в панели. Подпись: гайд по вебхукам.
Что не делать
- Путать приём входящих и ответ: приём — входящее, ответ — исходящее агента.
- Класть API-ключ в браузер. Виджету нужен Site ID, серверу — ключ.
- Проверять вебхук через
@sapportly/api/webhooks: там нет timestamp. Берите@sapportly/sdk/webhooks.