Подтверждение номера через мессенджеры

01 · Готовые примеры

Скопируйте интеграцию для вашего языка

type Json = Record<string, unknown>;
type MessengerLink = { messenger: "telegram" | "max" | "whatsapp"; title: string; bot_id: string; link: string; image: string; color: string; qr_code: string };
type Challenge = { id: string; authorization_url: string; qr_code: string; fallbackCode: string; links: MessengerLink[] };
type Status = { status: "created" | "opened" | "confirmed" | "rejected" | "expired" | "consumed"; messenger: "telegram" | "max" | "whatsapp" | null; reason?: string; resolvedAt: string | null };
type Proof = { proof: { expectedPhone: string; reportedPhone: string | null; phonesMatch: boolean; phoneVerified: boolean } };

const apiUrl = "https://confirmator.ru";
const apiKey = process.env.CONFIRMATOR_API_KEY;
if (!apiKey) throw new Error("CONFIRMATOR_API_KEY is required");

async function call<T>(path: string, init: RequestInit = {}): Promise<T> {
  const response = await fetch(apiUrl + path, {
    ...init,
    headers: { authorization: "Bearer " + apiKey, "content-type": "application/json", ...init.headers },
  });
  const body = await response.json() as Json;
  if (!response.ok) throw new Error(String((body.error as Json | undefined)?.code ?? response.status));
  return body as unknown as T;
}

const challenge = await call<Challenge>("/v1/challenges", {
  method: "POST",
  body: JSON.stringify({ phone: "+79991234567", purpose: "login", deliveryMode: "polling" }),
});
console.log("Send the user to", challenge.authorization_url);

let status: Status;
do {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  status = await call<Status>("/v1/challenges/" + challenge.id + "/status");
} while (status.status === "created" || status.status === "opened");

if (status.status !== "confirmed" && status.status !== "rejected") throw new Error("Challenge expired");

const result = await call<Proof>("/v1/challenges/" + challenge.id + "/consume", {
  method: "POST",
  headers: { "idempotency-key": crypto.randomUUID() },
});
if (result.proof.phoneVerified) console.log("Phone confirmed");

02 · Быстрый старт

Три запроса до результата

1. Создайте проектЗарегистрируйтесь, пополните баланс, включите Telegram, MAX и/или WhatsApp и выпустите API-ключ.
2. Создайте challengeПередайте ожидаемый номер с backend вашего приложения и покажите пользователю authorization_url.
3. Получите proofИспользуйте polling или подписанный webhook и создайте пользовательскую сессию только при phoneVerified: true.

03 · Авторизация

Bearer API key

Каждый запрос к `/v1` требует ключ проекта в заголовке:

Authorization: Bearer confirmator_test_<prefix>.<secret>

Полный ключ показывается один раз. Храните его в secret storage или переменной окружения.

04 · REST API

Жизненный цикл challenge

Если пользователь не завершил проверку за 30–180 секунд, API возвращает вычисляемый статус expired. consumed означает, что proof уже был получен server-to-server запросом.

05 · Webhook

Подписанная доставка

Для webhook-режима создайте secret в настройках проекта, добавьте callback origin и передайте deliveryMode: "webhook". Ответ 2xx подтверждает доставку. При ошибке выполняется до пяти попыток примерно на 0-й, 10-й, 40-й, 100-й и 160-й секундах; после трёх минут доставка прекращается.

x-confirmator-event-id: whd_...
x-confirmator-timestamp: 1784090000
x-confirmator-signature: v1=<hex-hmac-sha256>

Строка подписи: HMAC_SHA256(secret, timestamp + "." + rawBody). Проверяйте подпись по исходному телу до JSON parsing и отклоняйте слишком старый timestamp.

{
  "id": "whd_...",
  "type": "challenge.completed",
  "createdAt": "2026-07-15T12:01:17Z",
  "data": {
    "challengeId": "ch_...",
    "projectId": "prj_...",
    "status": "confirmed",
    "externalUserRef": "user-4815",
    "purpose": "login",
    "proof": {
      "type": "phone",
      "messenger": "telegram",
      "method": "shared_contact",
      "expectedPhone": "+79991234567",
      "reportedPhone": "+79991234567",
      "phonesMatch": true,
      "phoneVerified": true
    },
    "resolvedAt": "2026-07-15T12:01:17Z"
  }
}

Каждый пример ниже показывает полный цикл на backend заказчика: endpoint POST /login отправляет запрос создания challenge в Confirmator, а POST /webhooks/confirmator принимает и проверяет результат. Задайте CONFIRMATOR_API_KEY, CONFIRMATOR_WEBHOOK_SECRET и публичный HTTPS URL callback в CONFIRMATOR_WEBHOOK_URL.

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secret = process.env.CONFIRMATOR_WEBHOOK_SECRET;
const apiKey = process.env.CONFIRMATOR_API_KEY;
const webhookUrl = process.env.CONFIRMATOR_WEBHOOK_URL;
if (!secret || !apiKey || !webhookUrl) throw new Error("Confirmator environment variables are required");

app.post("/login", express.json({ limit: "4kb" }), async (request, response) => {
  const apiResponse = await fetch("https://confirmator.ru/v1/challenges", {
    method: "POST",
    headers: { Authorization: "Bearer " + apiKey, "Content-Type": "application/json" },
    body: JSON.stringify({
      phone: request.body.phone,
      purpose: "login",
      deliveryMode: "webhook",
      webhookUrl,
    }),
  });
  const result = await apiResponse.json();
  return response.status(apiResponse.status).json(result);
});

app.post("/webhooks/confirmator", express.raw({ type: "application/json", limit: "32kb" }), (request, response) => {
  const timestamp = request.header("x-confirmator-timestamp") ?? "";
  const signature = request.header("x-confirmator-signature") ?? "";
  const eventId = request.header("x-confirmator-event-id") ?? "";
  const rawBody = request.body as Buffer;

  const timestampMs = Number(timestamp) * 1000;
  if (!Number.isFinite(timestampMs) || Math.abs(Date.now() - timestampMs) > 5 * 60_000) {
    return response.status(401).end();
  }

  const expected = "v1=" + createHmac("sha256", secret)
    .update(timestamp + ".")
    .update(rawBody)
    .digest("hex");
  const actualBuffer = Buffer.from(signature);
  const expectedBuffer = Buffer.from(expected);
  if (actualBuffer.length !== expectedBuffer.length || !timingSafeEqual(actualBuffer, expectedBuffer)) {
    return response.status(401).end();
  }

  const event = JSON.parse(rawBody.toString("utf8"));
  // Сначала атомарно сохраните eventId в БД с уникальным индексом.
  // Повтор уже обработанного eventId должен также получить 204.
  if (event.data?.proof?.phoneVerified === true) {
    // Создайте сессию именно вашего приложения.
  }
  return response.status(204).end();
});

app.listen(8080);

Все webhook-заголовки используют единый префикс x-confirmator-*. Сначала атомарно дедуплицируйте событие по x-confirmator-event-id, затем обрабатывайте data.proof. Повтор уже принятого события также должен получить 2xx.

06 · Ошибки

Единый формат

{
  "error": {
    "code": "invalid_phone",
    "message": "Invalid phone",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}