> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Отправка SMS

> Отправляйте глобальные SMS-сообщения и отслеживайте их окончательный статус доставки.

## Что это

SMS API отправляет текстовое сообщение на один номер телефона. Используйте его для уведомлений, оповещений, транзакционных обновлений и других текстовых коммуникаций.

## Перед началом

* Сохраните ваш API-ключ YCloud в `YCLOUD_API_KEY`.
* Отформатируйте номер получателя в формате E.164.
* Зарегистрируйте одобренный `senderId`, если это требуется для направления.
* Укажите одобренную `signature` для сообщений, отправляемых в материковый Китай.

## Как это работает

Отправьте сообщение запросом `POST /sms`. Успешный ответ означает, что YCloud принял запрос. Он не гарантирует финальной доставки.

YCloud обновляет статус сообщения с `accepted` на более поздний, например `sent`, `delivered`, `undelivered` или `failed`. Получайте эти изменения через вебхук `sms.message.updated` или получайте записи SMS через `GET /sms`.

## Запрос

`POST /sms`

### Поля запроса

| Поле | Обязательное | Описание |
| - | - | - |
| `to` | Да | Номер телефона получателя в формате E.164. |
| `text` | Да | Текстовое тело сообщения. |
| `senderId` | Нет | Одобренный Sender ID, используемый для сообщения. Доступность зависит от направления. |
| `signature` | По условию | Одобренная подпись для материкового Китая. YCloud оборачивает её в `【】` и добавляет в начало сообщения. |
| `externalId` | Нет | Ваша уникальная ссылка для сверки сообщения с внутренней записью. |
| `callbackUrl` | Нет | URL отчёта о доставке для конкретного сообщения. Для новых интеграций используйте эндпоинты вебхуков. |

### Пример запроса

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/sms \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+16315551111",
    "text": "Your verification code is 123456.",
    "externalId": "login-10001"
  }'
```

## Ответ

Успешный ответ возвращает созданный объект SMS. Сохраните его `id`, чтобы соотносить обновления доставки и получать сообщение позже.

### Пример ответа

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "to": "+16315551111",
  "text": "Your verification code is 123456.",
  "regionCode": "US",
  "totalSegments": 1,
  "status": "accepted",
  "externalId": "login-10001",
  "createTime": "2026-07-16T12:00:00.000Z"
}
```

### Поля ответа

| Поле | Описание |
| - | - |
| `id` | ID сообщения в YCloud. Сохраните его для получения и корреляции событий. |
| `status` | Текущее состояние доставки. `accepted` означает, что запрос принят, а не доставлен. |
| `totalSegments` | Количество SMS-сегментов, используемых сообщением. |
| `totalPrice` | Общая стоимость сообщения, если доступно. |
| `currency` | Валюта цены по ISO 4217. |
| `errorCode` | Код ошибки, если сообщение не может быть доставлено. |
| `createTime` | Время создания сообщения в формате RFC 3339. |
| `updateTime` | Время последнего обновления статуса доставки. |
| `externalId` | Ссылка, указанная в запросе. |

## Статус доставки

Подпишитесь на `sms.message.updated` для отслеживания изменений статуса исходящих. Подпишитесь на `sms.inbound.received`, если ваш аккаунт принимает SMS-ответы.

Используйте `GET /sms` для сверки записей по времени создания или ID сообщения.

## Ограничения и устранение неполадок

* Доступность Sender ID и правила по контенту зависят от направления.
* Длинные сообщения могут использовать несколько SMS-сегментов и стоить дороже.
* Не повторяйте принятый запрос без стратегии идемпотентности. Повторный запрос может отправить дубликат сообщения.
* При расследовании проблем доставки используйте возвращённые `id` и `externalId`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.