Отправить SMS (POST)

Отправляет SMS через одно из ваших подключённых Android-устройств.

Метод: POST
Эндпоинт: /api/ext/v1/sms
Требуемое разрешение: sms:send

Тело запроса

{
  "phone": "+79001234567",
  "message": "Текст сообщения",
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "no_store": false
}

Поле	Тип	Обязательно	Описание
phone	string	✅	Номер телефона получателя в международном формате (+7...)
message	string	✅	Текст SMS, не более 300 символов
device_id	string (UUID)	❌	ID конкретного устройства. Если не указан — система выберет любое доступное
no_store	boolean	❌	Если true — SMS не сохраняется в истории. По умолчанию false

Выбор устройства

Если у вас несколько устройств и вы не указали device_id, система автоматически выберет любое онлайн-устройство с разрешённой отправкой SMS. Это удобно — не нужно следить за тем, какое устройство сейчас онлайн.

Ответ — 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "phone": "+79001234567",
  "message": "Текст сообщения",
  "status": "pending",
  "sent_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Поле	Описание
id	Уникальный ID SMS (UUID)
device_id	ID устройства, которому назначена отправка
phone	Номер получателя
message	Текст сообщения
status	Статус SMS (см. ниже)
sent_at	Время создания записи
updated_at	Время последнего обновления статуса

Статусы SMS

Статус	Значение
pending	Ожидает отправки (устройство получит задание)
sent	Устройство приняло задание и отправило
delivered	Оператор подтвердил доставку
undelivered	Не доставлено (номер недоступен)
failed_send	Ошибка при отправке на устройстве
failed_delivery	Ошибка подтверждения доставки

Примеры

curl

curl -X POST https://api.gosms.ru/api/ext/v1/sms \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+79001234567",
    "message": "Ваш код подтверждения: 4521"
  }'

Указать конкретное устройство

curl -X POST https://api.gosms.ru/api/ext/v1/sms \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+79001234567",
    "message": "Привет!",
    "device_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Python

import requests

def send_sms(phone: str, message: str, device_id: str = None):
    payload = {"phone": phone, "message": message}
    if device_id:
        payload["device_id"] = device_id

    response = requests.post(
        "https://api.gosms.ru/api/ext/v1/sms",
        headers={
            "Authorization": "Bearer ВАШ_КЛЮЧ",
            "Content-Type": "application/json",
        },
        json=payload,
    )
    response.raise_for_status()
    return response.json()

# Отправить на любое доступное устройство
sms = send_sms("+79001234567", "Ваш код: 1234")
print(f"ID: {sms['id']}, статус: {sms['status']}")

JavaScript

async function sendSMS(phone, message, deviceId = null) {
  const body = { phone, message };
  if (deviceId) body.device_id = deviceId;

  const response = await fetch('https://api.gosms.ru/api/ext/v1/sms', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ВАШ_КЛЮЧ',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.error.message);
  }

  return response.json();
}

const sms = await sendSMS('+79001234567', 'Ваш заказ принят!');
console.log('SMS создан:', sms.id);

Node.js (массовая рассылка)

const phones = ['+79001234567', '+79007654321', '+79001112233'];
const message = 'Акция! Скидка 20% до конца недели.';

// Отправляем по одному — не параллельно, чтобы не перегрузить устройство
for (const phone of phones) {
  try {
    const sms = await sendSMS(phone, message);
    console.log(`✅ ${phone} — ${sms.status}`);
  } catch (err) {
    console.error(`❌ ${phone} — ${err.message}`);
  }
  // Небольшая пауза между отправками
  await new Promise(r => setTimeout(r, 500));
}

Флаг no_store

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

{
  "phone": "+79001234567",
  "message": "Технический алерт: сервер недоступен",
  "no_store": true
}

WARNING

При no_store: true запись не создаётся. Если устройство было офлайн в момент запроса — SMS может быть потеряно, так как оно не попадёт в очередь повторной попытки.