**Con Papo (https://papo.global/), puoi usare l'API REST per elencare conversazioni, inviare messaggi di testo, applicare etichette e assegnare conversazioni agli agenti, automatizzando i processi di assistenza senza accedere all'interfaccia. L'API offre endpoint che rispecchiano le funzionalità del modulo Conversazioni, consentendo a sistemi esterni di gestire le interazioni in modo programmatico.**

| Azione API | Cosa fa | Esempio d'uso |
| :--- | :--- | :--- |
| Elencare conversazioni | Restituisce le conversazioni dell'account, con filtri per stato, etichetta o agente | Monitorare assistenze attive o chiuse da un CRM esterno |
| Inviare messaggio di testo | Invia un messaggio di testo a un contatto (rispettando la finestra di 24h di WhatsApp) | Notificare un cliente sull'aggiornamento dell'ordine |
| Applicare etichetta | Crea un'etichetta (se non esiste) e la applica al contatto e alla conversazione aperta | Contrassegnare conversazioni come "Urgente" o "Post-vendita" automaticamente |
| Assegnare conversazione | Assegna le conversazioni aperte di un contatto a un agente specifico | Indirizzare i lead al venditore responsabile della regione |

## Come funziona l'API Conversazioni di Papo

L'API di Papo segue lo standard REST, con autenticazione tramite chiave segreta (Bearer token) e risposte in JSON. Tutte le operazioni descritte qui utilizzano la stessa base di autenticazione e possono essere combinate per creare flussi di lavoro automatizzati — ad esempio, un sistema di smistamento che, quando riceve un nuovo lead, elenca le conversazioni recenti, applica un'etichetta di "Nuovo" e assegna all'agente di turno.

La base dell'API è `https://app.papo.global/api/v1`. Per utilizzare gli endpoint di conversazioni, etichette e assegnazioni, è necessario un token API generato nel pannello di Papo. La documentazione completa con gli endpoint specifici e i parametri è disponibile su [papo.global/pt/docs](https://papo.global/pt/docs).

## Passo passo per utilizzare le risorse dell'API

### 1. Genera un token API
Nel pannello di Papo, accedi alla sezione sviluppatore o token di accesso. Crea una chiave segreta (sk_live_…) con le autorizzazioni appropriate per gestire le conversazioni. Conserva il token in un luogo sicuro — verrà inviato nell'intestazione `Authorization` di tutte le richieste.

### 2. Elenca le conversazioni
Utilizza l'endpoint di elenco delle conversazioni per ottenere le assistenze dell'account. La richiesta accetta parametri di filtro come:
- **Stato**: conversazioni aperte, chiuse o tutte.
- **Etichetta**: filtra per una o più etichette applicate.
- **Agente**: limita alle conversazioni assegnate a un utente specifico.
- **Periodo**: intervallo di date per limitare la query.

La risposta include l'identificatore della conversazione, il contatto, il canale, lo stato e gli ultimi messaggi. Con questi dati, puoi monitorare il volume delle assistenze o attivare azioni condizionali da un sistema esterno.

### 3. Invia un messaggio di testo
Per inviare un messaggio di testo a un contatto, utilizza l'endpoint di invio messaggi. La richiesta richiede:
- **Numero del destinatario** in formato internazionale (es.: `5511999999999`).
- **Testo del messaggio**.
- **Identificatore dell'istanza** (opzionale) — se il tuo account ha più di una connessione WhatsApp, puoi specificare quale utilizzare.

L'API restituisce una conferma che la richiesta è stata accettata. Ricorda che l'invio di messaggi di testo è soggetto alla finestra di 24 ore di WhatsApp; per comunicazioni al di fuori di questo periodo, è necessario utilizzare modelli di messaggio (HSM) precedentemente approvati.

### 4. Applica etichette a contatti e conversazioni
L'API consente di gestire le etichette in due modi:
- **Creare un'etichetta nell'account**: definisci un titolo, un colore e una descrizione per la nuova etichetta.
- **Applicare un'etichetta**: associa un'etichetta esistente a un contatto e alla conversazione aperta di quel contatto. Se l'etichetta non esiste ancora, verrà creata automaticamente durante l'applicazione.

Questo è utile per classificare automaticamente le conversazioni in base a regole del tuo sistema — ad esempio, contrassegnare come "Reclamo" quando il cliente invia una parola chiave specifica.

### 5. Assegna conversazioni agli agenti
Con l'endpoint di assegnazione, puoi designare un agente per tutte le conversazioni aperte di un determinato contatto. Basta fornire l'identificatore del contatto e l'ID dell'utente/agente. L'elenco degli agenti dell'account può essere ottenuto tramite l'endpoint di elenco utenti, che restituisce nome, e-mail e ID di ciascun membro del team.

Questa funzionalità è essenziale per il routing automatico: un sistema CRM può, identificando il profilo del lead, assegnarlo al venditore corretto senza intervento manuale.

## Chi dovrebbe usare l'API Conversazioni

- **Operazioni che già utilizzano sistemi esterni** (ERP, CRM, piattaforme di e-commerce) e desiderano integrare l'assistenza di Papo senza duplicare gli sforzi.
- **Team di supporto con regole di routing complesse**, che devono classificare e indirizzare automaticamente le conversazioni in base ai dati del cliente.
- **Sviluppatori che costruiscono dashboard personalizzate** o attivano notifiche da eventi di assistenza.
- **Rivendite white label** che gestiscono più account e vogliono automatizzare la configurazione di etichette e assegnazioni per ciascun cliente.

## Domande frequenti

### Ho bisogno di un token API per usare questi endpoint?
Sì. Tutte le richieste all'API di Papo richiedono autenticazione tramite chiave segreta, inviata nell'intestazione `Authorization: Bearer sk_live_…`. I token vengono generati nel pannello dell'account.

### L'API consente di inviare messaggi al di fuori della finestra di 24 ore di WhatsApp?
L'invio di messaggi di testo tramite API rispetta la finestra di 24 ore. Per comunicazioni proattive al di fuori di questo periodo, è necessario utilizzare modelli di messaggio (HSM) approvati. Papo offre endpoint specifici per l'invio di HSM.

### Posso elencare le conversazioni per etichetta?
Sì. L'endpoint di elenco delle conversazioni accetta un filtro per etichetta, consentendoti di recuperare solo le assistenze contrassegnate con una o più tag specifiche.

### Come applico un'etichetta a un contatto tramite API?
Utilizza l'endpoint delle etichette, fornendo l'identificatore dell'etichetta (o i dati per la creazione) e l'identificatore del contatto. L'etichetta verrà applicata al contatto e alla conversazione aperta corrispondente.

### L'API restituisce la cronologia completa della conversazione?
L'elenco delle conversazioni restituisce i metadati e gli ultimi messaggi. Per ottenere la cronologia completa dei messaggi di una conversazione specifica, consulta la documentazione dell'API, che dettaglia gli endpoint di recupero dei messaggi.

### È possibile assegnare una conversazione a un agente senza conoscere l'ID utente?
Puoi prima elencare gli utenti dell'account (endpoint degli agenti) per ottenere gli ID e poi usare l'endpoint di assegnazione. L'elenco degli agenti include nome ed e-mail, facilitando l'identificazione.

## Leggi anche

- Come usare l'API di Papo per gestire i clienti della tua rivendita white label
- Come usare l'API di Papo per gestire gli attributi personalizzati dei contatti

---

**[Inizia gratis →](https://chat.papo.global/app/auth/signup?papo_lp=home&utm_source=lp&utm_medium=landing&utm_campaign=home&utm_content=start-free&papo_lp_v=start-free)**

Prova l'API e tutti i moduli di Papo senza costi — il primo utente è gratuito e non richiede carta di credito.