Подключите отправку SMS
к своему сервису.

Быстрый старт

1. Создайте API KEY

   После регистрации, одобрения и входа с OTP откройте раздел Управление API-ключами, чтобы выпустить ключ.

2. Подготовьте кредиты

   Используются кредиты и тариф вашего аккаунта. Сумма списывается при приёме отправки.

3. Отправьте сообщения и проверьте результат

   Сохраните ID отправки и проверяйте результат через API статуса.

Покрытие

GET/api/v1/messages/countries

Проверяйте активные страны и применяемые тарифы через API. В запросе на отправку укажите страну в country и передавайте в одном запросе номера только этой страны. Для стран без заданного тарифа отправки не принимаются.

{ "currency": "USDT", "countries": [{ "country": "US", "unitPrice": 0.02 }] }

Аутентификация по API KEY

Добавляйте этот заголовок во все запросы к внешнему API. Cookie входа и коды OTP не нужны.

Authorization: Bearer hex_live_ВАШ_КЛЮЧ

Полный ключ показывается только один раз при выпуске. Храните его в переменной окружения на сервере и не добавляйте во фронтенд-код. Отозванный ключ или ключ заблокированного аккаунта использовать нельзя. Можно создать до 5 ключей.

Отправляйте на 1000 номеров за раз

Отправьте один текст на множество номеров. Запрос проверяется, ставится в очередь отправки, и ответ приходит сразу. Чтобы отправить разным номерам разный текст, используйте отдельные запросы с новым Idempotency-Key.

Если хотя бы один номер неверен или повторяется, отклоняется весь запрос — без отправки и списания. Дубликаты проверяются после приведения номеров к международному формату.

curl -X POST 'https://hexsms.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: notice-20261024-001' \
  -d '{
    "country": "US",
    "text": "Your verification code is 482913.",
    "recipients": ["+12025550123", "+12025550124"]
  }'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "RUNNING",
  "total": 2,
  "segments": 1,
  "unitPrice": 0.025,
  "cost": 0.05,
  "createdAt": 1792800000000,
  "note": null,
  "replayed": false
}

Как рассчитывается стоимость

Число номеров × число сегментов (segments) × тариф аккаунта — так рассчитывается стоимость. Для символов UCS-2 один сегмент вмещает 70 символов, далее — по 67. Для базовых символов GSM-7 — 160, далее — по 153. Расширенные символы считаются за 2, эмодзи — по длине в UTF-16. unitPrice и cost указаны в USDT. Фактический тариф — тот, что в ответе; 0.025 выше — лишь пример.

Проверяйте результат по каждому номеру

Используйте id, полученный от API отправки. Доступны только отправки через API с того же аккаунта. Запрос возвращает сохранённые результаты. Если нужны свежие данные оператора, сначала вызовите API обновления статуса.

curl 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd?limit=1&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "DONE",
  "total": 2, "segments": 1,
  "unitPrice": 0.025, "cost": 0.05,
  "createdAt": 1792800000000, "note": null,
  "summary": { "DELIVERED": 1, "PENDING": 1 },
  "messages": [
    {
      "id": "d2787184-d8b8-49c6-9c15-1db90a6d5516",
      "to": "12025550123",
      "status": "DELIVERED",
      "statusName": "DELIVERED_TO_HANDSET",
      "description": "Message delivered to handset",
      "error": null,
      "updatedAt": 1792800005000
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "nextOffset": 1 }
}

limit — 1–1000 (по умолчанию 100), offset — 0–1000 (по умолчанию 0). Если nextOffset равен null, это последняя страница. summary — количество номеров по статусам. to возвращается в международном формате без +, время — в миллисекундах Unix. Порядок номеров может отличаться от исходного — различайте сообщения по id.

Получите актуальный статус доставки

Обновляет сохранённые результаты по логам оператора. Тело запроса не нужно. После обновления снова запросите результаты через GET. Одну отправку можно обновлять раз в 30 секунд. Логи оператора доступны в течение 48 часов после отправки. Если настроены вебхуки, результаты могут обновляться автоматически.

curl -X POST 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd/refresh' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{ "id": "35bed356-b84a-452a-8e94-98b538972ecd", "updated": 2 }

updated — число обновлённых строк. Оно может быть равно 0, если сообщения ещё в очереди или новых результатов нет. Рекомендуем вызывать GET не чаще чем раз в 10 секунд, а refresh — только при необходимости.

Коды статусов

state запроса на отправку

PREPARING — подготовка · RUNNING — обработка · PAUSED — пауза · DONE — очередь обработана · CANCELED — отменено

Операторы могут добавлять новые коды статусов, поэтому обрабатывайте и неизвестные значения status. Причину ошибки смотрите в statusName, description и error.

Что делать при ошибке

{ "error": "Недостаточно кредитов. Пополните баланс и повторите запрос.", "code": "INSUFFICIENT_CREDITS" }

Для каждого API KEY допускается до 120 запросов в минуту в сумме по отправке, запросу и обновлению статуса. При превышении лимита смотрите заголовок Retry-After. API предназначен для межсерверной интеграции; вызовы из браузера через CORS не поддерживаются.

Подключение на Node.js

const response = await fetch('https://hexsms.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.HEXSMS_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'notice-20261024-001'
  },
  body: JSON.stringify({
    country: 'US',
    text: 'Your order is on its way.',
    recipients: ['+12025550123', '+12025550124']
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.code + ': ' + result.error);
console.log(result.id); // Use this ID to check delivery status.

Создавайте ключ запроса один раз на операцию и используйте то же значение при повторах, если ответ не пришёл. Если повторно отправить успешную операцию с новым ключом, она будет обработана как отдельная отправка.