# Создание сообщения (POST)

Отправьте push-уведомление на ваши устройства.

## Эндпоинт

```
POST https://api.pocketalert.app/v1/messages
```

## Аутентификация

> **Info: Обязательно**
>
> Добавьте в запрос один из этих заголовков:
> - `Token: <your-api-key>` — получить можно в разделе [API-ключи](https://pocketalert.app/account/apikeys)
> - `Authorization: Bearer <jwt-token>` — из [входа](https://info.pocketalert.app/api/user/login.md)

## Запрос

### Заголовки

| Заголовок | Обязательный | Описание |
|-----------|:------------:|----------|
| `Content-Type` | ✅ | `application/json` |
| `Token` | ✅ | Ваш API-ключ |
| `Authorization` | ✅ | `Bearer <jwt-token>` |

<small>* Один из заголовков `Token` или `Authorization` обязателен</small>

### Параметры тела запроса

| Параметр | Тип | Обязательный | Описание |
|----------|-----|:------------:|----------|
| `title` | string | ✅ | Заголовок уведомления |
| `message` | string | ✅ | Текст уведомления |
| `application_id` | string | ❌ | TID приложения для категоризации сообщения |
| `device_id` | string | ❌ | TID конкретного устройства, не указывайте, чтобы отправить на все устройства |
| `level` | string \| int | ❌ | Уровень приоритета, определяющий способ доставки push-уведомления. Принимает название или целое число (`-2`..`2`). Синоним — `priority`. По умолчанию используется уровень приложения, а если он не задан — `default`. |
| `actions` | array | ❌ | До 3 кнопок действий в уведомлении. См. [Кнопки действий](#action-buttons). |
| `send_at` | string \| int | ❌ | Доставить в указанное время вместо немедленной отправки. RFC3339, Unix timestamp или `YYYY-MM-DD HH:MM`. См. [Отложенная отправка](#scheduled-delivery). |
| `delay` | string | ❌ | Доставить с относительной задержкой — `30m`, `2h` или просто секунды. Взаимоисключает `send_at`. |

#### Кнопки действий

Каждое уведомление может содержать до **3** кнопок действий. Они работают, когда приложение открыто, в фоне или закрыто. `actions` — это массив объектов, размер которого после JSON-кодирования не должен превышать 2048 байт (он передаётся внутри push-уведомления, ограниченного 4 КБ; длинное `message` будет сокращено, чтобы освободить место):

| Поле | Тип | Обязательное | Описание |
|------|-----|:------------:|----------|
| `type` | string | ✅ | `view` (открыть URL), `http` (выполнить HTTP-запрос) или `copy` (скопировать текст в буфер обмена) |
| `label` | string | ✅ | Текст кнопки, отображается как есть на Android и iOS |
| `value` | string | ✅ | Зависит от `type` — см. ниже |

`value` по типам:

- **`view`** — URL для открытия, например `"https://pocketalert.app"`.
- **`http`** — JSON-строка с описанием запроса: `{"url":"https://…","method":"POST","headers":{…},"body":"…"}`. Обязателен только `url`; `method` по умолчанию `GET`. Запрос выполняется с устройства в фоне без открытия приложения, поэтому может обращаться к хостам в локальной сети телефона. Если запрос не удался (статус не 2xx/3xx или ошибка сети), показывается уведомление с кнопкой **Retry**; повторно он никогда не отправляется автоматически, если мог дойти до сервера.
- **`copy`** — текст, который будет помещён в буфер обмена.

> **Tip: Человек в контуре**
>
> Две кнопки типа `http` (например, **Approve** / **Decline**) превращаются в панель управления в одно нажатие — это удобно для подтверждения действий LLM-агентов прямо из уведомления.

> **Warning: Платная функция**
>
> На бесплатных тарифах кнопки действий удаляются: сообщение доставляется без них, а `actions` не проверяется.

Ограничения, валидацию и шаблоны вебхуков см. в разделе [Кнопки действий](https://info.pocketalert.app/features/action-buttons.md).

#### Уровни приоритета

| Уровень | Синонимы | Поведение |
|---------|----------|-----------|
| `silent` | `min`, `-2` | Доставляется только в шторку — без звука и вибрации |
| `low` | `-1` | Тихо, без прерывания |
| `default` | `normal`, `0` (или не указан) | Стандартный баннер и звук |
| `high` | `1` | Важное по времени — пробивается через Фокусирование / плановую сводку |
| `critical` | `max`, `urgent`, `2` | Пробуждает устройство через переключатель режима тишины и режим «Не беспокоить». См. [Уровни приоритета](https://info.pocketalert.app/features/priority-levels.md) |

> **Warning**
>
> `critical` — функция платного тарифа. На бесплатных тарифах он автоматически понижается до `high`. Некорректные значения (неизвестное название или целое число вне диапазона) возвращают `400`.

Как каждый уровень работает на iOS и Android, см. в разделе [Уровни приоритета](https://info.pocketalert.app/features/priority-levels.md).

#### Отложенная отправка

Добавьте `send_at` или `delay` — но никогда оба сразу — и сообщение будет храниться в зашифрованном виде до времени доставки вместо немедленной отправки.

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

Время без смещения читается в часовом поясе вашего аккаунта. Горизонт планирования — 30 дней; `send_at` в прошлом возвращает `400` (с допуском 60 секунд на расхождение часов).

Отложенные запросы возвращают `201` с `"scheduled": true`, `status`, `deliver_at` и `deliver_at_utc` вместо доставленного сообщения. Список можно получить через `GET /v1/messages/scheduled`, отменить — через `DELETE /v1/messages/scheduled/{tid}`. См. [Отложенная отправка](https://info.pocketalert.app/features/scheduled-delivery.md).

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

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

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Server Alert",
    "message": "CPU usage exceeded 90%",
    "application_id": "qm47b9pzxzxg",
    "level": "critical",
    "actions": [
      { "type": "view", "label": "Dashboard", "value": "https://status.example.com" },
      { "type": "http", "label": "Restart", "value": "{\"url\":\"https://ops.example.com/restart\",\"method\":\"POST\"}" },
      { "type": "copy", "label": "Copy ID", "value": "incident-4821" }
    ]
  }'
```

**JavaScript**

```javascript
const response = await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Server Alert',
    message: 'CPU usage exceeded 90%',
    application_id: 'qm47b9pzxzxg'
  })
});

const data = await response.json();
console.log(data);
```

**Python**

```python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/messages',
    headers={
        'Token': 'your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Server Alert',
        'message': 'CPU usage exceeded 90%',
        'application_id': 'qm47b9pzxzxg'
    }
)

print(response.json())
```

**PHP**

```php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/messages', [
    'title' => 'Server Alert',
    'message' => 'CPU usage exceeded 90%',
    'application_id' => 'qm47b9pzxzxg',
]);

return $response->json();
```

## Ответ

### Успешный ответ

> **Tip: 201 Created**
>
> Сообщение успешно создано

| Поле | Тип | Описание |
|------|-----|----------|
| `tid` | string | Уникальный идентификатор сообщения |
| `title` | string | Заголовок сообщения |
| `message` | string | Текст сообщения |
| `application` | string | Название приложения (если указано) |
| `device` | string | Название устройства-получателя |
| `actions` | array | Кнопки действий в ответе (только если были переданы) |
| `created_at` | string | Время создания |

```json
{
  "tid": "jb4xw9elz28g",
  "title": "Server Alert",
  "message": "CPU usage exceeded 90%",
  "application": "Monitoring",
  "device": "iPhone",
  "actions": [
    { "type": "view", "label": "Dashboard", "value": "https://status.example.com" }
  ],
  "created_at": "18.01.2026 15:35:35"
}
```

### Заголовки квоты

Ответы содержат текущее использование [дневного лимита](https://info.pocketalert.app/features/daily-limits.md) (не возвращаются на тарифах без лимита):

| Заголовок | Описание |
|-----------|----------|
| `X-PA-Daily-Limit` | Количество сообщений в день по вашему тарифу |
| `X-PA-Daily-Remaining` | Сколько сообщений осталось на сегодня, включая этот |
| `X-PA-Daily-Reset` | Unix timestamp (в секундах) следующего сброса, 00:00 UTC |

### Ответы с ошибками

| Статус | Описание |
|:------:|----------|
| `400` | Bad Request — отсутствуют `title` или `message`, некорректный `level` или, на платных тарифах, некорректные `actions` |
| `401` | Unauthorized — токен неверный или отсутствует |
| `403` | Forbidden — `send_at` или `delay` на бесплатном тарифе |
| `404` | Not Found — `application_id` или `device_id` не существует |
| `429` | Достигнут дневной лимит — сообщение не сохранено и не отправлено. Подождите `Retry-After` секунд или перейдите на другой тариф. См. [Дневные лимиты сообщений](https://info.pocketalert.app/features/daily-limits.md). |

```json
{
  "error": "Validation failed",
  "details": {
    "title": ["The title field is required"]
  }
}
```

#### Достигнут дневной лимит

Когда квота на сегодня исчерпана, сообщение отклоняется — не ставится в очередь — до 00:00 UTC. В `Retry-After` указано количество секунд до сброса.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 30142
X-PA-Daily-Limit: 50
X-PA-Daily-Remaining: 0
X-PA-Daily-Reset: 1790035200
```

```json
{
  "error": "Daily message limit reached (50/50). New messages are rejected until 00:00 UTC. Upgrade your plan to raise the limit.",
  "limit": 50,
  "used": 50,
  "resets_at": "2026-09-22T00:00:00Z",
  "upgrade_url": "https://pocketalert.app/pricing"
}
```

Удаление сообщений не освобождает квоту. Проверить сегодняшнее использование можно через [`GET /v1/messages/usage`](https://info.pocketalert.app/api/messages/usage.md).
