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://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.

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://app.flowella.io/api/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

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

import os, requests

requests.get(
    "https://app.flowella.io/api/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. 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.

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à

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à

​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à

Paginazione

Data e ora

Numeri di telefono

Canali

OpenAPI spec