Протокол TwinCard Bots, версия 1

Как подключить чат-бота сторонней компании к цифровому сотруднику на бизнес-странице TwinCard. Модель — как у сервисов вида «адрес бота + токен»: TwinCard — канал, ваш бот — мозг.

Как это устроено

Компания заводит в TwinCard цифрового сотрудника типа «Внешний бот» («AI-сотрудники» → «+ сотрудник»). Для посетителей это обычный сотрудник: та же цифровая команда на странице, та же кнопка «Написать», виджет, приложения, Telegram.
Во вкладке «Подключение» компания вставляет адрес вашего бота (webhook) и ваш токен. TwinCard выдаёт адрес для ответов и секрет подписи — их вы вставляете у себя.
Посетитель пишет сотруднику → TwinCard присылает сообщение на ваш адрес → вы отвечаете сразу или позже → ответ появляется в том же чате.
Компания видит переписку в AIRONIK и может перехватить разговор оператором; пока разговор у человека, TwinCard вам сообщения этого разговора не пересылает. Расписание и пауза сотрудника действуют так же.

1. Сообщение от TwinCard

POST на ваш адрес бота, только https://. Заголовки:

Заголовок	Значение
`Content-Type`	`application/json`
`Authorization`	`Bearer <ваш токен>` — если вы выдали токен
`X-AI2-Timestamp`	время отправки, секунды Unix
`X-AI2-Signature`	`sha256=` + hex(HMAC-SHA256(timestamp + "\n" + тело запроса, секрет))

{
  "event": "message",                 // "test" — кнопка «Проверить связь» в TwinCard
  "version": 1,
  "bot":          { "id": "1c0f…-guid сотрудника", "name": "Анна" },
  "conversation": { "id": "g1234", "channel": "web" },   // web | telegram | app | voice | test
  "visitor":      { "id": "обезличенный sha256", "name": null, "lang": "ru" },
  "message":      { "id": "98765", "text": "Здравствуйте, сколько стоит стрижка?", "sent_at": "2026-10-03T17:00:00Z" },
  "history": [ { "role": "visitor", "text": "…" }, { "role": "bot", "text": "…" }, { "role": "operator", "text": "…" } ],
  "reply_url": "https://twincard.ru/api/public/bots/<guid сотрудника>/reply"
}

conversation.id — постоянный идентификатор разговора; передавайте его обратно в позднем ответе.
visitor.id — обезличенный идентификатор посетителя, постоянный для пары «посетитель — ваш бот». Имени и контактов посетителя TwinCard не передаёт.
history — до 10 последних сообщений разговора до текущего.
Проверяйте подпись и время: расхождение больше 5 минут — отклоняйте запрос.

2. Ваш ответ

Сразу — в ответе на запрос (до 10 секунд)

HTTP/1.1 200 OK
Content-Type: application/json

{ "reply": "Здравствуйте! Стрижка — от 1 500 ₽. Записать вас?" }

Подходят также {"text": "…"} и {"messages": [{"text": "…"}, {"text": "…"}]} (несколько сообщений склеиваются в одно). До 8 000 символов. Только бот, отвечающий сразу, может говорить в голосовом звонке — текст читает голос TwinCard.

Позже — отдельным запросом

Ответьте на сообщение TwinCard кодом 200 или 202 без поля reply (например, {"accepted": true}), а ответ пришлите на reply_url:

POST https://twincard.ru/api/public/bots/<guid сотрудника>/reply
Content-Type: application/json
X-AI2-Timestamp: 1790000000
X-AI2-Signature: sha256=<hex(HMAC-SHA256(timestamp + "\n" + тело, секрет))>

{ "conversation_id": "g1234", "text": "Записала вас на 18:00. Ждём!" }

Ответ TwinCard	Значение
`200 {"success": true, "data": {"delivered": true}}`	ответ доставлен посетителю
`200 … "delivered": false`	разговор сейчас ведёт оператор компании — ответ не показан
`401 stale / bad_signature`	неверная подпись или время
`404 conversation_not_found`	разговор не принадлежит этому сотруднику
`422 bad_payload`	нет текста или идентификатора разговора

3. Ошибки и недоступность

Ваш адрес не ответил или вернул не 2xx — посетитель на сайте и в Telegram видит «сотрудник временно недоступен»; сообщение в приложении TwinCard будет переслано повторно чуть позже.
После 10 сбоев подряд подключение помечается в кабинете компании как «ошибка связи»; пересылка продолжается.
Компания может поставить подключение на паузу или отключить внешнего бота — тогда сотрудник снова отвечает ИИ платформы.

4. Проверка подписи — пример

// PHP
$expected = 'sha256=' . hash_hmac('sha256', $_SERVER['HTTP_X_AI2_TIMESTAMP'] . "\n" . file_get_contents('php://input'), $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_AI2_SIGNATURE']);

// Node.js
const sig = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '\n' + rawBody).digest('hex');

# Python
sig = 'sha256=' + hmac.new(secret.encode(), (ts + '\n').encode() + raw_body, hashlib.sha256).hexdigest()

5. Что дальше (следующие версии)

Действия — поле actions в ответе: выдать номер события (ИНС), предложить форму заявки, позвать оператора. TwinCard выполнит действие и вернёт результат боту.
Знания — ваш бот сможет искать по базе знаний компании в TwinCard.

Delta Key — тестовый стенд: здесь можно завести бота и проверить весь путь до продакшена.