Vai al contenuto
WbizTool

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.

OperazioneEndpointScope
Creare un promemoriaPOST /api/v2/remindersreminders
Elencare i promemoriaGET /api/v2/remindersreminders
Ottenere un promemoriaGET /api/v2/reminders/{id}reminders
Modificare, mettere in pausa o riprenderePATCH /api/v2/reminders/{id}reminders
Eliminare un promemoriaDELETE /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#

POSThttps://wbiztool.com/api/v2/reminders

Corpo: 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" }
  }'

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

namestringobbligatorio

Un nome per il promemoria, fino a 100 caratteri, come appare nella pagina Promemoria.

toobjectobbligatorio

Esattamente uno tra phone (formato internazionale con +), group (il nome esatto di un gruppo WhatsApp), contact_id o username (Telegram), come in Messaggi → Destinatari.

frominteger or nullObbligatorio per una chiave limitata ad alcuni numeri

L'id del 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.

textstringobbligatorio

Il messaggio, fino a 3.000 caratteri. È anche la didascalia quando viene inviato media.

mediaobject or nullfacoltativo

Un'immagine o un file da inviare ogni volta: url o media_id e, facoltativamente, type, come in Messaggi → Media.

scheduleobjectobbligatorio

cron (obbligatorio) e timezone. Vedi Pianificazione.

activebooleanfacoltativo

true (predefinito) lo esegue; false lo 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).

cronSi esegue
0 9 * * 1Il 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-5Nei 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#

HTTPCodiceQuando
400validation_failedManca un campo obbligatorio o è vuoto, un campo è sconosciuto o troppo lungo (name, to.group), oppure media non è valido
400text_requiredtext è vuoto
400text_too_longtext supera i 3.000 caratteri
400invalid_cronschedule.cron non ha 5 parti, o non viene mai eseguito
400invalid_timezoneschedule.timezone non è un fuso orario IANA
403plan_requiredIl piano non include i promemoria
403number_not_allowedLa chiave è limitata ad alcuni numeri e from non è tra questi, o manca
422invalid_phoneto.phone non è un numero valido in formato internazionale con +
422invalid_usernameto.username non è un username Telegram, un link o un id tg:
422username_needs_telegramUn username Telegram, ma from non è un account Telegram (oppure, senza from, non è collegato nessun account Telegram)
422contact_not_foundNessun contatto con quel to.contact_id
422media_not_foundNessun file con quel media.media_id
422invalid_media_urlmedia.url non è un link http(s) pubblico
422number_not_connectedfrom non è un numero collegato di questo spazio di lavoro

Elencare i promemoria#

GEThttps://wbiztool.com/api/v2/reminders

I 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#

GEThttps://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#

PATCHhttps://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 e next_run_at diventa null. La pausa funziona con qualsiasi piano.
  • Riprendere: {"active": true}. Riprende dalla sua prossima esecuzione. Per riprenderlo serve un piano con i promemoria.
  • schedule viene sostituito per intero: invia cron insieme. Senza timezone, 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."}'

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#

DELETEhttps://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#

CampoTipoDescrizione
idintegerL'id del promemoria.
namestringIl suo nome.
activebooleantrue mentre è attivo, false mentre è in pausa.
toobjectIl destinatario: phone (con +), group o username. Un promemoria creato con contact_id mostra il numero o il gruppo del contatto.
frominteger or nullL'id del numero mittente, oppure null per un qualsiasi numero collegato.
textstringIl messaggio.
mediaobject or nulltype (image o file), url e file_name.
scheduleobjectcron e timezone.
next_run_atstring or nullQuando 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_atstringQuando è stato creato (UTC).

Pagine correlate#