Как подключить аккаунт TikTok к подписанному webhook через QR-авторизацию

Чтобы получать сообщения TikTok через UnifyPort, начинайте не с QR-экрана, а с webhook. Безопасный порядок такой: зарегистрировать webhook endpoint с signing_secret, создать аккаунт TikTok с auth_mode: "qrcode", запустить QR-авторизацию, опрашивать состояние QR, дать владельцу аккаунта отсканировать код, а затем сохранять входящие события message.received до любой маршрутизации.

Главное

• Создайте webhook до авторизации: и прогресс авторизации, и входящие сообщения приходят как события.
• TikTok в UnifyPort использует стандартные account и QR auth endpoints; первый start response может еще не содержать QR URL, поэтому нужен polling QR check endpoint.
• Проверяйте X-Device-Signature по строке X-Device-Timestamp + "." + raw body до JSON parsing.
• Сначала сохраняйте event в durable storage, потом отправляйте его в Slack, helpdesk, AI worker или очередь.
• Не смешивайте этот flow с официальной TikTok Login Kit QR authorization: официальный Login Kit относится к app login, profile и scoped access.

Если вы еще выясняете, существует ли публичный DM API для TikTok, начните с статьи TikTok DM API. Этот материал уже про следующий шаг: подключение TikTok через unofficial interface UnifyPort к подписанному входящему потоку. Для общей архитектуры receiver откройте рядом webhook-first inbound checklist.

Порядок настройки

1. Создайте HTTPS webhook endpoint и задайте signing_secret.
2. На первом тесте подпишитесь только на message.received.
3. Создайте TikTok account с auth_mode: "qrcode".
4. Запустите QR authorization flow.
5. Опрашивайте QR check endpoint, пока не появится QR material, success state или failure state.
6. Дайте владельцу TikTok-аккаунта отсканировать QR и подтвердить подключение.
7. Дождитесь auth/runtime events, затем отправьте тестовое сообщение и проверьте message.received.

Первый шаг важен: документация UnifyPort описывает webhook как долговременную запись inbound traffic. Не проектируйте систему так, будто пропущенные deliveries всегда можно полностью восстановить позже.

1. Зарегистрируйте подписанный webhook endpoint

В production используйте стабильный HTTPS URL под вашим контролем. В разработке можно использовать tunnel, но signature verification должен совпадать с production.

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://inbox.example.com/unifyport/tiktok",
  "status": "active",
  "subscribed_events": ["message.received"],
  "signing_secret": "sea-support-tiktok-2026"
}'

В Create webhook endpoint reference описаны url, status, subscribed_events, signing_secret и retry_policy.max_attempts. Для всех публичных стандартных событий можно использовать ["*"], но для первого TikTok inbound теста явный message.received проще отлаживать.

2. Создайте TikTok account

Один channel login в UnifyPort соответствует одному account. TikTok provider guide описывает этот канал как QR-code authorization flow.

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "TikTok Support Inbox",
  "provider": "tiktok",
  "region": "global",
  "status": "active",
  "auth_mode": "qrcode",
  "capabilities": ["receive_message"],
  "provider_data": {},
  "metadata": { "workflow": "support-intake" }
}'

Сохраните account ID из ответа. Ниже используется $ACCOUNT_ID, чтобы не вставлять настоящий production identifier в логи или чаты.

3. Запустите QR authorization и polling

Запустите QR flow с пустым body:

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/qr/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Для TikTok первый start response может еще не содержать QR URL. Продолжайте polling:

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/qr/check" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Когда QR material появится, показывайте его только владельцу подключаемого TikTok-аккаунта. После сканирования и подтверждения ожидайте auth/runtime events на webhook, а затем первое message.received.

4. Проверяйте signature до JSON parsing

Webhook delivery and signature verification задает контракт доставки. Если signing включен, delivery содержит X-Device-Timestamp и X-Device-Signature; подпись — это hex HMAC-SHA256 от:

<X-Device-Timestamp>.<raw request body>

Минимальный Express receiver должен сохранить raw body:

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const signingSecret = process.env.WEBHOOK_SIGNING_SECRET;

app.post('/unifyport/tiktok', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Device-Timestamp') ?? '';
  const signature = req.get('X-Device-Signature') ?? '';

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(timestamp + '.')
    .update(req.body)
    .digest('hex');

  if (signature.length !== expected.length) return res.sendStatus(401);
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString('utf8'));
  if (event.type === 'message.received' && event.provider === 'tiktok') {
    // store event.id, event.account_id, event.occurred_at и event.data before routing
  }

  res.sendStatus(202);
});

Если подпись не совпадает, проверьте raw body, timestamp, secret и порядок middleware по webhook HMAC replay-protection guide. Частая причина — проверка уже распарсенного или переформатированного JSON.

Как выглядит message.received

Стандартный event envelope всегда содержит id, type, provider, account_id, occurred_at и data. Receiver должен хранить этот общий контракт, а не TikTok-only schema.

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "tiktok",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:34:56Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "3003",
      "text": "Hi - is this item still available?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:34:55Z"
    }
  }
}

Сначала сохранение, потом маршрутизация. AI classification, CRM enrichment и назначение оператора должны выполняться после durable acceptance события.

Ограничения и компромиссы

• Владелец TikTok-аккаунта должен реально отсканировать QR и подтвердить авторизацию.
• Provider support и upstream availability могут отличаться по аккаунтам и регионам; UI должен показывать failure и re-authentication states.
• Webhook delivery — at-least-once. Используйте event.id или X-Device-Event-Id как idempotency key.
• HMAC подтверждает источник и целостность, но не шифрует ваши logs, queues или databases.
• Если нужны официальные TikTok app-login scopes или profile APIs, используйте TikTok Developer Platform. В этом flow UnifyPort отвечает за inbound messaging event stream.

FAQ

Нужен ли TikTok developer app для этого flow?

Нет. Подключение аккаунта использует account и QR authorization endpoints UnifyPort. TikTok Login Kit — отдельный путь для app login и scoped access.

Почему первый start response не содержит QR URL?

TikTok provider guide указывает, что initial start response может не содержать QR URL. Продолжайте QR check polling, пока не получите QR material, success или failure.

Подписываться на ["*"] или только на message.received?

Для первого TikTok intake теста используйте message.received. Расширяйте список, когда готовы обрабатывать auth, runtime, receipt и другие события.

Следующий шаг

Откройте вместе TikTok authorization provider guide и Webhook delivery guide. Если еще проектируете очередь, посмотрите TikTok live-DM queue tutorial.

Sources

Official sources checked on 2026-09-03:

• UnifyPort: TikTok authorization
• UnifyPort: Create webhook endpoint
• UnifyPort: Webhook delivery and signature verification
• TikTok for Developers: QR Code Authorization