Vai al contenuto
WbizTool

API promemoria

API Crea promemoria

Crea un messaggio WhatsApp ricorrente che viene inviato automaticamente secondo una pianificazione. Usala per promemoria di pagamento, check-in settimanali, follow-up quotidiani e altri messaggi che si ripetono.

POSThttps://wbiztool.com/api/v1/reminder/create/

Corpo: JSON o campi di un modulo

Descrivi la pianificazione con un'espressione cron e un fuso orario. Ogni volta che la pianificazione corrisponde, WbizTool mette in coda un messaggio per il numero di telefono o il gruppo, proprio come un messaggio inviato con Invia messaggio. I promemoria che crei qui compaiono anche nella pagina Promemoria della tua dashboard, dove puoi metterli in pausa o modificarli.

Esempio rapido#

curl -X POST https://wbiztool.com/api/v1/reminder/create/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "reminder_name": "Monthly rent reminder",
    "phone": "919876543210",
    "message": "Hi Aman, a reminder that your rent is due on {current_date_formatted}.",
    "cron_expression": "0 10 1 * *",
    "timezone": "Asia/Kolkata"
  }'

Questo promemoria viene inviato alle 10:00 ora indiana il giorno 1 di ogni mese. Sostituisci 12345, YOUR_API_KEY e 678 con i tuoi valori. Consulta Autenticazione per sapere dove trovarli.

Parametri della richiesta#

Invia i parametri come corpo JSON o come campi di un modulo. In JSON, invia ogni valore testuale (api_key, reminder_name, phone, message, cron_expression, timezone, img_url, file_name) come stringa.

Autenticazione

client_idintegerobbligatorio

Il tuo ID Client API, da Impostazioni → Chiavi API.

api_keystringobbligatorio

La tua chiave API, dalla stessa pagina.

Mittente

whatsapp_clientintegerfacoltativo

ID del numero WhatsApp o dell'account Telegram da cui inviare, dalle Impostazioni WhatsApp. Se lo ometti, o se l'ID non è nel tuo spazio di lavoro, ogni promemoria viene inviato da un numero collegato al momento dell'esecuzione, prima WhatsApp: il primo numero WhatsApp collegato, oppure un account Telegram solo quando è l'unico collegato. Un promemoria a un @username, a un link t.me o a tg:<id> viene inviato da un account Telegram collegato.

Promemoria

reminder_namestringobbligatorio

Un nome per il promemoria, mostrato nella pagina Promemoria e disponibile nel messaggio come {reminder_name}.

phonestringobbligatorio

Il numero WhatsApp del destinatario con il prefisso internazionale, ad esempio 919876543210. Non esiste un parametro country_code separato. Spazi, +, -, . e parentesi vengono rimossi, e così anche un 00 iniziale e uno 0 iniziale, quindi il numero viene salvato solo come cifre: +91 98765-43210 e 0091 98765 43210 vengono salvati entrambi come 919876543210. Un numero senza prefisso internazionale, come 9876543210 o 09876543210, viene salvato senza lo 0 e completato quando il promemoria viene eseguito, con il Paese del numero whatsapp_client, altrimenti con il Paese per i numeri senza prefisso internazionale dello spazio di lavoro. Quando non si conosce alcun Paese, viene inviato così come è scritto. I valori da foglio di calcolo come 919876543210.0 e 9.19876543210E+11 vengono letti come le loro cifre. Un valore arrotondato da foglio di calcolo come 9.19877E+11 viene rifiutato, perché mancano delle cifre. Un valore con lettere o altri simboli viene trattato come nome di un gruppo WhatsApp e salvato così come l'hai scritto. Eccezione: un @username, un link t.me/username o tg:<id> è un utente Telegram, a cui si invia da un account Telegram. Passa l'ID di quell'account come whatsapp_client.

messagestringobbligatorio

Il testo del messaggio. Può includere variabili di modello che vengono compilate a ogni esecuzione del promemoria. La formattazione di WhatsApp funziona: *bold*, _italic_, ~strikethrough~.

cron_expressionstringobbligatorio

Quando inviare, come espressione cron a cinque campi, ad esempio 0 9 * * 1-5. Vedi Espressioni cron.

timezonestringfacoltativo

Il fuso orario in cui viene eseguita l'espressione cron, come nome di fuso orario IANA, ad esempio Asia/Kolkata, America/New_York o Europe/London. Omettilo per usare UTC. Una stringa vuota restituisce Invalid timezone. Consulta il Riferimento fusi orari per l'elenco completo.

Immagini e file

msg_typeintegerfacoltativo

0 testo (predefinito), 1 immagine o 2 file, con message come didascalia. Qualsiasi altro valore viene trattato come 0.

img_urlstringObbligatorio quando msg_type è 1 o 2

URL pubblico http o https dell'immagine, o del file per msg_type 2, fino a 1.000 caratteri. Viene scaricato a ogni esecuzione del promemoria, quindi mantieni il link funzionante. Puoi ospitare i file con l'API Carica file multimediali.

file_namestringObbligatorio quando msg_type è 2

Per msg_type 2, il nome del file con la sua estensione, fino a 100 caratteri, ad esempio invoice.pdf. Ignorato per gli altri tipi di messaggio.

Espressioni cron#

Un'espressione cron è composta da cinque valori separati da spazi. Il promemoria viene eseguito ogni volta che l'ora corrente in timezone corrisponde a tutti e cinque:

┌───────── minute        (0-59)
│ ┌─────── hour          (0-23)
│ │ ┌───── day of month  (1-31)
│ │ │ ┌─── month         (1-12)
│ │ │ │ ┌─ day of week   (0-7, where 0 and 7 are Sunday)
│ │ │ │ │
0 9 * * 1-5
SimboloSignificatoEsempio
*Ogni valore* nel campo dell'ora significa ogni ora.
,Un elenco di valori9,18 nel campo dell'ora significa alle 9:00 e alle 18:00.
-Un intervallo1-5 nel campo del giorno della settimana significa da lunedì a venerdì.
/Un passo*/6 nel campo dell'ora significa ogni 6 ore.

Esempi comuni#

EspressioneEsecuzione
0 9 * * *Ogni giorno alle 9:00
0 9 * * 1-5Da lunedì a venerdì alle 9:00
0 9 * * 1Ogni lunedì alle 9:00
30 18 * * 0Ogni domenica alle 18:30
0 9,18 * * *Ogni giorno alle 9:00 e alle 18:00
0 */6 * * *Ogni 6 ore, allo scoccare dell'ora
*/30 9-17 * * 1-5Ogni 30 minuti dalle 9:00 alle 17:30, da lunedì a venerdì
0 9 1 * *Il giorno 1 di ogni mese alle 9:00
0 10 15 * *Il giorno 15 di ogni mese alle 10:00
0 8 1 1 *Ogni 1° gennaio alle 8:00

Gli orari sono nel timezone del promemoria. Usa solo cinque campi: non aggiungere un campo per i secondi né scorciatoie come @daily.

Variabili di modello#

Questi segnaposto in message vengono sostituiti a ogni esecuzione del promemoria. Date e orari sono nel timezone del promemoria.

VariabileSostituita conEsempio
{current_date}Data2026-10-01
{current_date_formatted}Data in lettereOctober 1, 2026
{current_time}Ora in formato 24 ore09:00:00
{current_time_12h}Ora in formato 12 ore9:00 AM
{current_datetime}Data e ora2026-10-01 09:00:00
{timezone}Il valore di timezoneAsia/Kolkata
{timezone_short}Abbreviazione del fuso orarioIST
{reminder_name}Il valore di reminder_nameMonthly rent reminder
{to_number}Il valore di phone salvato919876543210
{client_name}Nome del tuo spazio di lavoro, come {organisation_name}
{organisation_name}Nome del tuo spazio di lavoro

Promemoria con immagine#

Promemoria settimanale con immagine
curl -X POST https://wbiztool.com/api/v1/reminder/create/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "reminder_name": "Weekly class timetable",
    "phone": "919876543210",
    "msg_type": 1,
    "img_url": "https://example.com/timetable.png",
    "message": "Here is this week'\''s timetable.",
    "cron_expression": "0 8 * * 1",
    "timezone": "Asia/Kolkata"
  }'

L'esempio PHP invia campi di un modulo invece di JSON. Funzionano entrambi.

Risposta#

Una richiesta riuscita restituisce HTTP 200:

{
  "reminder_id": 3187,
  "message": "Reminder created successfully",
  "status": 1
}
CampoTipoDescrizione
statusinteger1 se il promemoria è stato creato, 0 se la richiesta non è riuscita.
messagestringReminder created successfully, altrimenti l'errore.
reminder_idintegerID del nuovo promemoria. Salvalo per annullare il promemoria in seguito. Presente solo in caso di successo.

I nuovi promemoria sono attivi immediatamente.

Errori#

Gli errori restituiscono HTTP 400 con status impostato su 0, salvo dove indicato:

{ "status": 0, "message": "Invalid timezone" }
MessaggioCome risolvere
Invalid JSON format: …Il corpo JSON non è valido, spesso a causa di una virgola finale o di un a capo non codificato in message. Usa \n per andare a capo. Ricevi questo errore anche per una richiesta con campi di un modulo senza client_id, o per qualsiasi richiesta GET.
Invalid client id.Invia client_id come numero.
Reminder name cannot be nullAggiungi reminder_name.
Phone number cannot be nullAggiungi phone.
Phone number was rounded by a spreadsheet (like 9.19877E+11): send all of its digits as textFormatta la colonna dei numeri come testo o come numero intero e invia il numero completo.
Invalid phone number or group nameUn numero deve avere da 7 a 15 cifre, ad esempio 919876543210. Solo zeri, oppure troppe o troppo poche cifre, non sono né un numero né un nome di gruppo.
Message template cannot be nullAggiungi message.
Cron expression cannot be nullAggiungi cron_expression.
Auth Error - Please send correct API key and Client idInvia un api_key non vuoto.
Invalid cron expressionVerifica che l'espressione abbia cinque campi validi. Vedi Espressioni cron.
Invalid timezoneUsa un nome IANA come Asia/Kolkata, non un'abbreviazione come IST.
Image URL cannot be null for image messagesPer msg_type 1, invia img_url.
File URL cannot be null for file messagesPer msg_type 2, invia file_name.
Auth Error: invalid api keyLa chiave non esiste, è stata eliminata o appartiene a un altro client_id. Provala con Verifica credenziali.
Auth Error: please check client idLa chiave non è associata a uno spazio di lavoro. Crea una nuova chiave nello spazio di lavoro che vuoi usare.
Demo Account cannot access APIsUsa un account normale.
Not enough creditsLo spazio di lavoro è sul piano gratuito e non ha più messaggi: i piani a pagamento inviano messaggi illimitati. Vedi Quando finiscono i messaggi.
Upgrade your plan to use reminders featureIl tuo piano non include i promemoria. Passa a un piano superiore.
WhatsApp Logged Out. Please Reconnect!!Il numero whatsapp_client è scollegato. Ricollegalo nelle Impostazioni WhatsApp.
Invalid WhatsApp client idInvia whatsapp_client come numero.
Error creating reminder: … (HTTP 500)Non è stato possibile salvare il promemoria. Controlla i valori inviati, ad esempio che img_url non superi i 1.000 caratteri e file_name i 100.

Come vengono eseguiti i promemoria#

  • La pianificazione viene controllata nel timezone del promemoria e il messaggio viene messo in coda quando l'ora corrente corrisponde all'espressione cron.
  • Ogni esecuzione crea un messaggio normale che viene inviato dal tuo numero WhatsApp, quindi il numero deve restare collegato.
  • Un'esecuzione viene saltata se non è stato impostato alcun whatsapp_client e in quel momento nessun numero del tuo spazio di lavoro è collegato. Un'esecuzione oltre il limite giornaliero del numero (1.000 messaggi in 24 ore) viene creata come messaggio non riuscito con "Daily limit reached: …".
  • Se whatsapp_client è impostato, ogni esecuzione viene messa in coda su quel numero anche se nel frattempo è stato disconnesso, e resta lì in attesa. Non c'è alcun ripiego su un altro numero.
  • I promemoria vengono controllati periodicamente, non al secondo, e il messaggio attende poi nella coda di invio come qualsiasi altro. Non fare affidamento su tempi esatti. Se un controllo viene eseguito in ritardo, l'esecuzione viene comunque inviata fino a 10 minuti dopo (fino a 1 minuto dopo per la prima esecuzione di un promemoria); oltre quel limite viene saltata. La stessa esecuzione non viene mai inviata due volte.

Suggerimenti#

  • Elenca e fai pulizia: ottieni i tuoi promemoria e i relativi ID con Elenca promemoria e fermane uno con Annulla promemoria.
  • Mettere in pausa e modificare non è possibile tramite l'API. Usa la pagina Promemoria della tua dashboard.
  • Molti promemoria insieme: la pagina Promemoria permette anche di importare promemoria da un file CSV.
  • A capo nel JSON: scrivili come \n all'interno di message. Un a capo letterale rende il JSON non valido.