Vai al contenuto principale
L’API REST di Flowella consente di inviare messaggi WhatsApp, gestire i contatti e gli opt-out, i modelli di elenco e di invio massivo e le analisi - in modo programmatico. Questa pagina illustra tutto ciò che è necessario sapere prima di chiamare un endpoint. Il riferimento completo all’endpoint si trova nella barra laterale riferimento dell’API (generato automaticamente dalle specifiche OpenAPI).

​
URL di base

https://app.flowella.io
Tutti gli endpoint v1 sono sotto /api/v1.

​
Autenticazione

Ogni richiesta necessita di una chiave API nell’intestazione Authorization: 
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
Le chiavi sono a livello di organizzazione: agiscono su una singola organizzazione Flowella ed ereditano i permessi di un amministratore in quella organizzazione.
Trattate le chiavi come le password. Non eseguite mai il commit nel controllo sorgente, non incollatele in chat o nei documenti condivisi e ruotatele quando i compagni di squadra lasciano l’organizzazione. Vedere Impostazioni → Chiavi API per le fasi di rotazione.

​
Creare una chiave

Per gestire le chiavi API è necessario il ruolo Owner o Admin.
  1. Andare a Impostazioni → Chiavi API nell’app Flowella.
  2. Fare clic su Crea chiave e assegnarle un nome memorabile.
  3. Copiare la chiave una sola volta: viene visualizzata solo al momento della creazione.
Trattate le chiavi come le password: non impegnatele mai nel controllo sorgente, non incollatele mai in chat e ruotatele quando i compagni di squadra lasciano l’organizzazione.

​
Verifica di una chiave

Per confermare la validità di una chiave, si può utilizzare l’endpoint ping: 
curl https://app.flowella.io/api/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
Un 200 OK con { "ok": true, "organizationId": "…" } significa che l’utente è autenticato.

​
Errori

Tutti gli errori vengono restituiti in una busta coerente: 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
Stato HTTPQuando lo vedrete
400Convalida fallita, corpo malformato o rifiuto upstream Meta
401Chiave API mancante o non valida
402Pagamento richiesto - l’abbonamento non copre l’azione
403Vietato - ad esempio, l’invio a un contatto che ha rinunciato o Meta non è connesso
404Il canale o la risorsa richiesti non esistono
429Velocità limitata - rallentare
Il campo error.code è stabile e sicuro da attivare programmaticamente. Il campo error.message è leggibile dall’uomo e può cambiare.

​
Limiti di velocità

Le chiavi API hanno un limite di velocità per organizzazione. Se si supera il limite, si riceve un 429 con il codice RATE_LIMITED e il messaggio Too many requests. Ritirarsi e riprovare con un ritardo esponenziale. Se si eseguono grandi invii in massa, preferire POST /api/v1/templates/send con il parametro throttlePerHour - Flowella applica il throttle lato server, quindi non è necessario ritmare le richieste da soli.

​
Paginazione

Gli endpoint elenco (/conversations, /contacts, /templates) utilizzano la paginazione a cursore:
  • Passare limit (1-100, valore predefinito 25) e un cursor opzionale.
  • La risposta contiene items e, se ci sono più risultati, nextCursor.
  • Passare nextCursor come parametro cursor per recuperare la pagina successiva.
  • Quando manca nextCursor, si è giunti alla fine.
curl "https://app.flowella.io/api/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

​
Data e ora

Tutti i timestamp sono stringhe ISO 8601 in UTC (ad esempio 2025-01-15T14:30:00.000Z). Quando l’API accetta date, sia la sola data (2025-01-15) che l’intero ISO 8601 sono forzati dal lato server.

​
Numeri di telefono

Passare i numeri di telefono nella forma E.164 (+15551234567), ove possibile. Flowella normalizzerà le varianti più comuni lato server, ma E.164 è più sicuro.

​
Canali

Molti endpoint accettano un whatsappChannelId. Se la vostra organizzazione ha un solo canale e lo omettete, Flowella utilizzerà il vostro canale predefinito. Se avete più canali, passate esplicitamente l’ID per evitare di inviare dal mittente sbagliato. Per lo schema URL completo e il cambio di canale, vedere Multi-channel.

​
OpenAPI spec

Le specifiche leggibili in macchina si trovano in: 
/api-reference/openapi.json
Inseritelo in Postman, Insomnia o nel vostro generatore di codice preferito.
State costruendo un’integrazione? Abbinate questa pagina a Webhooks per reagire agli eventi invece di eseguire il polling dello stato.