API de gateway de SMS para códigos de verificação nos seus próprios números

Autenticação

Crie uma chave no painel, em API REST. Ela começa com bsk_live_ e só aparece uma vez, então guarde-a como segredo, por exemplo em BUSYSMS_API_KEY. Envie-a em toda requisição, em qualquer um destes cabeçalhos:

Authorization: Bearer bsk_live_xxxxxxxx
# or
X-API-Key: bsk_live_xxxxxxxx

Uma chave pertence a uma pessoa e só enxerga os celulares dessa pessoa, além dos números compartilhados com ela. Uma chave criada no painel pode ler códigos, listar seus celulares e números, ler o status da sua conta e despertar um celular pausado; ela não pode excluir um dispositivo nem gerenciar a sua conta, então uma chave vazada não consegue mudar o que você paga. Mesmo assim, mantenha as chaves no servidor: quem tiver uma pode ler os seus códigos.

Endpoints

URL base https://busysms.net/api/v1. As requisições são GETs simples e as respostas são JSON.

• GET /codes: o código mais recente entre os seus números. Com timeoutMs, espera o próximo, por até 90 segundos. Filtros: service, phone, deviceId.
• GET /devices: seus celulares gateway com id, nome, número, plataforma e os estados online, verificado e pausado, além dos números compartilhados com você.
• GET /numbers: só os seus números, cada um com canReceive e, quando não pode receber, um reason: unverified, verification_pending, inactive, gateway_off ou phone_unreachable.
• GET /devices/:id/messages: as mensagens capturadas recentemente em um celular, das mais novas para as mais antigas. Aceita service, limit (50 por padrão, no máximo 200) e since.
• GET /account: a sua conta, com o status do teste e da assinatura.

Espere um código: curl, Node.js e Python

A chamada de que a maioria das integrações precisa é um long-poll logo depois de algo disparar um SMS. Comece a espera, dispare o login, e a requisição retorna assim que chega um código correspondente.

curl -s -H "Authorization: Bearer $BUSYSMS_API_KEY" \
  "https://busysms.net/api/v1/codes?service=exampleapp&timeoutMs=60000"

const params = new URLSearchParams({ service: "exampleapp", timeoutMs: "60000" });
const res = await fetch(`https://busysms.net/api/v1/codes?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BUSYSMS_API_KEY}` },
});

if (res.status === 402) throw new Error("Trial over or subscription inactive");
if (!res.ok) throw new Error(`BusySMS ${res.status}: ${await res.text()}`);

const { code, message } = await res.json();
if (code) console.log(`${code} from ${message.sender}`);
else console.log("No new code within 60 seconds");

import os
import requests

r = requests.get(
    "https://busysms.net/api/v1/codes",
    params={"service": "exampleapp", "timeoutMs": 60000},
    headers={"Authorization": f"Bearer {os.environ['BUSYSMS_API_KEY']}"},
    timeout=75,
)
if r.status_code == 402:
    raise RuntimeError("Trial over or subscription inactive")
r.raise_for_status()

data = r.json()
if data["code"]:
    print(data["code"], "from", data["message"]["sender"])
else:
    print("No new code within 60 seconds")

A ordem importa menos do que você talvez tema: um código que chegou até cerca de um segundo antes do início da requisição ainda conta como novo, e qualquer um mais antigo, não. Nos testes, inicie a requisição primeiro e dispare o SMS depois; o guia de automação de OTP mostra como fazer isso no Playwright, no Selenium e no Cypress.

O que volta

Toda resposta de /codes tem o mesmo formato (o objeto message está resumido aqui):

{
  "code": "482913",
  "message": {
    "otpCode": "482913",
    "phone": "+447700900123",
    "sender": "ExampleApp",
    "service": "exampleapp",
    "serviceLabel": "ExampleApp",
    "bodyPreview": "Your ExampleApp verification code is 482913",
    "receivedAt": 1792674000000,
    "deviceName": "Test phone"
  }
}

code é null quando nada de novo chegou a tempo: durante a espera, a API nunca recorre a um código antigo. receivedAt vem em milissegundos desde a epoch. service é um id curto que o BusySMS dá a cada mensagem: uma marca conhecida como google, telegram ou microsoft, ou então um slug do nome do remetente. Passe-o como service= para esperar só o código desse remetente.

Erros e como tratá-los

• 401: a chave está ausente, malformada ou revogada. Uma chave revogada avisa com key_revoked.
• 402 payment_required: o teste acabou e não há assinatura ativa. A leitura de códigos para, mas /devices continua respondendo para você ver o que está errado, e o corpo traz uma billingUrl.
• 403: o dispositivo pertence a outra conta, ou a chave não tem o escopo exigido pela rota (insufficient_scope).
• 404: esse dispositivo não existe.
• 409 number_unverified: o número desse celular ainda não foi verificado, então as mensagens dele não podem ser lidas.
• 429: limite de requisições atingido. Espere retryAfterMs antes de tentar de novo.

Limites e boas práticas

• Uma espera dura no máximo 90 segundos. Se um código pode demorar mais, chame de novo com um novo timeout em vez de manter uma requisição aberta.
• Com vários números, filtre: phone= com o número que recebe, ou deviceId= para um dos seus celulares, para não receber um código destinado a outro login.
• Se nenhum dos seus celulares estiver capturando quando uma espera começar, o BusySMS manda uma notificação para o celular pedindo que o gateway seja ligado de novo. Ele nunca liga a captura remotamente; alguém precisa tocar.
• As mensagens capturadas ficam guardadas por até 7 dias e depois são apagadas.
• Ler códigos exige um teste ou uma assinatura ativos: $5 por número verificado ao mês depois de 7 dias grátis. Não há cobrança por requisição.

Além da API REST

Os mesmos códigos estão disponíveis para agentes de IA pelo servidor MCP do BusySMS (veja códigos SMS para agentes de IA) e para pessoas pela extensão para Chrome, que preenche o código no site por você.

Os números compartilhados com você também entram. Quando um colega compartilha os códigos de um número, /codes os retorna junto com os seus, e phone= seleciona esse número.

Dúvidas

Perguntas frequentes