Documentazione API

Integra promemoria WhatsApp automatici nella tua applicazione con le API REST di WeRemind. Esempi di codice in cURL, JavaScript e Python.

Base URLhttps://api.weremind.it/v1

Introduzione

L'API REST di WeRemind ti permette di integrare promemoria WhatsApp automatici nel tuo CRM, gestionale o applicazione. Tutte le richieste usano il base URL https://api.weremind.it/v1 e restituiscono risposte in formato JSON.

L'API segue il versionamento semantico. La versione corrente e v1. Le modifiche breaking verranno rilasciate con un nuovo prefisso di versione (es. /v2), garantendo la retrocompatibilita per le versioni esistenti per almeno 12 mesi.

Autenticazione

Ogni richiesta API deve includere una API key nel header Authorization con il formato Bearer token.

Authorization: Bearer YOUR_API_KEY

Puoi generare e gestire le tue API key dalla dashboard WeRemind in Impostazioni > API. Le chiavi possono avere permessi granulari (sola lettura, lettura/scrittura) e possono essere revocate in qualsiasi momento.

Sicurezza: Non condividere mai le tue API key nel codice client-side, repository pubblici o comunicazioni non sicure. Usa variabili d'ambiente per gestirle in modo sicuro.

Contatti

Gestisci la rubrica dei contatti a cui inviare promemoria WhatsApp.

GET/v1/contactsAuth

Restituisce la lista paginata dei contatti associati al tuo account.

Parametri

Nome	Tipo	Richiesto	Descrizione
page	integer	No	Numero di pagina (default 1)(default: 1)
per_page	integer	No	Risultati per pagina (max 100)(default: 25)
search	string	No	Cerca per nome o numero di telefono

Campi risposta

Campo	Tipo	Descrizione
data	Contact[]	Array di contatti
meta	PaginationMeta	Metadati paginazione

Esempi di codice

curl -X GET "https://api.weremind.it/v1/contacts?page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio risposta

{
  "data": [
    {
      "id": "cnt_01H8X...",
      "name": "Marco Rossi",
      "phone": "+393331234567",
      "email": "marco.rossi@example.it",
      "tags": [
        "cliente",
        "premium"
      ],
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 142
  }
}

GET/v1/contacts/:idAuth

Restituisce i dettagli di un singolo contatto.

Parametri

Nome	Tipo	Richiesto	Descrizione
id	string	Si	ID univoco del contatto

Campi risposta

Campo	Tipo	Descrizione
id	string	ID univoco
name	string	Nome completo
phone	string	Numero WhatsApp
email	string	Email (opzionale)
tags	string[]	Tag associati
created_at	string	Data creazione ISO 8601

Esempi di codice

curl -X GET "https://api.weremind.it/v1/contacts/cnt_01H8X" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio risposta

{
  "id": "cnt_01H8X...",
  "name": "Marco Rossi",
  "phone": "+393331234567",
  "email": "marco.rossi@example.it",
  "tags": [
    "cliente",
    "premium"
  ],
  "created_at": "2025-01-15T10:30:00Z"
}

POST/v1/contactsAuth

Crea un nuovo contatto nella rubrica.

Corpo richiesta

Campo	Tipo	Descrizione
name	string	Nome completo (obbligatorio)
phone	string	Numero WhatsApp con prefisso internazionale
email	string	Indirizzo email (opzionale)
tags	string[]	Tag da associare (opzionale)

Campi risposta

Campo	Tipo	Descrizione
id	string	ID del nuovo contatto
name	string	Nome completo
phone	string	Numero WhatsApp
created_at	string	Data creazione

Esempi di codice

curl -X POST "https://api.weremind.it/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Giulia Bianchi",
    "phone": "+393489876543",
    "email": "giulia.bianchi@example.it",
    "tags": ["nuovo-cliente"]
  }'

Esempio richiesta

{
  "name": "Giulia Bianchi",
  "phone": "+393489876543",
  "email": "giulia.bianchi@example.it",
  "tags": [
    "nuovo-cliente"
  ]
}

Esempio risposta

{
  "id": "cnt_01H9Y...",
  "name": "Giulia Bianchi",
  "phone": "+393489876543",
  "email": "giulia.bianchi@example.it",
  "tags": [
    "nuovo-cliente"
  ],
  "created_at": "2025-02-01T14:00:00Z"
}

PUT/v1/contacts/:idAuth

Aggiorna i campi di un contatto esistente. Invia solo i campi da modificare.

Parametri

Nome	Tipo	Richiesto	Descrizione
id	string	Si	ID univoco del contatto

Corpo richiesta

Campo	Tipo	Descrizione
name	string	Nome completo
phone	string	Numero WhatsApp
email	string	Indirizzo email
tags	string[]	Tag aggiornati

Campi risposta

Campo	Tipo	Descrizione
id	string	ID contatto
name	string	Nome aggiornato
updated_at	string	Data aggiornamento

Esempi di codice

curl -X PUT "https://api.weremind.it/v1/contacts/cnt_01H8X" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marco Rossi", "tags": ["cliente", "vip"]}'

Esempio richiesta

{
  "name": "Marco Rossi",
  "tags": [
    "cliente",
    "vip"
  ]
}

Esempio risposta

{
  "id": "cnt_01H8X...",
  "name": "Marco Rossi",
  "phone": "+393331234567",
  "email": "marco.rossi@example.it",
  "tags": [
    "cliente",
    "vip"
  ],
  "updated_at": "2025-02-10T09:15:00Z"
}

DELETE/v1/contacts/:idAuth

Elimina permanentemente un contatto e i suoi promemoria futuri.

Parametri

Nome	Tipo	Richiesto	Descrizione
id	string	Si	ID univoco del contatto

Campi risposta

Campo	Tipo	Descrizione
deleted	boolean	Conferma eliminazione

Esempi di codice

curl -X DELETE "https://api.weremind.it/v1/contacts/cnt_01H8X" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio risposta

{
  "deleted": true
}

Promemoria

Crea e gestisci promemoria WhatsApp automatici per i tuoi contatti.

GET/v1/remindersAuth

Restituisce la lista paginata dei promemoria programmati e inviati.

Parametri

Nome	Tipo	Richiesto	Descrizione
page	integer	No	Numero di pagina(default: 1)
per_page	integer	No	Risultati per pagina(default: 25)
status	string	No	Filtra per stato: scheduled, sent, failed, cancelled
contact_id	string	No	Filtra per contatto specifico

Campi risposta

Campo	Tipo	Descrizione
data	Reminder[]	Array di promemoria
meta	PaginationMeta	Metadati paginazione

Esempi di codice

curl -X GET "https://api.weremind.it/v1/reminders?status=scheduled" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio risposta

{
  "data": [
    {
      "id": "rem_01H9Z...",
      "contact_id": "cnt_01H8X...",
      "template_id": "tpl_01H7W...",
      "title": "Rinnovo polizza auto",
      "scheduled_at": "2025-03-01T09:00:00Z",
      "status": "scheduled",
      "created_at": "2025-01-20T16:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 89
  }
}

GET/v1/reminders/:idAuth

Restituisce i dettagli di un singolo promemoria.

Parametri

Nome	Tipo	Richiesto	Descrizione
id	string	Si	ID univoco del promemoria

Campi risposta

Campo	Tipo	Descrizione
id	string	ID univoco
contact_id	string	ID contatto associato
template_id	string	ID template utilizzato
title	string	Titolo del promemoria
scheduled_at	string	Data/ora programmata
sent_at	string \| null	Data/ora invio effettivo
status	string	Stato: scheduled, sent, failed, cancelled

Esempi di codice

curl -X GET "https://api.weremind.it/v1/reminders/rem_01H9Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio risposta

{
  "id": "rem_01H9Z...",
  "contact_id": "cnt_01H8X...",
  "template_id": "tpl_01H7W...",
  "title": "Rinnovo polizza auto",
  "message": "Gentile Marco, la sua polizza auto scade il 15/03/2025. Contatti lo studio per il rinnovo.",
  "scheduled_at": "2025-03-01T09:00:00Z",
  "sent_at": null,
  "status": "scheduled",
  "created_at": "2025-01-20T16:00:00Z"
}

POST/v1/remindersAuth

Programma un nuovo promemoria WhatsApp per un contatto.

Corpo richiesta

Campo	Tipo	Descrizione
contact_id	string	ID del contatto destinatario
template_id	string	ID del template da utilizzare
title	string	Titolo del promemoria
scheduled_at	string	Data/ora di invio (ISO 8601)
variables	Record<string, string>	Variabili per il template (opzionale)

Campi risposta

Campo	Tipo	Descrizione
id	string	ID del nuovo promemoria
status	string	Stato iniziale (scheduled)
scheduled_at	string	Data/ora programmata

Esempi di codice

curl -X POST "https://api.weremind.it/v1/reminders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "cnt_01H8X...",
    "template_id": "tpl_01H7W...",
    "title": "Visita di controllo",
    "scheduled_at": "2025-04-10T08:30:00Z",
    "variables": {
      "nome": "Marco",
      "data_appuntamento": "10 aprile 2025",
      "ora": "09:30"
    }
  }'

Esempio richiesta

{
  "contact_id": "cnt_01H8X...",
  "template_id": "tpl_01H7W...",
  "title": "Visita di controllo",
  "scheduled_at": "2025-04-10T08:30:00Z",
  "variables": {
    "nome": "Marco",
    "data_appuntamento": "10 aprile 2025",
    "ora": "09:30"
  }
}

Esempio risposta

{
  "id": "rem_01HAB...",
  "contact_id": "cnt_01H8X...",
  "template_id": "tpl_01H7W...",
  "title": "Visita di controllo",
  "scheduled_at": "2025-04-10T08:30:00Z",
  "status": "scheduled",
  "created_at": "2025-02-15T11:00:00Z"
}

PUT/v1/reminders/:idAuth

Modifica un promemoria programmato (solo se non ancora inviato).

Parametri

Nome	Tipo	Richiesto	Descrizione
id	string	Si	ID univoco del promemoria

Corpo richiesta

Campo	Tipo	Descrizione
title	string	Nuovo titolo
scheduled_at	string	Nuova data/ora
variables	Record<string, string>	Variabili aggiornate

Campi risposta

Campo	Tipo	Descrizione
id	string	ID promemoria
status	string	Stato aggiornato
updated_at	string	Data aggiornamento

Esempi di codice

curl -X PUT "https://api.weremind.it/v1/reminders/rem_01H9Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2025-04-12T10:00:00Z"}'

Esempio richiesta

{
  "scheduled_at": "2025-04-12T10:00:00Z",
  "variables": {
    "ora": "11:00"
  }
}

Esempio risposta

{
  "id": "rem_01H9Z...",
  "scheduled_at": "2025-04-12T10:00:00Z",
  "status": "scheduled",
  "updated_at": "2025-02-16T09:00:00Z"
}

DELETE/v1/reminders/:idAuth

Cancella un promemoria programmato (solo se non ancora inviato).

Parametri

Nome	Tipo	Richiesto	Descrizione
id	string	Si	ID univoco del promemoria

Campi risposta

Campo	Tipo	Descrizione
deleted	boolean	Conferma cancellazione

Esempi di codice

curl -X DELETE "https://api.weremind.it/v1/reminders/rem_01H9Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio risposta

{
  "deleted": true
}

Template

Visualizza i template di messaggio disponibili per i promemoria.

GET/v1/templatesAuth

Restituisce tutti i template disponibili per il tuo account.

Parametri

Nome	Tipo	Richiesto	Descrizione
category	string	No	Filtra per categoria: standard, custom, vertical

Campi risposta

Campo	Tipo	Descrizione
data	Template[]	Array di template

Esempi di codice

curl -X GET "https://api.weremind.it/v1/templates?category=standard" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio risposta

{
  "data": [
    {
      "id": "tpl_01H7W...",
      "name": "Promemoria appuntamento",
      "category": "standard",
      "body": "Gentile {{nome}}, le ricordiamo il suo appuntamento del {{data_appuntamento}} alle ore {{ora}}.",
      "variables": [
        "nome",
        "data_appuntamento",
        "ora"
      ],
      "created_at": "2024-12-01T00:00:00Z"
    }
  ]
}

GET/v1/templates/:idAuth

Restituisce i dettagli di un singolo template.

Parametri

Nome	Tipo	Richiesto	Descrizione
id	string	Si	ID univoco del template

Campi risposta

Campo	Tipo	Descrizione
id	string	ID univoco
name	string	Nome del template
category	string	Categoria
body	string	Testo con variabili {{...}}
variables	string[]	Lista variabili richieste

Esempi di codice

curl -X GET "https://api.weremind.it/v1/templates/tpl_01H7W" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio risposta

{
  "id": "tpl_01H7W...",
  "name": "Promemoria appuntamento",
  "category": "standard",
  "body": "Gentile {{nome}}, le ricordiamo il suo appuntamento del {{data_appuntamento}} alle ore {{ora}}.",
  "variables": [
    "nome",
    "data_appuntamento",
    "ora"
  ],
  "created_at": "2024-12-01T00:00:00Z"
}

Messaggi

Consulta lo storico dei messaggi WhatsApp inviati dal tuo account.

GET/v1/messagesAuth

Restituisce lo storico dei messaggi inviati con filtri per stato, contatto e periodo.

Parametri

Nome	Tipo	Richiesto	Descrizione
page	integer	No	Numero di pagina(default: 1)
per_page	integer	No	Risultati per pagina(default: 25)
status	string	No	Filtra per stato: delivered, read, failed
contact_id	string	No	Filtra per contatto specifico
from	string	No	Data inizio periodo (ISO 8601)
to	string	No	Data fine periodo (ISO 8601)

Campi risposta

Campo	Tipo	Descrizione
data	Message[]	Array di messaggi
meta	PaginationMeta	Metadati paginazione

Esempi di codice

curl -X GET "https://api.weremind.it/v1/messages?status=delivered&from=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio risposta

{
  "data": [
    {
      "id": "msg_01HBC...",
      "reminder_id": "rem_01H9Z...",
      "contact_id": "cnt_01H8X...",
      "contact_name": "Marco Rossi",
      "body": "Gentile Marco, le ricordiamo il rinnovo della polizza auto in scadenza il 15/03/2025.",
      "status": "delivered",
      "sent_at": "2025-03-01T09:00:00Z",
      "delivered_at": "2025-03-01T09:00:05Z",
      "read_at": "2025-03-01T09:15:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1247
  }
}

Gestione errori

L'API utilizza codici di stato HTTP standard per indicare il risultato delle richieste.

Codice	Significato	Descrizione
200	OK	Richiesta completata con successo
201	Created	Risorsa creata con successo
400	Bad Request	Parametri mancanti o non validi
401	Unauthorized	API key mancante o non valida
403	Forbidden	Permessi insufficienti per questa operazione
404	Not Found	Risorsa non trovata
422	Unprocessable Entity	Dati validi ma non elaborabili
429	Too Many Requests	Limite di richieste superato
500	Internal Server Error	Errore interno del server

Formato risposta errore:

{
  "error": {
    "code": "validation_error",
    "message": "Il campo phone non e in un formato valido.",
    "details": [
      {
        "field": "phone",
        "message": "Deve includere il prefisso internazionale (es. +39)"
      }
    ]
  }
}

Rate limits

Le richieste API sono soggette a limiti per piano per garantire la stabilita del servizio.

Piano	Limite richieste	Periodo
Individual	60 req	al minuto
Starter	120 req	al minuto
Professional	300 req	al minuto
Business	600 req	al minuto

Ogni risposta include header informativi sul tuo utilizzo corrente:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1709312400

Quando superi il limite, riceverai una risposta 429 Too Many Requests con l'header Retry-After che indica i secondi di attesa prima di riprovare.