API REST di Flowella: autenticazione, scope, limiti ed errori

L’API REST di Flowella vi permette di inviare messaggi WhatsApp, gestire contatti e opt-out, lavorare con template e Flows e leggere le analisi dal vostro codice. Questa pagina illustra ciò che dovete sapere prima di chiamare un endpoint. La sezione Endpoints di questo riferimento API documenta le singole richieste. Per l’elenco completo e aggiornato, usate il documento OpenAPI attivo o la documentazione API interattiva nell’app.

URL di base

https://api.flowella.io/v1

Ogni endpoint si trova sotto questa base, ad esempio https://api.flowella.io/v1/messages. Usatela anche dove l’app mostra un indirizzo che termina con /api/v1, come API base URL nel Developer hub.

Le richieste all’host dell’app, https://app.flowella.io/api/v1/..., vengono reindirizzate in modo permanente (308) a https://api.flowella.io/v1/.... Molti client HTTP eliminano l’intestazione Authorization quando seguono un reindirizzamento verso un altro host, quindi la richiesta reindirizzata può non riuscire con 401. Chiamate direttamente https://api.flowella.io/v1.

Autenticazione

Inviate un bearer token nell’intestazione Authorization di ogni richiesta:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Flowella accetta due tipi di token. Entrambi agiscono su una sola organizzazione.

Token	Inizia con	Provenienza	Scope	Scadenza
Chiave API	`flo_`	Settings → API keys, creata da un Owner o da un Admin. Vedere Chiavi API.	Tutti gli scope	Nessuna. Funziona finché non viene revocata.
Token di accesso OAuth	`fla_`	Un’app OAuth registrata in Settings → Developer apps. Vedere Registrare un’app partner con OAuth.	Solo gli scope concessi quando l’app è stata autorizzata	1 ora. Richiedete un nuovo token alla scadenza.

Usate una chiave API per i vostri script e le vostre integrazioni. Usate un’app OAuth quando altre organizzazioni Flowella installano la vostra integrazione.

Trattate chiavi e token come password. Non inseriteli mai nel controllo del codice sorgente e non incollateli in chat o documenti condivisi. Revocate una chiave che non vi serve più in Chiavi API.

Verificare le credenziali

Chiamate l’endpoint ping per confermare che una chiave o un token funzionino:

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"

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

import os
import requests

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

Una risposta 200 OK significa che siete autenticati. organizationId è l’ID numerico della vostra organizzazione:

{
  "ok": true,
  "organizationId": 4821
}

Una risposta 401 ha il codice UNAUTHORIZED e uno di questi messaggi: Missing bearer token, Invalid or expired API key, Invalid or expired access token o Unsupported bearer token.

Scope

Ogni endpoint richiede uno scope. Le chiavi API create nell’app hanno tutti gli scope. I token di accesso OAuth hanno solo gli scope concessi al momento dell’autorizzazione.

Scope	Consente
`messages:read`	Leggere i messaggi.
`messages:write`	Inviare messaggi con `POST /v1/messages`.
`contacts:read`	Leggere contatti e opt-out.
`contacts:write`	Creare, aggiornare ed eliminare contatti, eseguire upsert in blocco e registrare opt-out.
`conversations:read`	Leggere conversazioni e canali WhatsApp.
`conversations:write`	Aggiornare, chiudere e riaprire conversazioni.
`templates:read`	Leggere i template e il loro stato di approvazione.
`templates:write`	Creare, modificare, inviare per approvazione ed eliminare template, eseguire invii di prova e invii in blocco con `POST /v1/templates/send`.
`webhooks:manage`	Gestire webhook, consegne, ripetizioni e segreti di firma.
`analytics:read`	Leggere analisi e utilizzo.
`account:read`	Leggere funzionalità, stato delle integrazioni e dettagli delle richieste.
`flows:read`	Leggere i Flows e il loro stato di sincronizzazione.
`flows:write`	Creare, modificare, pubblicare ed eliminare Flows e configurare i provider di moduli.
`forms:ingest`	Inviare e leggere invii di moduli, inclusi i webhook di moduli in entrata.
`events:read`	Leggere il feed degli eventi con `GET /v1/events`.
`jobs:read`	Leggere i job in background e i loro risultati.
`jobs:write`	Annullare i job in background.
`sandbox:manage`	Leggere e modificare l’impostazione della sandbox e usare gli strumenti di test della sandbox.

GET /v1/ping e GET /v1/rate-limits non richiedono alcuno scope. GET /v1/capabilities (scope account:read) elenca gli scope del vostro token. Una richiesta priva dello scope necessario restituisce 403 con il codice INSUFFICIENT_SCOPE. details.required elenca gli scope mancanti:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Token is missing required scope(s)",
    "requestId": "req_5b1e0c2a-8f3d-4e6a-9c7b-2d4f6a8e0b1c",
    "details": { "required": ["webhooks:manage"] }
  }
}

Errori

Gli errori usano la stessa struttura. requestId identifica la richiesta quando contattate il supporto e details contiene informazioni aggiuntive, come problemi di validazione, quando presenti:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Stato HTTP	`error.code`	Quando compare
`400`	`BAD_REQUEST`	La richiesta non ha superato la validazione, la `API-Version` non è supportata oppure la `Idempotency-Key` ha una lunghezza errata.
`400`	`META_ERROR`	Meta ha rifiutato la richiesta.
`400`	`INVALID_TEMPLATE_NAME`, `INVALID_TEMPLATE_COMPONENTS`	Il nome o i componenti del template non sono validi.
`401`	`UNAUTHORIZED`	Il bearer token è mancante, non valido, revocato o scaduto.
`402`	`PAYMENT_REQUIRED`	Il pagamento del vostro abbonamento è scaduto.
`403`	`INSUFFICIENT_SCOPE`	Il vostro token non ha uno scope richiesto dall’endpoint.
`403`	`FORBIDDEN`	L’azione non è consentita, ad esempio inviare a un contatto che ha fatto opt-out su quel numero, oppure il vostro abbonamento non è attivo.
`404`	`NOT_FOUND`	La risorsa non esiste nella vostra organizzazione.
`409`	`CONFLICT`, `IDEMPOTENCY_KEY_CONFLICT`, `IDEMPOTENCY_KEY_IN_FLIGHT`	Un valore duplicato, come un `externalId`, oppure un conflitto di chiave di idempotenza.
`429`	`RATE_LIMITED`	Avete inviato troppe richieste. Vedere Limiti di frequenza.
`500`	`INTERNAL_ERROR`, `INTERNAL_SERVER_ERROR`	Si è verificato un problema lato Flowella. Riprovate più tardi e comunicate il `requestId` al supporto.

Il valore error.code è stabile, quindi il vostro codice può farvi affidamento. Il testo error.message è destinato alle persone e può cambiare.

Limiti di frequenza

Ogni chiave API e ogni token di accesso OAuth ha un proprio limite di richieste al minuto. Flowella conteggia le richieste in finestre fisse di un minuto che iniziano allo scoccare del minuto (UTC). Le risposte alle richieste che superano i controlli di autenticazione e di scope includono queste intestazioni:

Intestazione	Significato
`X-RateLimit-Limit`	Richieste consentite in ogni finestra.
`X-RateLimit-Remaining`	Richieste rimanenti nella finestra corrente.
`X-RateLimit-Reset`	Quando termina la finestra corrente, in secondi Unix.

Quando superate il limite, Flowella restituisce 429 con il codice RATE_LIMITED e un’intestazione Retry-After con il numero di secondi da attendere. GET /v1/rate-limits restituisce i vostri valori limit, remaining e reset in formato JSON. Per invii di grandi dimensioni, usate POST /v1/templates/send, che accetta fino a 50.000 destinatari in un’unica richiesta. La richiesta accetta anche un campo facoltativo throttlePerHour, un numero intero da 1 a 100.000, ma al momento non regola il ritmo degli invii, quindi non fatevi affidamento. Per distribuire un invio di grandi dimensioni nel tempo, suddividete l’elenco dei destinatari in lotti più piccoli e inviate ciascun lotto separatamente.

ID delle richieste

Le risposte includono un’intestazione X-Request-Id e i corpi degli errori la ripetono come error.requestId. POST /v1/templates/send fa eccezione: vedere Invii di template in blocco. Per usare un vostro ID, inviate un’intestazione X-Request-Id di massimo 128 caratteri e Flowella la riutilizza. Comunicate l’ID della richiesta quando contattate il supporto. Per cercare autonomamente una richiesta, chiamate GET /v1/requests/{requestId} (scope account:read): restituisce la richiesta registrata con gli eventi, i job e le consegne webhook collegati. Il Developer hub elenca le richieste recenti e i relativi ID.

Idempotenza

Le chiavi di idempotenza vi permettono di ripetere una richiesta di scrittura dopo un timeout o un errore di rete senza eseguire il lavoro due volte. POST /v1/templates/send segue regole proprie, descritte più avanti.

La maggior parte delle richieste di scrittura

Le richieste POST, PATCH, PUT e DELETE accettano un’intestazione facoltativa Idempotency-Key:

La chiave deve contenere da 8 a 255 caratteri. Altre lunghezze restituiscono 400.
Flowella ricorda ogni chiave per la vostra organizzazione per 24 ore.
Una ripetizione con la stessa chiave, lo stesso metodo, lo stesso percorso e lo stesso corpo restituisce la risposta memorizzata senza eseguire di nuovo la richiesta.
Una ripetizione con la stessa chiave ma con metodo, percorso o corpo diversi restituisce 409 IDEMPOTENCY_KEY_CONFLICT.
Una ripetizione inviata mentre la prima richiesta è ancora in esecuzione restituisce 409 IDEMPOTENCY_KEY_IN_FLIGHT. Attendete e riprovate.
Le risposte riportano la chiave in un’intestazione Idempotency-Key.

Le richieste senza l’intestazione vengono eseguite normalmente, senza protezione contro i duplicati.

Invii di template in blocco

Gli invii di template in blocco sono asincroni. POST /v1/templates/send convalida la richiesta, la mette in coda in modo persistente e restituisce subito 202 Accepted:

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

Flowella consegna il lotto in background e ripete automaticamente gli errori temporanei di WhatsApp. I destinatari vengono elaborati singolarmente, quindi un numero non valido non blocca il resto del lotto. Seguite l’avanzamento delle consegne nella scheda Statistics del template nell’app. Passate un’intestazione Idempotency-Key che identifichi ciascun lotto:

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

Questo endpoint gestisce le chiavi in modo diverso dalle altre richieste di scrittura:

La chiave può contenere fino a 200 caratteri. Una chiave più lunga restituisce 400.
Una ripetizione con la stessa chiave entro 7 giorni restituisce l’id originale e non invia nulla, anche se il corpo è cambiato.
Senza l’intestazione, Flowella usa come chiave un hash del corpo della richiesta. Se inviate di nuovo un corpo identico byte per byte entro 7 giorni, ricevete l’id originale e non viene inviato nulla. Usate una nuova chiave per ogni lotto che intendete inviare.

Anche altri comportamenti di questo endpoint sono diversi:

Chiamatelo con una chiave API. I token di accesso OAuth vengono rifiutati con 401.
Le sue risposte non includono le intestazioni X-Request-Id, API-Version o X-RateLimit-*. Le sue richieste contano comunque ai fini del limite di frequenza della chiave.

Versioni

Potete fissare la versione dell’API con l’intestazione API-Version:

API-Version: 2026-08-11

2026-08-11 è l’unica versione supportata ed è quella predefinita quando omettete l’intestazione. Qualsiasi altro valore, o un valore che non è una data YYYY-MM-DD, restituisce 400 con il messaggio Unsupported API-Version. Le risposte riportano la versione nelle intestazioni API-Version e X-Flowella-Api-Version.

Sandbox

La sandbox vi permette di testare un’integrazione senza inviare nulla a WhatsApp. Funziona sulla vostra organizzazione reale: non esiste un account di test separato. Potete usarla in due modi:

Una chiave sandbox, che riguarda solo le richieste effettuate con quella chiave. Vedere Chiavi sandbox.
L’API sandbox a livello di organizzazione nel Developer hub, che un Owner o un Admin può attivare. Vedere API sandbox.

Quando la sandbox è attiva, POST /v1/messages memorizza il messaggio e restituisce "sandbox": true senza contattare Meta, e l’invio di un template per approvazione restituisce una decisione simulata immediata. Gli strumenti di test della sandbox in /v1/test/ e /v1/sandbox richiedono lo scope sandbox:manage.

Paginazione

Gli endpoint di elenco, come /v1/conversations, /v1/contacts e /v1/templates, usano la paginazione a cursore:

Passate limit (da 1 a 100, predefinito 25) e un cursor facoltativo.
La risposta contiene items e, quando ci sono altri risultati, un nextCursor.
Passate nextCursor come parametro cursor per recuperare la pagina successiva.
Quando nextCursor è assente o null, avete raggiunto la fine.

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"

Data e ora

Tutti i timestamp sono stringhe ISO 8601 in UTC, ad esempio 2025-01-15T14:30:00.000Z. Dove l’API accetta date, funzionano sia i valori con la sola data (2025-01-15) sia i valori ISO 8601 completi.

Numeri di telefono

Passate i numeri di telefono in formato E.164 (+15551234567) quando possibile. Flowella normalizza le varianti più comuni, ma E.164 è il formato più sicuro.

Canali

Molti endpoint accettano un whatsappChannelId. Se la vostra organizzazione ha un solo canale e lo omettete, Flowella usa il canale predefinito. Se avete più canali, passate l’ID in modo esplicito per non inviare dal numero sbagliato. Per lo schema completo degli URL e il cambio di canale, vedere Multicanale.

Specifica OpenAPI

La specifica attiva e leggibile dalle macchine è pubblica:

https://api.flowella.io/v1/openapi.json

Importatela in Postman, Insomnia o in un generatore di codice. Descrive sia l’autenticazione con chiave API sia quella OAuth.

Risorse per sviluppatori

L’app offre altro materiale per sviluppatori. Queste pagine sono pubbliche, quindi potete aprirle senza accedere:

Risorsa	Indirizzo
Documentazione API interattiva, con richieste di prova	`https://app.flowella.io/docs`
Collezione Postman (scarica un file `.json`)	`https://app.flowella.io/docs/postman`
Guida alla sandbox	`https://app.flowella.io/docs/sandbox`
Guide rapide in Markdown per Salesforce, Zoho CRM, SurveyMonkey, Typeform e n8n	`https://app.flowella.io/docs/quickstarts/salesforce`, con `zoho`, `surveymonkey`, `typeform` o `n8n` al posto di `salesforce`

Il Developer hub in Settings riunisce questi link insieme alle vostre richieste API recenti e all’interruttore dell’API sandbox.

Abbinate questa pagina al riferimento sui webhook per reagire agli eventi invece di interrogare periodicamente le modifiche.

Per iniziare

Essenziali

Usare l'app

Impostazioni

Configurazione Meta e WhatsApp

Integrazione HubSpot

Flow e campagne

Riferimento API

Risoluzione problemi

Registro modifiche

API REST di Flowella: autenticazione, scope, limiti ed errori

URL di base

Autenticazione

Verificare le credenziali

Scope

Errori

Limiti di frequenza

ID delle richieste

Idempotenza

La maggior parte delle richieste di scrittura

Invii di template in blocco

Versioni

Sandbox

Paginazione

Data e ora

Numeri di telefono

Canali

Specifica OpenAPI

Risorse per sviluppatori

​URL di base

​Autenticazione

​Verificare le credenziali

​Scope

​Errori

​Limiti di frequenza

​ID delle richieste

​Idempotenza

​La maggior parte delle richieste di scrittura

​Invii di template in blocco

​Versioni

​Sandbox

​Paginazione

​Data e ora

​Numeri di telefono

​Canali

​Specifica OpenAPI

​Risorse per sviluppatori

URL di base

Autenticazione

Verificare le credenziali

Scope

Errori

Limiti di frequenza

ID delle richieste

Idempotenza

La maggior parte delle richieste di scrittura

Invii di template in blocco

Versioni

Sandbox

Paginazione

Data e ora

Numeri di telefono

Canali

Specifica OpenAPI

Risorse per sviluppatori