Создание сообщения POST
Отправьте push-уведомление на ваши устройства.
Эндпоинт
POST https://api.pocketalert.app/v1/messagesАутентификация
Обязательно
Добавьте в запрос один из этих заголовков:
Запрос
Заголовки
| Заголовок | Обязательный | Описание |
|---|---|---|
Content-Type | ✅ | application/json |
Token | ✅ | Ваш API-ключ |
Authorization | ✅ | Bearer <jwt-token> |
* Один из заголовков Token или Authorization обязателен
Параметры тела запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
title | string | ✅ | Заголовок уведомления |
message | string | ✅ | Текст уведомления |
application_id | string | ❌ | TID приложения для категоризации сообщения |
device_id | string | ❌ | TID конкретного устройства, не указывайте, чтобы отправить на все устройства |
level | string | int | ❌ | Уровень приоритета, определяющий способ доставки push-уведомления. Принимает название или целое число (-2..2). Синоним — priority. По умолчанию используется уровень приложения, а если он не задан — default. |
actions | array | ❌ | До 3 кнопок действий в уведомлении. См. Кнопки действий. |
send_at | string | int | ❌ | Доставить в указанное время вместо немедленной отправки. RFC3339, Unix timestamp или YYYY-MM-DD HH:MM. См. Отложенная отправка. |
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— текст, который будет помещён в буфер обмена.
Человек в контуре
Две кнопки типа http (например, Approve / Decline) превращаются в панель управления в одно нажатие — это удобно для подтверждения действий LLM-агентов прямо из уведомления.
Платная функция
На бесплатных тарифах кнопки действий удаляются: сообщение доставляется без них, а actions не проверяется.
Ограничения, валидацию и шаблоны вебхуков см. в разделе Кнопки действий.
Уровни приоритета
| Уровень | Синонимы | Поведение |
|---|---|---|
silent | min, -2 | Доставляется только в шторку — без звука и вибрации |
low | -1 | Тихо, без прерывания |
default | normal, 0 (или не указан) | Стандартный баннер и звук |
high | 1 | Важное по времени — пробивается через Фокусирование / плановую сводку |
critical | max, urgent, 2 | Пробуждает устройство через переключатель режима тишины и режим «Не беспокоить». См. Уровни приоритета |
WARNING
critical — функция платного тарифа. На бесплатных тарифах он автоматически понижается до high. Некорректные значения (неизвестное название или целое число вне диапазона) возвращают 400.
Как каждый уровень работает на iOS и Android, см. в разделе Уровни приоритета.
Отложенная отправка
Добавьте 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}. См. Отложенная отправка.
WARNING
Отложенная отправка — функция платного тарифа. Запросы с send_at или delay на бесплатном тарифе возвращают 403.
Пример запроса
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" }
]
}'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);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())$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();Ответ
Успешный ответ
201 Created
Сообщение успешно создано
| Поле | Тип | Описание |
|---|---|---|
tid | string | Уникальный идентификатор сообщения |
title | string | Заголовок сообщения |
message | string | Текст сообщения |
application | string | Название приложения (если указано) |
device | string | Название устройства-получателя |
actions | array | Кнопки действий в ответе (только если были переданы) |
created_at | string | Время создания |
{
"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"
}Заголовки квоты
Ответы содержат текущее использование дневного лимита (не возвращаются на тарифах без лимита):
| Заголовок | Описание |
|---|---|
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 секунд или перейдите на другой тариф. См. Дневные лимиты сообщений. |
{
"error": "Validation failed",
"details": {
"title": ["The title field is required"]
}
}Достигнут дневной лимит
Когда квота на сегодня исчерпана, сообщение отклоняется — не ставится в очередь — до 00:00 UTC. В Retry-After указано количество секунд до сброса.
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{
"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.