Recevez les SMS sur un vrai numéro américain, directement dans votre code.

Pourquoi pas un numéro de plateforme télécom ?

Les numéros programmables des plateformes télécom sont le plus souvent classés comme VoIP. L'article de Twilio sur le filtrage de la VoIP avant l'envoi des codes montre son Lookup marquant un numéro Twilio comme nonFixedVoip (Twilio). Si un service filtre la VoIP, son code n'arrivera jamais sur un numéro de plateforme. Une ligne Cleat est une ligne mobile. C'est toute la raison d'en prendre une. En savoir plus sur les types de ligne.

Démarrage rapide

1. 01Prenez une ligne. Créez un compte et abonnez-vous. Lister vos lignes fonctionne tout de suite ; lire les messages d'une ligne répond 403 jusqu'à ce que le titulaire du compte ait vérifié son identité.
2. 02Créez une clé API dans les Réglages. Elle commence par clt_ et n'est affichée qu'une fois.
3. 03Ajoutez un endpoint de webhook dans les Réglages, si vous voulez les push : une URL HTTPS publique. Son secret de signature commence par whsec_ et n'est affiché qu'une fois.
4. 04Listez vos lignes, puis interrogez les SMS ou attendez les webhooks.

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"
    }
  ]
}

Webhooks

Quand un SMS arrive, Cleat envoie un POST à chacun de vos endpoints avec ce corps JSON, un header cleat-signature et le 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"
  }
}

Le header de signature ressemble à t=1789120961,v1=5d41…. v1 est le HMAC-SHA256 en hexadécimal du timestamp, d'un point et du corps brut, avec pour clé le secret de signature de l'endpoint. Vérifiez-le sur les octets bruts avant de les parser. Refusez les timestamps anciens pour bloquer les rejeux.

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);

Détails de livraison

• Les endpoints doivent être des URL https:// publiques. Cleat ne suit pas les redirections.
• Répondez avec n'importe quel statut 2xx en moins de 10 secondes.
• La livraison est au moins une fois. Si elle échoue ou expire, elle est retentée : cinq tentatives en tout, la première tout de suite puis après 30 secondes, 2 minutes, 10 minutes et une heure, avec les mêmes octets et une signature fraîche. Rendez votre handler idempotent sur data.id ; l'id d'un SMS ne change jamais. Les Réglages conservent chaque tentative et permettent de rejouer n'importe quelle livraison.
• Si les cinq tentatives échouent, rattrapez le retard via l'API avec ?after= et le receivedAt du dernier SMS traité.
• Rien n'est envoyé tant qu'une ligne est suspendue ou que son titulaire n'a pas vérifié son identité. Ces SMS sont conservés et lisibles dès que la cause disparaît, mais aucun webhook n'est envoyé pour eux ensuite : lisez-les avec ?after=.
• Jusqu'à cinq endpoints par espace de travail. Les Réglages affichent le dernier statut de chaque endpoint et le nombre de livraisons échouées d'affilée.
• type vaut message.received, ou test pour la livraison d'essai déclenchée depuis les Réglages : même data, avec ses propres ids. Répondez 200 à un type que vous ne connaissez pas ; d'autres pourront s'ajouter.
• Collez un webhook entrant Slack ou un lien de workflow Microsoft Teams au lieu de votre URL et cet endpoint reçoit le format de message de cette app, sans cleat-signature : avec une app de chat, il n'y a pas de secret partagé.
• code est la meilleure hypothèse de Cleat sur le code à usage unique, ou null. Le body complet est toujours là.
• label dit de qui vient le SMS, en clair : un contact enregistré par votre équipe, sinon le service reconnu par Cleat d'après le texte, avec contact et service derrière. Les trois valent null en cas de doute. Ils ont été ajoutés après coup et n'enlèvent rien : from, body et code sont inchangés.
• Un code dicté lors d'un appel automatique arrive de la même façon. L'appel est transcrit et livré comme un message.received, avec la transcription dans body, le numéro appelant dans from et code rempli. Rien dans le payload n'indique qu'une livraison venait d'un appel plutôt que d'un SMS.

Référence de l'API

Limites et permissions

120 requêtes par minute et par clé API ; au-delà, l'API répond 429, sans en-tête Retry-After : le backoff est à vous. Seul le propriétaire de l'espace de travail peut créer des clés API et des endpoints de webhook, et une clé révoquée cesse de fonctionner immédiatement. Une clé peut aussi être restreinte à sa création : à des lignes nommées et à une date d'expiration — c'est ce qui permet de la confier à un agent, à un job de CI ou à un prestataire. Une ligne hors de la portée répond 404, et une clé expirée répond 401 avec code key_expired.

Les usages qui conviennent

• Les comptes de votre propre entreprise : consoles cloud, bureaux d'enregistrement, prestataires de paiement, avec les codes publiés sur un canal que votre ingénieur d'astreinte surveille.
• Le staging et le QA de vos propres parcours d'inscription et de connexion, face à un numéro qui se comporte comme le téléphone d'un client.
• Les projets personnels qui ont besoin d'un numéro mobile américain au dossier.

Les usages qui ne conviennent pas

• Envoyer des SMS. Cleat Line est en réception seule : elle ne peut ni envoyer de SMS, ni passer d'appel, ni joindre le 911.
• Les tests de charge ou les parcs de numéros. Chaque ligne est un abonnement distinct avec un titulaire vérifié. Cleat n'est pas fait pour gérer beaucoup de numéros.
• Les comptes qui ne sont ni les vôtres ni ceux de votre entreprise.
• Tout ce qui demande de la voix en direct. L'API ne peut pas appeler. Il n'y a pas de sonnerie à décrocher, pas d'audio à diffuser, pas d'enregistrement à récupérer. Vous avez la transcription d'un appel une fois qu'il est terminé. Les appels de Cleat Full se prennent et se passent dans l'appli web, pas via l'API.

Comparatif

Vous partagez des codes avec des personnes qui ne codent pas ? Voir la 2FA partagée pour les équipes. Pourquoi Google Voice et les autres numéros internet ratent des codes : Google Voice et les codes de vérification. Comment nous traitons l'identité : confiance et sécurité. Les règles de facturation complètes : tarif.