Come usare l'API di Papo per gestire i Flow di automazione

Apri in

Visualizza come Markdown

Apri in ChatGPT Apri in Claude

Vitor

Ultimo aggiornamento Oct 19, 2026

Con l'API REST di Papo, puoi elencare tutti i Flow disponibili nel tuo account, attivare o disattivare i percorsi e iscrivere contatti alle automazioni in modo programmatico — tutto tramite richieste autenticate, senza aprire il pannello. È il modo per integrare il motore dei Flow con sistemi esterni, workflow n8n, CRM o script interni.

L'API di Papo espone risorse Flow che permettono di gestire le automazioni così come già gestisci inbox o contatti. Con essa, team di sviluppo, integratori e rivenditori white label riescono a controllare in blocco quali percorsi sono attivi, avviare contatti in sequenze e sincronizzare lo stato delle automazioni con i processi di business.

Riepilogo delle operazioni Flow tramite API

Operazione	Descrizione	Esempio d'uso
Elenca Flow	Restituisce i Flow e le sequenze disponibili, con identificatore, nome, tipo e stato (Attivo/Inattivo).	Verificare le automazioni, sincronizzare con dashboard esterni o controllare cosa è in esecuzione.
Attiva/disattiva Flow	Modifica lo stato di un Flow specifico, sbloccando o mettendo in pausa la ricezione e l'elaborazione dei contatti.	Mettere in pausa un percorso durante la manutenzione, riattivare dopo le modifiche o disattivare una campagna conclusa.
Iscrivi contatto	Inserisce un contatto esistente all'inizio di un Flow attivo, dando inizio al percorso configurato.	Includere lead da CRM esterni, avviare un flusso di benvenuto dopo l'integrazione o correggere inserimenti manuali.

Come funziona l'autenticazione dell'API

Tutte le chiamate all'API, comprese quelle che coinvolgono i Flow, richiedono la chiave segreta dell'account. Deve essere inviata come token Bearer nell'header Authorization. La chiave pubblica dell'account è opzionale, ma se inviata deve corrispondere allo stesso account della chiave segreta.

L'URL base dell'API è https://app.papo.global/api/v1. Le chiavi vengono generate nell'area sviluppatore del pannello Papo. La chiave segreta appare una sola volta alla creazione; conservala in un luogo sicuro e revocala se sospetti una fuga di dati.

Lo schema di autenticazione è lo stesso usato in tutti gli endpoint:

curl https://app.papo.global/api/v1/me \
  -H "Authorization: Bearer sk_live_…" \
  -H "X-Papo-Public-Key: pk_live_…"

Gestire i Flow tramite API in pratica

Sebbene i dettagli esatti di ogni endpoint e parametro siano nella documentazione ufficiale dell'API, il flusso di lavoro generale segue questi passaggi concettuali:

Autenticati con la chiave segreta (e, se desideri, la chiave pubblica) per validare l'account.
Elenca i Flow per ottenere l'elenco attuale dei percorsi, inclusi identificatori e stato. Questo permette di mappare ciò che esiste già e scegliere il Flow corretto per le operazioni successive.
Modifica lo stato di un Flow specifico, se necessario. Invia una richiesta che imposti il Flow come attivo (abilitato a ricevere contatti) o inattivo (in pausa). Solo i Flow attivi elaborano contatti e accettano iscrizioni.
Iscrivi un contatto in un Flow attivo. Indica l'identificatore del contatto e l'identificatore del Flow desiderato per inserirlo all'inizio del percorso. Lo storico del contatto nel CRM viene preservato.
Integra con sistemi esterni — tramite webhook o chiamate dirette, puoi avviare contatti provenienti da un modulo esterno, un evento in un altro sistema o una pipeline di dati.

La piattaforma supporta anche la creazione di Flow vuoti e inattivi e la compilazione dei loro nodi tramite API, permettendo di provisionare automazioni complete in modo programmatico. Per i formati esatti di payload, campi obbligatori ed esempi di codice, consulta la sezione Flow nella documentazione dell'API Papo.

Per chi ha senso questa integrazione

Team IT che gestiscono più automazioni e devono mettere in pausa, riattivare o monitorare Flow in blocco senza accedere manualmente al pannello.
Rivenditori white label che desiderano provisionare percorsi standardizzati per ogni nuovo cliente automaticamente, iscrivere contatti iniziali e mantenere l'allineamento tra piattaforme.
Integratori e sviluppatori che collegano Papo a CRM, ERP o strumenti come n8n, attivando Flow a partire da eventi esterni (un acquisto, una registrazione, un appuntamento).
Operazioni che lavorano con iscrizione condizionale, dove i contatti vengono inclusi nei Flow solo dopo aver superato regole di business definite in altri sistemi.

Domande frequenti

Serve la chiave segreta per elencare i Flow?

Sì. L'elenco dei Flow, così come qualsiasi operazione che restituisce dati dell'account, richiede l'autenticazione con la chiave segreta. Lo schema è lo stesso di tutti gli altri endpoint: invia il token Bearer nell'header Authorization.

Posso attivare o disattivare un Flow tramite API?

Sì. L'API permette di modificare lo stato di un Flow tra attivo e inattivo. Ti servono l'identificatore del Flow e la chiave segreta. I Flow inattivi non ricevono contatti e non avanzano nel percorso, anche se viene tentata un'iscrizione.

Come faccio a iscrivere un contatto a un Flow tramite API?

Fornisci l'identificatore del contatto e l'identificatore del Flow attivo nella chiamata di iscrizione. Il contatto verrà inserito all'inizio del percorso, senza cancellare lo storico delle conversazioni o i dati del profilo. La documentazione ufficiale dettaglia il formato esatto dei parametri.

È possibile creare un Flow da zero tramite API?

Sì. L'API permette di creare un Flow vuoto (solo con il nodo Start) e inattivo, oltre a compilare i suoi nodi con domande, messaggi e condizioni. È utile per provisionare automazioni in modo scalabile, soprattutto in scenari di rivendita o onboarding di nuovi clienti.

L'API restituisce lo stato di ogni Flow durante l'elenco?

Sì. L'elenco include lo stato (Attivo o Inattivo) di ogni Flow e sequenza, oltre a identificatore, nome e tipo, permettendo ai sistemi esterni di monitorare ciò che funziona e ciò che è in pausa.

Dove trovo la documentazione completa delle rotte dei Flow?

La documentazione ufficiale è disponibile su https://papo.global/pt/docs. Lì trovi tutti gli endpoint, i parametri accettati, i codici di errore e esempi in varie lingue. Le rotte dei Flow seguono lo stesso schema REST e autenticazione degli altri moduli.