Первый запрос
Проверьте, что ключ работает и привязан к пользователю. Это лучший старт до покупки номера.
curl -X GET "https://api.hush-sms.com/v1/me" \ -H "Authorization: Bearer <api_key>"
Hush SMS · API
REST API для каталога, покупки виртуальных номеров, проверки статуса и безопасной работы через идемпотентные запросы.
Проверьте, что ключ работает и привязан к пользователю. Это лучший старт до покупки номера.
curl -X GET "https://api.hush-sms.com/v1/me" \ -H "Authorization: Bearer <api_key>"
Для создания заказа обязателен Idempotency-Key. Повтор с тем же ключом защищает от двойной покупки.
curl -X POST "https://api.hush-sms.com/v1/numbers" \
-H "Authorization: Bearer <api_key>" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{"service":"tg","country":0}'
order_id.Такой порядок запросов покрывает основной поток интеграции: от выбора сервиса до статуса и отмены.
Сначала запросите GET /v1/me, чтобы убедиться, что ключ активен, а баланс и профиль читаются корректно.
Получите сервисы через GET /v1/services, затем страны и цены через GET /v1/services/{code}/countries.
Вызовите POST /v1/numbers с Idempotency-Key. Это защищает от повторной покупки при ретраях.
Используйте GET /v1/numbers/{order_id} и GET /v1/numbers для получения активных заказов и SMS-кодов.
Webhook настраивается в Telegram-боте: Информация → API → Webhooks. Сейчас отправляется только одно событие: когда по заказу пришла SMS.
POST с простым JSON-телом для события получения SMS.2xx как подтверждение успешной обработки.2xx только после успешного приёма.POST https://your-app.example/webhooks/hush
Content-Type: application/json
{
"action": "postWebhook",
"sms_content": "Your code: 482913",
"sender_number": "",
"recipient_number": "+447700900123",
"activation_id": "66173a6d8a5f0f36e4a1c123",
"service": "tg",
"country": "0",
"status": "sms_received",
"test": false,
"received_at": "2026-04-09T12:34:56Z"
}
sms_content — текст SMS, если провайдер отдаёт только код, сюда приходит код.recipient_number — купленный виртуальный номер.activation_id — ID заказа в Hush SMS, его удобно связывать с вашим заказом.test — true только у тестового webhook из бота.sender_number может быть пустым, если upstream не передал номер отправителя.Кнопка Тестовый webhook отправляет такой же POST, но с test: true, тестовым номером и демонстрационным кодом 123456.
{
"action": "postWebhook",
"sms_content": "123456",
"sender_number": "Hush SMS",
"recipient_number": "+10000000000",
"activation_id": "test-webhook",
"service": "tg",
"country": "0",
"status": "sms_received",
"test": true,
"received_at": "2026-04-09T12:34:56Z"
}
Эти коды встречаются чаще всего и на них обычно нужно опираться в клиентской логике.
| Код | Когда возникает |
|---|---|
missing_token | Не передан API-ключ в заголовке Authorization. |
forbidden | Ключ невалиден, неактивен или не привязан к пользователю. |
not_available | Для выбранного сервиса и страны сейчас нет офферов. |
missing_idempotency_key | При покупке номера не передан Idempotency-Key. |
too_early | Отмена запрошена раньше допустимого времени после создания заказа. |
upstream_timeout | Внешний провайдер не успел ответить вовремя. |
| Статус | Значение |
|---|---|
pending | Заказ создан, номер выдан, SMS ещё не получена. |
sms_received | Хотя бы одна SMS уже доступна в заказе. |
finished | Работа с заказом завершена. |
canceled | Заказ отменён, номер освобождён. |
refunded | Средства были возвращены пользователю. |
Ниже находится полный интерактивный reference по всем endpoint’ам, параметрам, схемам и примерам ответов.
Внутренний код для запроса (service) — понятное название сервиса. Используется в POST /v1/numbers и GET /v1/services/{code}/countries.
Числовой ID страны (country) для покупки номера. Название на английском — название на русском.