Receba SMS num número americano de verdade, direto no seu código.

Por que não um número de plataforma de telecom?

Números programáveis de plataformas de telecom costumam ser classificados como VoIP. O próprio texto da Twilio sobre filtrar VoIP antes de mandar códigos mostra o Lookup dela marcando um número da Twilio como nonFixedVoip (Twilio). Se um serviço filtra VoIP, o código dele nunca chega num número de plataforma. Uma linha Cleat é uma linha móvel. É essa a razão de usar uma. Mais sobre tipos de linha.

Primeiros passos

1. 01Pegue uma linha. Crie a conta e assine. Listar suas linhas funciona na hora; ler as mensagens de uma linha responde 403 até o dono da conta verificar a identidade.
2. 02Crie uma API key em Configurações. Ela começa com clt_ e aparece uma vez só.
3. 03Adicione um endpoint de webhook em Configurações, se quiser receber pushes: uma URL HTTPS pública. O segredo de assinatura começa com whsec_ e aparece uma vez só.
4. 04Liste suas linhas e depois consulte os SMS ou espere os 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

Quando um SMS chega, a Cleat manda um POST para cada um dos seus endpoints com este corpo JSON, um header cleat-signature e o 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"
  }
}

O header de assinatura fica assim: t=1789120961,v1=5d41…. v1 é o HMAC-SHA256 em hexadecimal do timestamp, de um ponto e do corpo cru, com a chave do segredo de assinatura do endpoint. Confira contra os bytes crus antes de fazer o parse. Recuse timestamps antigos para bloquear reenvios.

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

Detalhes da entrega

• Os endpoints precisam ser URLs https:// públicas. A Cleat não segue redirecionamentos.
• Responda com qualquer status 2xx em até 10 segundos.
• A entrega é pelo menos uma vez. Se uma falha ou estoura o tempo, ela é tentada de novo: cinco tentativas no total, a primeira na hora e depois com 30 segundos, 2 minutos, 10 minutos e uma hora, mandando os mesmos bytes com uma assinatura nova. Faça o seu handler ser idempotente no data.id; o id de um SMS nunca muda. Configurações guarda cada tentativa e pode reenviar qualquer entrega.
• Se as cinco tentativas falharem, se atualize pela API com ?after= e o receivedAt do último SMS que você tratou.
• Enquanto a linha está suspensa ou o dono dela não verificou a identidade, nada é enviado. Esses SMS ficam guardados e podem ser lidos assim que o motivo se resolve, mas nenhum webhook é mandado por eles depois: leia com ?after=.
• Até cinco endpoints por espaço de trabalho. Configurações mostra o último status de cada endpoint e quantas entregas seguidas falharam.
• type é message.received, ou test para a entrega de teste que você dispara em Configurações: o mesmo data, com ids próprios. Responda 200 a um tipo que você não conhece; outros podem aparecer.
• Se em vez da sua URL você colar um webhook de entrada do Slack ou um link de workflow do Microsoft Teams, aquele endpoint recebe o formato de mensagem do próprio app e sem cleat-signature: com um app de chat não existe segredo compartilhado.
• code é o melhor palpite da Cleat para o código de uso único, ou null. O body completo está sempre lá.
• label diz de quem é o SMS em palavras: um contato que a sua equipe salvou ou, senão, o serviço que o Cleat reconheceu pelo que o SMS diz, com contact e service por trás. Os três vêm null quando não dá para ter certeza. Foram adicionados depois e não tiram nada: from, body e code continuam iguais.
• Um código ditado numa ligação automática chega do mesmo jeito. A ligação é transcrita e entregue como um message.received, com a transcrição em body, o número que ligou em from e o code preenchido. Nada no payload indica que a entrega foi uma ligação em vez de um SMS.

Referência da API

Limites e permissões

120 requisições por minuto por API key; passou disso, a API responde 429, sem cabeçalho Retry-After, então o backoff é seu. Só o dono do espaço de trabalho cria API keys e endpoints de webhook, e uma chave revogada para de funcionar na hora. Você também pode limitar uma chave na criação: a linhas específicas e a uma data em que ela deixa de valer, o que é o que torna seguro entregá-la a um agente, a um job de CI ou a um terceiro. Uma linha fora do escopo responde 404, e uma chave expirada responde 401 com code key_expired.

Casos que encaixam

• As contas da sua própria empresa, como consoles de nuvem, registros de domínio e gateways de pagamento, com os códigos indo para um canal que a pessoa de plantão acompanha.
• Staging e QA dos seus próprios fluxos de cadastro e login, contra um número que se comporta como o celular de um cliente.
• Projetos pessoais que precisam de um número de celular americano no cadastro.

Casos que não encaixam

• Enviar SMS. A Cleat Line só recebe: não envia mensagens, não faz chamadas e não liga para o 911.
• Teste de carga ou pilhas de números. Cada linha é uma assinatura separada, com um dono verificado. A Cleat não foi feita para ter muitos números.
• Contas que não são suas nem da sua empresa.
• Qualquer coisa que precise de voz ao vivo. A API não liga para fora. Não tem chamada para atender, áudio para transmitir nem gravação para baixar. Só a transcrição de uma ligação depois que ela acabou. As ligações da Cleat Full são atendidas e feitas no app web, não pela API.

Como se compara

Precisa dividir códigos com gente que não programa? Veja 2FA compartilhado para equipes. Por que o Google Voice e outros números de internet perdem códigos: Google Voice e os códigos de verificação. Como tratamos identidade: confiança e segurança. As regras de cobrança: preço.