Introduzione all'API

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://api.flowella.io/v1

Tutti gli endpoint v1 si trovano sotto questa base canonica — ad esempio https://api.flowella.io/v1/messages.

In precedenza l’API si trovava sull’host dell’app all’indirizzo https://app.flowella.io/api/v1/.... Le richieste a quel percorso legacy vengono reindirizzate in modo permanente (308) a https://api.flowella.io/v1/..., preservando metodo e body — le integrazioni esistenti continuano quindi a funzionare. Aggiornate il vostro URL di base non appena possibile per evitare il salto aggiuntivo.

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.

Andare a Impostazioni → Chiavi API nell’app Flowella.
Fare clic su Crea chiave e assegnarle un nome memorabile.
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://api.flowella.io/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});

import os, requests

requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)

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 HTTP	Quando lo vedrete
`400`	Convalida fallita, corpo malformato o rifiuto upstream Meta
`401`	Chiave API mancante o non valida
`402`	Pagamento richiesto - l’abbonamento non copre l’azione
`403`	Vietato - ad esempio, l’invio a un contatto che ha rinunciato o Meta non è connesso
`404`	Il canale o la risorsa richiesti non esistono
`429`	Velocità 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. Quando presente, l’intestazione di risposta Retry-After indica quanti secondi attendere. Ritirarsi e riprovare con un ritardo esponenziale. Se si eseguono grandi invii in massa, preferire POST /v1/templates/send con il parametro throttlePerHour - Flowella applica il throttle lato server, quindi non è necessario ritmare le richieste da soli.

Chiavi di idempotenza

Gli invii massivi di modelli sono asincroni. POST /v1/templates/send convalida la richiesta, la mette in coda in modo durevole e restituisce immediatamente 202 Accepted:

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

Flowella consegna il batch in background e riprova automaticamente in caso di errori temporanei di WhatsApp. I destinatari vengono elaborati singolarmente, quindi un numero non valido non blocca il resto del batch. Seguite l’avanzamento della consegna nella scheda Statistiche del modello nell’app. Poiché la consegna avviene dopo la risposta, i tentativi ripetuti devono essere sicuri. Passate un’intestazione Idempotency-Key (fino a 200 caratteri) che identifichi in modo univoco ogni batch:

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'

Le ripetizioni della stessa chiave entro sette giorni restituiscono l’id del job originale invece di creare un nuovo invio. È possibile riprovare in sicurezza una richiesta dopo un timeout o un errore di rete senza inviare messaggi a nessuno due volte. Se si omette l’intestazione, Flowella deriva una chiave dal corpo della richiesta. Un batch identico inviato due volte in rapida successione non viene quindi inviato due volte. Una chiave esplicita è comunque più sicura, perché qualsiasi modifica al corpo (anche il riordino dei destinatari) produce una nuova chiave derivata.

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://api.flowella.io/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.

Per iniziare

Registro modifiche

Essenziali

Usare l'app

Impostazioni

Configurazione Meta e WhatsApp

Integrazione HubSpot

Flow e campagne

Account e accesso

Sicurezza e privacy

Riferimento API

Risoluzione problemi

Introduzione all'API

URL di base

Autenticazione

Creare una chiave

Verifica di una chiave

Errori

Limiti di velocità

Chiavi di idempotenza

Paginazione

Data e ora

Numeri di telefono

Canali

OpenAPI spec

​URL di base

​Autenticazione

​Creare una chiave

​Verifica di una chiave

​Errori

​Limiti di velocità

​Chiavi di idempotenza

​Paginazione

​Data e ora

​Numeri di telefono

​Canali

​OpenAPI spec

URL di base

Autenticazione

Creare una chiave

Verifica di una chiave

Errori

Limiti di velocità

Chiavi di idempotenza

Paginazione

Data e ora

Numeri di telefono

Canali

OpenAPI spec