API SMS-шлюза для кодов подтверждения на ваших номерах

Авторизация

Создайте ключ в панели, в разделе REST API. Он начинается с bsk_live_ и показывается один раз, поэтому храните его как секрет, например в BUSYSMS_API_KEY. Передавайте его в каждом запросе в одном из заголовков:

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

Ключ принадлежит конкретному человеку и видит только его телефоны и номера, которыми с ним поделились. Ключ из панели может читать коды, получать список телефонов и номеров, читать статус аккаунта и будить телефон, поставленный на паузу; удалить устройство или управлять аккаунтом он не может, так что утёкший ключ не изменит ваш счёт. И всё же держите ключи на сервере: любой, у кого есть ключ, может читать ваши коды.

Эндпоинты

Базовый URL — https://busysms.net/api/v1. Запросы — обычные GET, ответы — в JSON.

• GET /codes: самый свежий код по всем вашим номерам. С timeoutMs ждёт следующий, до 90 секунд. Фильтры: service, phone, deviceId.
• GET /devices: ваши телефоны-шлюзы с id, именем, номером, платформой и состоянием (в сети, подтверждён, на паузе), а также номера, которыми с вами поделились.
• GET /numbers: только ваши номера, у каждого — canReceive и, если принимать он не может, reason: unverified, verification_pending, inactive, gateway_off или phone_unreachable.
• GET /devices/:id/messages: последние перехваченные сообщения одного телефона, сначала новые. Принимает service, limit (по умолчанию 50, максимум 200) и since.
• GET /account: ваш аккаунт со статусом пробного периода и подписки.

Ожидание кода: curl, Node.js и Python

Вызов, который нужен большинству интеграций, — long polling сразу после действия, отправляющего SMS. Начните ожидание, запустите вход — и запрос вернётся, как только придёт подходящий код.

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

Порядок важен меньше, чем можно опасаться: код, пришедший примерно за секунду до начала запроса, всё ещё считается новым, а всё, что старше, — нет. В тестах сначала отправляйте запрос, а потом вызывайте SMS; как это сделать в Playwright, Selenium и Cypress, показано в руководстве по автоматизации OTP.

Что возвращается

Каждый ответ /codes имеет одну и ту же структуру (объект message здесь сокращён):

{
  "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, если за отведённое время ничего нового не пришло: во время ожидания API никогда не откатывается к старому коду. receivedAt — время в миллисекундах Unix. service — короткий идентификатор, который BusySMS присваивает каждому сообщению: известный бренд вроде google, telegram или microsoft, а иначе — slug имени отправителя. Передайте его как service=, чтобы ждать код только от этого отправителя.

Ошибки и как их обрабатывать

• 401: ключ отсутствует, имеет неверный формат или отозван. Об отзыве сообщает key_revoked.
• 402 payment_required: пробный период закончился, а действующей подписки нет. Чтение кодов прекращается, но /devices продолжает отвечать, чтобы вы видели, в чём дело, а в теле ответа есть billingUrl.
• 403: устройство принадлежит другому аккаунту или у ключа нет прав на этот маршрут (insufficient_scope).
• 404: такого устройства нет.
• 409 number_unverified: номер этого телефона ещё не подтверждён, поэтому его сообщения читать нельзя.
• 429: превышен лимит запросов. Подождите retryAfterMs и повторите.

Ограничения и полезные практики

• Одно ожидание длится не больше 90 секунд. Если код может идти дольше, повторите запрос с новым таймаутом, а не держите один запрос открытым.
• Если номеров несколько, используйте фильтры: phone= с номером получателя или deviceId= для одного из ваших телефонов — так вы не получите код, предназначенный для другого входа.
• Если в момент начала ожидания ни один ваш телефон не перехватывает коды, BusySMS отправляет на телефон уведомление с просьбой снова включить шлюз. Удалённо перехват он никогда не включает — нажать должен человек.
• Перехваченные сообщения хранятся до 7 дней, затем удаляются.
• Для чтения кодов нужен действующий пробный период или подписка: $5 за подтверждённый номер в месяц после бесплатного пробного периода на 7 дней. Платы за запросы нет.

Не только REST API

Те же коды доступны ИИ-агентам через MCP-сервер BusySMS (см. SMS-коды для ИИ-агентов), а людям — через расширение для Chrome, которое само вводит код на сайте.

Номера, которыми с вами поделились, тоже учитываются. Когда коллега делится кодами номера, /codes возвращает их вместе с вашими, а phone= выделяет именно этот номер.

Вопросы и ответы

Частые вопросы