# Отложенная отправка push-уведомлений

Отправьте сообщение сейчас, а доставьте позже. Добавьте `send_at` или `delay` к любому запросу [Create Message](https://info.pocketalert.app/api/messages/create.md), и Pocket Alert сохранит сообщение в зашифрованном виде до времени доставки, а затем отправит его как обычное push-уведомление.

Не нужна cron-задача на вашей стороне, не нужен воркер очереди и процесс, который должен работать до вторника.

## Два способа указать время

| Параметр | Принимает | Примеры |
|-----------|---------|----------|
| `send_at` | RFC3339, Unix-время или `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`, `1786867200`, `2026-08-15 09:00` |
| `delay` | Длительность в формате Go или количество секунд | `30m`, `2h`, `90s`, `3600` |

Передайте что-то одно: если указать оба параметра, вернётся `400`.

`send_at` без смещения часового пояса читается в **часовом поясе вашего аккаунта**, поэтому `2026-08-15 09:00` означает девять утра там, где вы находитесь, а не по UTC. Задать его можно в [настройках аккаунта](https://pocketalert.app/account).

## Планирование сообщения

**cURL — absolute time**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Certificate expires tomorrow",
    "message": "api.example.com — renew before 09:00 UTC",
    "send_at": "2026-08-15T09:00:00Z",
    "level": "high"
  }'
```

**cURL — relative delay**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Check the migration",
    "message": "Started at 14:02 — verify row counts",
    "delay": "2h"
  }'
```

**JavaScript**

```javascript
await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: { 'Token': 'your-api-key', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Check the migration',
    message: 'Started at 14:02 — verify row counts',
    delay: '2h'
  })
});
```

**Python**

```python
import requests

requests.post(
    'https://api.pocketalert.app/v1/messages',
    headers={'Token': 'your-api-key'},
    json={
        'title': 'Check the migration',
        'message': 'Started at 14:02 — verify row counts',
        'delay': '2h'
    }
)
```

Запланированное сообщение возвращает `201` с `"scheduled": true` вместо доставленного сообщения:

```json
{
  "tid": "n8k2vq7pxr4m",
  "scheduled": true,
  "status": "pending",
  "title": "Check the migration",
  "deliver_at": "09.08.2026 16:02:00",
  "deliver_at_utc": "2026-08-09T13:02:00Z",
  "tz": "Europe/Berlin"
}
```

Сохраните `tid`: по нему отменяется сообщение.

## Список запланированных сообщений (GET)

```
GET https://api.pocketalert.app/v1/messages/scheduled
```

По умолчанию возвращаются ожидающие сообщения, сначала ближайшие.

| Параметр запроса | Значения | Описание |
|-----------------|--------|-------------|
| `status` | `pending`, `sending`, `sent`, `canceled`, `failed`, `all` | Фильтр по состоянию. По умолчанию `pending`. |

```bash
curl -X GET "https://api.pocketalert.app/v1/messages/scheduled?status=all" \
  -H "Token: your-api-key"
```

Каждый элемент содержит `tid`, `title`, `message`, `priority`, `status`, `deliver_at`, `deliver_at_utc`, `tz`, `application`, `device`, `created_at`, а также `actions`, если у сообщения есть кнопки.

## Отмена (DELETE)

```
DELETE https://api.pocketalert.app/v1/messages/scheduled/{tid}
```

```bash
curl -X DELETE "https://api.pocketalert.app/v1/messages/scheduled/n8k2vq7pxr4m" \
  -H "Token: your-api-key"
```

| Статус | Значение |
|:------:|---------|
| `200` | Отменено. Вложение удаляется вместе с сообщением. |
| `404` | В вашем аккаунте нет запланированного сообщения с таким `tid` |
| `409` | Уже отправлено, уже отправляется или уже отменено |

Отмена безопасно работает вместе с диспетчером: если доставка уже началась, вы получите `409`, а не наполовину отменённое сообщение.

## Правила, которые стоит знать

**Горизонт планирования — 30 дней.** Всё, что дальше, отклоняется.

**Прошедшее время возвращает `400`** с допуском 60 секунд на расхождение часов. Внутри этого окна сообщение просто отправляется сразу.

**Уровень и тариф определяются в момент планирования, а не доставки.** Сообщение, запланированное с уровнем `critical` на платном тарифе, всё равно придёт как `critical`, даже если тариф закончится в промежутке. Запланированное сообщение — это обещание.

**Дневной лимит списывается при планировании.** Запланированное сообщение учитывается в [дневном лимите сообщений](https://info.pocketalert.app/features/daily-limits.md) того дня, когда вы его запланировали, а не того дня, когда оно доставлено, и доставка никогда не блокируется лимитом. Если лимит превышен, сам запрос на планирование возвращает `429`. Отмена не возвращает квоту.

**Вложения загружаются при планировании** и привязываются к сообщению при доставке. Отмена удаляет сохранённый файл.

**Просроченные сообщения доставляются с опозданием, а не теряются.** Если сервис перезапустился после времени доставки, сообщение уйдёт на следующем тике, а не исчезнет.

**Содержимое шифруется при хранении** вашим персональным ключом с момента планирования, так же как обычные сообщения.

> **Warning: Платная функция**
>
> Отложенная отправка доступна на платных тарифах. Запрос на бесплатном тарифе с `send_at` или `delay` возвращает `403` — ничего не отбрасывается молча.

## Связанное

- [Create Message](https://info.pocketalert.app/api/messages/create.md) — полная справка по запросу
- [Уровни приоритета](https://info.pocketalert.app/features/priority-levels.md) — как ведёт себя доставленное оповещение
- [Кнопки действий](https://info.pocketalert.app/features/action-buttons.md) — запланированные сообщения сохраняют свои кнопки
- [Дневные лимиты сообщений](https://info.pocketalert.app/features/daily-limits.md) — как учитываются запланированные сообщения
