SMS на настоящий номер США — прямо в ваш код.

Почему не номер телеком-платформы?

Программируемые номера телеком-платформ обычно классифицируются как VoIP. В статье самой Twilio о фильтрации VoIP перед отправкой кодов её Lookup помечает номер Twilio как nonFixedVoip (Twilio). Если сервис фильтрует VoIP, его код до номера платформы не дойдёт. Линия Cleat — мобильная. В этом и весь смысл. Подробнее о типах номеров.

Быстрый старт

1. 01Получите линию. Зарегистрируйтесь и оформите подписку. Список линий доступен сразу; чтение SMS на линии отвечает 403, пока владелец аккаунта не подтвердит личность.
2. 02Создайте API-ключ в разделе Settings. Он начинается с clt_ и показывается один раз. Если удобнее сгенерировать клиент, весь контракт API описан в OpenAPI.
3. 03Добавьте эндпоинт вебхука в разделе Settings, если нужны push-уведомления: публичный HTTPS-адрес. Его секрет подписи начинается с whsec_ и показывается один раз.
4. 04Получите список линий, затем опрашивайте API или ждите вебхуков.

curl https://cleat.so/api/v1/lines \
  -H "Authorization: Bearer $CLEAT_API_KEY"

{
  "data": [
    {
      "id": "8f14e45f-ceea-4b6b-9d3c-2a1f0e7c5b10",
      "phone": "13055550100",
      "label": "Staging sign-ups",
      "status": "active",
      "createdAt": "2026-09-11T10:00:00.000Z"
    }
  ]
}

curl "https://cleat.so/api/v1/lines/$LINE_ID/messages?after=2026-09-11T10:00:00Z&limit=50" \
  -H "Authorization: Bearer $CLEAT_API_KEY"

{
  "data": [
    {
      "id": "c9a7e0d2-5b1f-4e8a-9f3c-6d2b1a0e4f77",
      "line": { "id": "8f14e45f-ceea-4b6b-9d3c-2a1f0e7c5b10", "phone": "13055550100", "label": "Staging sign-ups" },
      "from": "32665",
      "body": "704118 is your Facebook confirmation code",
      "code": "704118",
      "receivedAt": "2026-09-11T10:02:41.000Z",
      "service": { "id": "facebook", "name": "Facebook", "color": "#0866FF" },
      "contact": null,
      "label": "Facebook"
    }
  ]
}

Вебхуки

Когда приходит SMS, Cleat отправляет POST на каждый ваш эндпоинт с таким JSON-телом, заголовком cleat-signature и User-Agent Cleat-Webhooks/1.0:

{
  "type": "message.received",
  "data": {
    "id": "c9a7e0d2-5b1f-4e8a-9f3c-6d2b1a0e4f77",
    "line": { "id": "8f14e45f-ceea-4b6b-9d3c-2a1f0e7c5b10", "phone": "13055550100", "label": "Staging sign-ups" },
    "from": "32665",
    "body": "704118 is your Facebook confirmation code",
    "code": "704118",
    "receivedAt": "2026-09-11T10:02:41.000Z",
    "service": { "id": "facebook", "name": "Facebook", "color": "#0866FF" },
    "contact": null,
    "label": "Facebook"
  }
}

Заголовок подписи выглядит так: t=1789120961,v1=5d41…. v1 — HMAC-SHA256 в шестнадцатеричном виде от метки времени, точки и сырого тела запроса; ключ — секрет подписи эндпоинта. Проверяйте подпись по сырым байтам, до разбора тела. Отклоняйте старые метки времени, чтобы защититься от повторной отправки.

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.CLEAT_WEBHOOK_SECRET; // whsec_…

// cleat-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">
function verified(header, body) {
  const parts = Object.fromEntries(String(header).split(",").map((part) => part.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && parts.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

app.post("/cleat-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  if (!verified(req.get("cleat-signature"), body)) return res.sendStatus(401);

  const { type, data } = JSON.parse(body);
  if (type === "message.received") {
    // data.code is Cleat's best guess at a one-time code; data.body is the full text.
    console.log(data.line.phone, data.from, data.code ?? data.body);
  }
  res.sendStatus(200);
});

app.listen(3000);

Как работает доставка

• Эндпоинты должны быть публичными адресами https://. Cleat не переходит по редиректам.
• Ответьте любым статусом 2xx в течение 10 секунд.
• Доставка выполняется не менее одного раза. Неудачную или истёкшую по времени доставку повторяем: всего пять попыток — сразу, затем через 30 секунд, 2 минуты, 10 минут и час, — каждая отправляет те же байты с новой подписью. Сделайте обработчик идемпотентным по data.id; id сообщения никогда не меняется. В разделе Settings сохраняется каждая попытка, и любую доставку можно отправить повторно.
• Если все пять попыток не удались, заберите пропущенное через API: ?after= и receivedAt последнего обработанного SMS.
• Пока линия приостановлена или её владелец не подтвердил личность, не отправляется ничего. Такие SMS сохраняются и становятся доступны сразу после снятия причины, но вебхук по ним потом не уходит — читайте их через ?after=.
• До пяти эндпоинтов на рабочее пространство. В разделе Settings видно последний статус каждого эндпоинта и сколько доставок подряд не удалось.
• type — это message.received, а для тестовой доставки из Settings — test: та же структура data, но со своими id. На незнакомый тип отвечайте 200: могут появиться новые.
• Если вместо своего адреса вставить входящий webhook Slack или ссылку на workflow Microsoft Teams, такой эндпоинт получит формат сообщений самого мессенджера и без cleat-signature: общего секрета с мессенджером нет.
• code — одноразовый код, который Cleat счёл наиболее вероятным, или null. Полный body есть всегда.
• label словами говорит, от кого SMS: контакт, сохранённый вашей командой, иначе сервис, который Cleat распознал по тексту; за ними стоят contact и service. Все три равны null, когда уверенности нет. Поля добавлены позже и ничего не убирают: from, body и code прежние.
• Код, продиктованный в автоматическом звонке, приходит так же. Звонок расшифровывается и доставляется как message.received: расшифровка в body, номер звонившего в from, code заполнен. Ничто в теле запроса не отличает звонок от SMS.

Справочник API

Ограничения и права

120 запросов в минуту на один API-ключ; сверх этого API отвечает 429 — без заголовка Retry-After, так что задержку выбираете вы сами. Создавать API-ключи и эндпоинты вебхуков может только владелец рабочего пространства, а отозванный ключ перестаёт работать сразу. Ключ можно и сузить при создании: до конкретных линий и до даты, когда он перестанет работать, — именно это позволяет отдать его агенту, CI-задаче или подрядчику. Линия вне области действия отвечает 404, а истёкший ключ — 401 с code key_expired.

Для чего подходит

• Аккаунты вашей компании: облачные консоли, регистраторы доменов, платёжные сервисы. Коды приходят в канал, который читает дежурный инженер.
• Тестирование ваших собственных сценариев регистрации и входа в тестовой среде и QA — на номере, который ведёт себя как телефон клиента.
• Личные проекты, где нужно указать мобильный номер США.

Для чего не подходит

• Отправка SMS. Cleat Line работает только на приём: не отправляет SMS, не звонит и не набирает 911.
• Нагрузочное тестирование или пулы номеров. Каждая линия — отдельная подписка со своим проверенным владельцем. Cleat не рассчитан на пулы номеров.
• Аккаунты, которые не принадлежат вам или вашей компании.
• Всё, что требует живого голоса. Через API нельзя позвонить. Звонок нельзя принять, аудиопотока нет, записи для скачивания тоже. Расшифровку звонка вы получаете после его окончания. Звонки Cleat Full принимают и совершают в веб-приложении, а не через API.

Сравнение

Нужно делиться кодами с коллегами, которые не пишут код? Смотрите общий номер для 2FA в команде. Почему Google Voice и другие интернет-номера не получают коды: Google Voice и коды подтверждения. Как мы проверяем личность: доверие и безопасность. Все правила оплаты: цены.

Читайте также

SMS в Telegram