Руководство September 1, 2026

Что сделать после создания UnifyPort API key: чеклист первого Webhook-теста

После получения первого UnifyPort API key не подключайте messaging account сразу. Более надежная последовательность такая: проверить key через GET /v1/workspace, создать подписанный webhook endpoint, подписаться на message.received или ["*"], сохранять входящие события и только затем авторизовать WhatsApp, Telegram, LINE, TikTok, Zalo или X.

Главное

API key передается в header X-Api-Key; не помещайте его в browser code и не коммитьте в repository.
Полный secret нового key возвращается один раз в поле api_key; последующие list responses показывают только key_prefix.
Webhook нужно создать до account authorization, потому что прогресс авторизации и inbound messages приходят как webhook events.
Включите signing_secret и проверяйте X-Device-Signature по raw request body, прежде чем доверять payload.
Считайте message.received первым production contract, а не временным demo event.

Если у вас уже есть live key и его нужно заменить, используйте отдельный zero-downtime API key rotation runbook. Если вы только проектируете inbound architecture, прочитайте также webhook-first integration checklist.

1. Проверьте, к какому workspace относится key

UnifyPort сейчас доступен выбранным клиентам; публичная документация рекомендует обратиться к команде, чтобы получить workspace access и первый API key. Первый request после получения key должен быть read-only workspace check, а не отправка сообщения.

export UNIFYPORT_API_KEY="set-this-in-your-secret-manager"

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

Успешный response подтверждает, что key указывает на один workspace. Introduction docs также описывает, что все /v1 endpoints используют request header X-Api-Key, а JSON success/error responses содержат top-level request_id для поддержки и сверки.

2. Создайте именованный key и сохраните полный secret один раз

Если workspace позволяет создавать дополнительные keys, используйте имя, которое показывает назначение runtime. Например, production inbound worker. Create API key reference документирует форму response: запись key возвращается в key, а полный secret один раз возвращается в api_key.

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production inbound worker",
    "prefix": "dk_live"
  }'

Практическое правило: сразу сохраните полученный api_key в secrets manager и не вставляйте его в issue, chat log или client-side environment variable. Официальный OWASP Secrets Management Cheat Sheet также относит API keys к secrets и рассматривает создание, хранение, rotation, revocation и auditing как единый жизненный цикл.

3. Зарегистрируйте webhook до подключения account

Сделайте это до QR, code или session authorization. UnifyPort не гарантирует полный replay для пропущенных webhook deliveries, поэтому постоянной записью inbound traffic должны быть ваш receiver и database.

export WEBHOOK_SIGNING_SECRET="generate-a-long-random-secret"

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/webhook",
    "status": "active",
    "subscribed_events": ["message.received"],
    "signing_secret": "'"$WEBHOOK_SIGNING_SECRET"'"
  }'

Create webhook endpoint reference допускает точные public standard event names или ["*"] для всех public standard events. Используйте ["*"], если строите полный account state machine; используйте message.received, если первый milestone — прием входящих сообщений клиентов.

4. Проверяйте webhook signature по raw body

Delivery docs определяют важные headers: X-Device-Event-Id, X-Device-Delivery-Id, X-Device-Timestamp и X-Device-Signature. Signature — это hex-encoded HMAC-SHA256 от строки:

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

Критически важно использовать raw body. Если framework сначала parse JSON, а затем serialize его заново, bytes могут измениться и signature verification завершится ошибкой.

import crypto from 'crypto';
import express from 'express';

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

app.post('/unifyport/webhook', 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');

  const valid = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!valid) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8'));
  if (event.type === 'message.received') {
    console.log(event.provider, event.data.conversation.id, event.data.message.text);
  }

  res.status(200).end();
});

Подробности — в Webhook delivery & signature verification. Там же описаны retries, idempotency, проверка stale timestamp и правило, что любой 2xx response подтверждает delivery.

5. Сохраните envelope `message.received` как первый contract

Обычное inbound message приходит со стабильным envelope: id, type, provider, account_id, occurred_at и data. standard event payload reference показывает поля, вокруг которых стоит строить модель:

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "telegram",
  "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": "Здравствуйте, заказ уже отправлен?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:34:55Z"
    }
  }
}

Сохраняйте top-level event id для idempotency, provider и account_id для routing, data.conversation.id для grouping в очереди, data.sender.id для identity и data.message.id для message-level actions. После этого один receiver может принимать Telegram или WhatsApp сейчас и позже добавить LINE, Zalo, TikTok или X. Если хотите увидеть вариант с AI coding agent, посмотрите AI coding agent auto-reply bot tutorial.

Типичные ошибки первого дня

Ошибка	Почему это плохо	Более безопасный вариант
Сначала создать account	Auth events могут прийти до готовности receiver	Сначала создать webhook endpoint
Отключить signing	Любой, кто знает URL, может отправить похожий JSON	Задать `signing_secret` и проверять raw-body HMAC
Дедуплицировать только delivery attempt	Retry может отправить тот же event повторно	Дедуплицировать по `X-Device-Event-Id` или event `id`
Писать API key в logs	Secrets распространяются в системы, которые сложно аудитить	Хранить key в secrets manager и редактировать logs
Считать `message.received` только WhatsApp-событием	Это normalized event для поддерживаемых providers	Сохранять provider/account fields, а не предположения одной platform

FAQ

Можно ли позже получить полный API key?

Нет. Create response возвращает полный secret один раз в поле api_key. List и detail responses показывают безопасные метаданные, например key_prefix, но не полный secret.

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

Для узкого первого inbound test используйте message.received. Если один receiver должен обрабатывать auth, runtime, message, receipt, conversation или group events, используйте ["*"].

Нужен ли webhook endpoint до создания account?

Для надежного первого запуска — да. Account authorization progress и live inbound messages доставляются как webhook events, а UnifyPort не обещает полный replay пропущенных payloads.

Нужен ли официальный business account на каждой platform?

Нет. UnifyPort предоставляет неофициальный интерфейс для WhatsApp, Telegram, LINE, TikTok, Zalo и X и может работать с personal или ordinary messaging accounts там, где такая модель подходит задаче.

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

Откройте Quickstart, сохраните API key в secrets manager, сначала создайте webhook endpoint и держите delivery verification docs рядом с реализацией receiver.

Sources checked on 2026-09-01

UnifyPort API

Превратите интеграцию сообщений в стабильный продуктовый pipeline.

Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.

Получить API Key Открыть справочник API