API v2 (бета)
Напоминания
Напоминание снова и снова отправляет одно и то же сообщение одному получателю по расписанию: аренда каждый месяц, занятие каждый понедельник, отчёт каждый вечер. Расписание — это выражение cron из 5 частей в выбранном вами часовом поясе. Напоминания, созданные через API, — те же самые, что на странице Напоминания в панели.
| Операция | Endpoint | Область доступа |
|---|---|---|
| Создание напоминания | POST /api/v2/reminders | reminders |
| Список напоминаний | GET /api/v2/reminders | reminders |
| Получение напоминания | GET /api/v2/reminders/{id} | reminders |
| Изменение, пауза и возобновление | PATCH /api/v2/reminders/{id} | reminders |
| Удаление напоминания | DELETE /api/v2/reminders/{id} | reminders |
Для создания и изменения напоминаний нужен тариф, включающий напоминания; иначе ответ — 403 plan_required. Просмотр, чтение, пауза и удаление работают на любом тарифе. Для сообщения, которое уходит один раз в заданное время, используйте send_at в Отправке сообщения.
Создание напоминания#
https://wbiztool.com/api/v2/remindersТело запроса: JSON (application/json)
curl -X POST https://wbiztool.com/api/v2/reminders \
-H "Authorization: Bearer $WBIZTOOL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: rent-flat-4b" \
-d '{
"name": "Weekly rent",
"from": 101,
"to": { "phone": "+919876543210" },
"text": "Hi, a reminder that the rent is due on Friday.",
"schedule": { "cron": "0 9 * * 1", "timezone": "Asia/Kolkata" }
}'import os
import requests
response = requests.post(
"https://wbiztool.com/api/v2/reminders",
headers={
"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}",
"Idempotency-Key": "rent-flat-4b",
},
json={
"name": "Weekly rent",
"from": 101,
"to": {"phone": "+919876543210"},
"text": "Hi, a reminder that the rent is due on Friday.",
"schedule": {"cron": "0 9 * * 1", "timezone": "Asia/Kolkata"},
},
timeout=30,
)
reminder = response.json()
print(response.status_code, reminder.get("id"), reminder.get("next_run_at"))// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/reminders", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "rent-flat-4b",
},
body: JSON.stringify({
name: "Weekly rent",
from: 101,
to: { phone: "+919876543210" },
text: "Hi, a reminder that the rent is due on Friday.",
schedule: { cron: "0 9 * * 1", timezone: "Asia/Kolkata" },
}),
});
const reminder = await response.json();
console.log(response.status, reminder.id, reminder.next_run_at);<?php
$ch = curl_init('https://wbiztool.com/api/v2/reminders');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: rent-flat-4b',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Weekly rent',
'from' => 101,
'to' => ['phone' => '+919876543210'],
'text' => 'Hi, a reminder that the rent is due on Friday.',
'schedule' => ['cron' => '0 9 * * 1', 'timezone' => 'Asia/Kolkata'],
]),
CURLOPT_RETURNTRANSFER => true,
]);
$reminder = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $reminder['id'] . ' next: ' . $reminder['next_run_at'];Ответ (201):
{
"id": 812,
"name": "Weekly rent",
"active": true,
"to": { "phone": "+919876543210" },
"from": 101,
"text": "Hi, a reminder that the rent is due on Friday.",
"media": null,
"schedule": { "cron": "0 9 * * 1", "timezone": "Asia/Kolkata" },
"next_run_at": "2026-10-19T09:00:00+05:30",
"created_at": "2026-10-18T10:20:11.004Z"
}
Тело запроса
namestringобязательноНазвание напоминания, до 100 символов, как оно показывается на странице «Напоминания».
toobjectобязательноРовно одно из полей:
phone(международный формат с+),group(точное название группы WhatsApp),contact_idилиusername(Telegram), как в Сообщения → Получатели.frominteger or nullОбязателен для ключа, ограниченного некоторыми номерамиidномера, который его отправляет. На момент указания номер должен быть подключён. Если не указан илиnull, отправляет любой подключённый номер рабочего пространства.textstringобязательноТекст сообщения, до 3000 символов. Если отправляется
media, это ещё и подпись.mediaobject or nullнеобязательноИзображение или файл, которые отправляются каждый раз:
urlилиmedia_idи при необходимостиtype, как в Сообщения → Медиафайлы.scheduleobjectобязательноcron(обязательно) иtimezone. См. Расписание.activebooleanнеобязательноtrue(по умолчанию) — напоминание работает;false— создаётся на паузе.
Расписание#
schedule.cron состоит из пяти частей через пробел: минута, час, день месяца, месяц, день недели. * означает «каждый». Расписание должно когда-нибудь срабатывать (не 31 февраля).
cron | Срабатывает |
|---|---|
0 9 * * 1 | По понедельникам в 09:00 |
30 18 * * * | Каждый день в 18:30 |
0 10 1 * * | 1-го числа каждого месяца в 10:00 |
0 9 * * 1-5 | По будням в 09:00 |
0 8,20 * * * | Каждый день в 08:00 и 20:00 |
0 9 15 1 * | 15 января в 09:00, каждый год |
schedule.timezone — название часового пояса IANA, например Asia/Kolkata, Europe/London или America/New_York (по умолчанию UTC). Время в cron указывается в этом поясе, и next_run_at тоже приводится в нём, со смещением. См. справочник часовых поясов.
Каждое срабатывание отправляет обычное сообщение: для него нужны оставшиеся сообщения тарифа, и оно появляется в Списке сообщений.
Ошибки при создании#
| HTTP | Код | Когда |
|---|---|---|
400 | validation_failed | Обязательное поле отсутствует или пусто, поле неизвестно или слишком длинное (name, to.group), или media недействителен |
400 | text_required | text пуст |
400 | text_too_long | text длиннее 3000 символов |
400 | invalid_cron | schedule.cron состоит не из 5 частей или никогда не срабатывает |
400 | invalid_timezone | schedule.timezone — не часовой пояс IANA |
403 | plan_required | Тариф не включает напоминания |
403 | number_not_allowed | Ключ ограничен некоторыми номерами, а from не из их числа или не указан |
422 | invalid_phone | to.phone — не действительный номер в международном формате с + |
422 | invalid_username | to.username — не имя пользователя Telegram, не ссылка и не ID tg: |
422 | username_needs_telegram | Указано имя пользователя Telegram, но from — не аккаунт Telegram (или, без from, не подключён ни один аккаунт Telegram) |
422 | contact_not_found | Нет контакта с таким to.contact_id |
422 | media_not_found | Нет файла с таким media.media_id |
422 | invalid_media_url | media.url — не публичная ссылка http(s) |
422 | number_not_connected | from — не подключённый номер этого рабочего пространства |
Список напоминаний#
https://wbiztool.com/api/v2/remindersНапоминания рабочего пространства, сначала самые новые, страницами (limit от 1 до 100, по умолчанию 25, и cursor). Приостановленные тоже входят в список, с "active": false. Ключ, ограниченный некоторыми номерами, видит только напоминания, которые отправляются с этих номеров.
curl "https://wbiztool.com/api/v2/reminders?limit=50" \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"
Ответ — {"data": [Reminder, …], "next_cursor": "…" or null}.
Получение напоминания#
https://wbiztool.com/api/v2/reminders/{id}curl https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"
Напоминание, которого не существует, которое удалено или отправляется с номера, недоступного ключу, возвращает 404 reminder_not_found.
Изменение, пауза и возобновление напоминания#
https://wbiztool.com/api/v2/reminders/{id}Тело запроса: JSON (application/json)
Передавайте только поля, которые меняются; остальные сохраняют свои значения. Поля те же, что в Создании напоминания. Ответ — 200 с напоминанием в его текущем виде.
- Пауза:
{"active": false}. Напоминание перестаёт срабатывать, аnext_run_atстановитсяnull. Пауза работает на любом тарифе. - Возобновление:
{"active": true}. Напоминание снова срабатывает со следующего времени по расписанию. Для возобновления нужен тариф с напоминаниями. scheduleзаменяется целиком: передавайте вместе с нимcron. Безtimezoneнапоминание сохраняет текущий часовой пояс.
# Pause
curl -X PATCH https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"active": false}'
# Move it to Fridays at 10:00 and change the text
curl -X PATCH https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"schedule": {"cron": "0 10 * * 5"}, "text": "Hi, the rent is due today."}'import os
import requests
headers = {"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"}
url = "https://wbiztool.com/api/v2/reminders/812"
paused = requests.patch(url, headers=headers, json={"active": False}, timeout=30).json()
print(paused["active"], paused["next_run_at"]) # False None
resumed = requests.patch(url, headers=headers, json={"active": True}, timeout=30).json()
print(resumed["active"], resumed["next_run_at"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/reminders/812", {
method: "PATCH",
headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ active: false }),
});
const reminder = await response.json();
console.log(reminder.active, reminder.next_run_at); // false null<?php
$ch = curl_init('https://wbiztool.com/api/v2/reminders/812');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['active' => false]),
CURLOPT_RETURNTRANSFER => true,
]);
$reminder = json_decode(curl_exec($ch), true);
curl_close($ch);
var_dump($reminder['active']);Изменение возвращает те же ошибки, что и создание, а также 404 reminder_not_found. Если хотя бы одно поле неверно, ничего не меняется.
Удаление напоминания#
https://wbiztool.com/api/v2/reminders/{id}Удаляет напоминание: оно больше никогда не сработает. Уже отправленные им сообщения остаются в истории. Чтобы остановить его на время, поставьте его на паузу.
curl -X DELETE https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"
{ "id": 812, "deleted": true }
Объект Reminder#
| Поле | Тип | Описание |
|---|---|---|
id | integer | ID напоминания. |
name | string | Его название. |
active | boolean | true, пока оно работает, false, пока оно на паузе. |
to | object | Получатель: phone (с +), group или username. Напоминание, созданное с contact_id, показывает номер или группу контакта. |
from | integer or null | id номера-отправителя или null для любого подключённого номера. |
text | string | Текст сообщения. |
media | object or null | type (image или file), url и file_name. |
schedule | object | cron и timezone. |
next_run_at | string or null | Когда оно сработает в следующий раз, в его часовом поясе со смещением, например 2026-10-19T09:00:00+05:30. null, пока оно на паузе. |
created_at | string | Когда оно создано (UTC). |
Связанные материалы#
- Напоминания в панели
- Справочник часовых поясов
- Сообщения: одно сообщение в заданное время через
send_at - Ошибки
