API v2 (beta)
Promemoria
Un promemoria invia sempre lo stesso messaggio a un destinatario secondo una pianificazione: l'affitto ogni mese, una lezione ogni lunedì, un report ogni sera. La pianificazione è un'espressione cron in 5 parti in un fuso orario a tua scelta. I promemoria creati con l'API sono gli stessi della pagina Promemoria della dashboard.
| Operazione | Endpoint | Scope |
|---|---|---|
| Creare un promemoria | POST /api/v2/reminders | reminders |
| Elencare i promemoria | GET /api/v2/reminders | reminders |
| Ottenere un promemoria | GET /api/v2/reminders/{id} | reminders |
| Modificare, mettere in pausa o riprendere | PATCH /api/v2/reminders/{id} | reminders |
| Eliminare un promemoria | DELETE /api/v2/reminders/{id} | reminders |
Per creare e modificare promemoria serve un piano che includa i promemoria; altrimenti la richiesta risponde 403 plan_required. Elencare, leggere, mettere in pausa ed eliminare funzionano con qualsiasi piano. Per un messaggio che parte una sola volta a un'ora stabilita, usa invece send_at in Inviare un messaggio.
Creare un promemoria#
https://wbiztool.com/api/v2/remindersCorpo: 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'];Risposta (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"
}
Body
namestringobbligatorioUn nome per il promemoria, fino a 100 caratteri, come appare nella pagina Promemoria.
toobjectobbligatorioEsattamente uno tra
phone(formato internazionale con+),group(il nome esatto di un gruppo WhatsApp),contact_idousername(Telegram), come in Messaggi → Destinatari.frominteger or nullObbligatorio per una chiave limitata ad alcuni numeriL'
iddel numero che lo invia. Deve essere collegato quando lo imposti. Se lo ometti o ènull, lo invia un qualsiasi numero collegato dello spazio di lavoro.textstringobbligatorioIl messaggio, fino a 3.000 caratteri. È anche la didascalia quando viene inviato
media.mediaobject or nullfacoltativoUn'immagine o un file da inviare ogni volta:
urlomedia_ide, facoltativamente,type, come in Messaggi → Media.scheduleobjectobbligatoriocron(obbligatorio) etimezone. Vedi Pianificazione.activebooleanfacoltativotrue(predefinito) lo esegue;falselo crea in pausa.
Pianificazione#
schedule.cron ha cinque parti separate da spazi: minuto, ora, giorno del mese, mese, giorno della settimana. * significa "ogni". Deve essere una pianificazione che prima o poi viene eseguita (non il 31 febbraio).
cron | Si esegue |
|---|---|
0 9 * * 1 | Il lunedì alle 09:00 |
30 18 * * * | Ogni giorno alle 18:30 |
0 10 1 * * | Il 1° di ogni mese alle 10:00 |
0 9 * * 1-5 | Nei giorni feriali alle 09:00 |
0 8,20 * * * | Ogni giorno alle 08:00 e alle 20:00 |
0 9 15 1 * | Il 15 gennaio alle 09:00, ogni anno |
schedule.timezone è il nome di un fuso orario IANA, ad esempio Asia/Kolkata, Europe/London o America/New_York (predefinito UTC). Gli orari del cron sono in quel fuso, e anche next_run_at è indicato in quel fuso, con il suo offset. Vedi il riferimento fusi orari.
Ogni esecuzione invia un messaggio come qualsiasi altro: servono messaggi rimanenti nel piano e compare in Elencare i messaggi.
Errori durante la creazione#
| HTTP | Codice | Quando |
|---|---|---|
400 | validation_failed | Manca un campo obbligatorio o è vuoto, un campo è sconosciuto o troppo lungo (name, to.group), oppure media non è valido |
400 | text_required | text è vuoto |
400 | text_too_long | text supera i 3.000 caratteri |
400 | invalid_cron | schedule.cron non ha 5 parti, o non viene mai eseguito |
400 | invalid_timezone | schedule.timezone non è un fuso orario IANA |
403 | plan_required | Il piano non include i promemoria |
403 | number_not_allowed | La chiave è limitata ad alcuni numeri e from non è tra questi, o manca |
422 | invalid_phone | to.phone non è un numero valido in formato internazionale con + |
422 | invalid_username | to.username non è un username Telegram, un link o un id tg: |
422 | username_needs_telegram | Un username Telegram, ma from non è un account Telegram (oppure, senza from, non è collegato nessun account Telegram) |
422 | contact_not_found | Nessun contatto con quel to.contact_id |
422 | media_not_found | Nessun file con quel media.media_id |
422 | invalid_media_url | media.url non è un link http(s) pubblico |
422 | number_not_connected | from non è un numero collegato di questo spazio di lavoro |
Elencare i promemoria#
https://wbiztool.com/api/v2/remindersI promemoria dello spazio di lavoro, dal più recente, in pagine (limit da 1 a 100, predefinito 25, e cursor). Sono inclusi quelli in pausa, con "active": false. Una chiave limitata ad alcuni numeri vede solo i promemoria che vengono inviati da quei numeri.
curl "https://wbiztool.com/api/v2/reminders?limit=50" \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"
La risposta è {"data": [Reminder, …], "next_cursor": "…" or null}.
Ottenere un promemoria#
https://wbiztool.com/api/v2/reminders/{id}curl https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"
Un promemoria che non esiste, è stato eliminato o viene inviato da un numero che la chiave non può usare risponde 404 reminder_not_found.
Modificare, mettere in pausa o riprendere un promemoria#
https://wbiztool.com/api/v2/reminders/{id}Corpo: JSON (application/json)
Invia solo i campi che cambiano; gli altri mantengono i loro valori. I campi sono quelli di Creare un promemoria. La risposta è 200 con il promemoria com'è ora.
- Mettere in pausa:
{"active": false}. Smette di essere eseguito enext_run_atdiventanull. La pausa funziona con qualsiasi piano. - Riprendere:
{"active": true}. Riprende dalla sua prossima esecuzione. Per riprenderlo serve un piano con i promemoria. scheduleviene sostituito per intero: inviacroninsieme. Senzatimezone, il promemoria mantiene quello attuale.
# 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']);Una modifica risponde con gli stessi errori della creazione, più 404 reminder_not_found. Se un campo è sbagliato, non viene modificato nulla.
Eliminare un promemoria#
https://wbiztool.com/api/v2/reminders/{id}Elimina il promemoria: non verrà più eseguito. I messaggi che ha già inviato restano nella cronologia. Per fermarlo solo per un po', invece, mettilo in pausa.
curl -X DELETE https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"
{ "id": 812, "deleted": true }
L'oggetto Reminder#
| Campo | Tipo | Descrizione |
|---|---|---|
id | integer | L'id del promemoria. |
name | string | Il suo nome. |
active | boolean | true mentre è attivo, false mentre è in pausa. |
to | object | Il destinatario: phone (con +), group o username. Un promemoria creato con contact_id mostra il numero o il gruppo del contatto. |
from | integer or null | L'id del numero mittente, oppure null per un qualsiasi numero collegato. |
text | string | Il messaggio. |
media | object or null | type (image o file), url e file_name. |
schedule | object | cron e timezone. |
next_run_at | string or null | Quando verrà eseguito la prossima volta, nel suo fuso orario con l'offset, ad esempio 2026-10-19T09:00:00+05:30. null mentre è in pausa. |
created_at | string | Quando è stato creato (UTC). |
Pagine correlate#
- Promemoria nella dashboard
- Riferimento fusi orari
- Messaggi: un messaggio a un'ora stabilita con
send_at - Errori
