Inbox
Gestisci le conversazioni bidirezionali con i tuoi contatti.
Elenca conversazioni in arrivo
Restituisce tutte le conversazioni bidirezionali del tuo account. Una conversazione raggruppa in un unico thread tutti i messaggi scambiati con un singolo contatto su un dato canale (WhatsApp, RCS, ecc.). Le conversazioni vengono create automaticamente quando un contatto invia un messaggio in entrata o quando invii una risposta tramite la Inbox. Usa i parametri di filtro per restringere i risultati: dateFrom limita alle conversazioni aggiornate dopo una determinata data ISO, channelIds restringe a uno o più canali e unreadOnly=true restituisce solo le conversazioni che contengono messaggi che non hai ancora segnato come letti. L'ordinamento è controllato da orderBy; anteponi al nome del campo - per l'ordine decrescente o + per quello crescente (es. -lastMessageDate per le più recenti prima). Ogni conversazione restituita include un contatore dei non letti. Per azzerarlo, chiama PATCH /conversations/{chatId}/read. Le conversazioni che non ti servono più nella vista predefinita possono essere spostate con PATCH /conversations/{chatId}/archive e ripristinate in seguito con PATCH /conversations/{chatId}/unarchive. Una risposta 401 indica che la chiave API è mancante o non valida.
Invia una risposta a una conversazione
Invia una risposta a una conversazione bidirezionale esistente. Il messaggio viene consegnato sullo stesso canale (WhatsApp, RCS, ecc.) su cui la conversazione è stata originariamente avviata, quindi non devi specificare tu il canale. La risposta viene accettata in modo asincrono (202 Accepted) e messa in coda per la consegna; lo stato di consegna effettivo può essere monitorato tramite la callback dello stato di consegna dei Webhooks, se ne hai configurata una. Il corpo della richiesta deve includere l'ID della conversazione e il contenuto del messaggio. Restituisce 400 se il corpo della richiesta è malformato o mancano campi obbligatori. Restituisce 404 se la conversazione non esiste o non appartiene al tuo account. Restituisce 401 se la chiave API è mancante o non valida. Nota: alcuni canali impongono una finestra di risposta (es. la finestra di 24 ore di WhatsApp). Tentare di rispondere al di fuori di questa finestra può causare la mancata consegna del messaggio.
Archivia una conversazione
Archivia una conversazione, spostandola fuori dalla vista predefinita della posta in arrivo in modo che non compaia più nella lista principale delle conversazioni restituita da GET /conversations. L'archiviazione è un'operazione non distruttiva: nessun messaggio viene eliminato e l'intero storico della conversazione viene conservato. Usala per mantenere ordinata la tua posta in arrivo nascondendo le conversazioni risolte o inattive. Se il contatto invia un nuovo messaggio in entrata a una conversazione archiviata, di norma la conversazione ricompare nella posta in arrivo attiva. Per ripristinare manualmente una conversazione archiviata, chiama PATCH /conversations/{chatId}/unarchive. Restituisce 204 in caso di successo, senza corpo di risposta. Restituisce 404 se la conversazione non esiste o non appartiene al tuo account. Restituisce 401 se la chiave API è mancante o non valida.
Ottieni i messaggi di una conversazione
Restituisce il thread completo dei messaggi di una conversazione, in ordine cronologico. Ogni messaggio include la direzione (in entrata o in uscita), il timestamp, il contenuto e lo stato di consegna. Per i thread lunghi, pagina per ID messaggio: imposta idFrom per recuperare i messaggi con ID maggiore o uguale a un valore, e idTo per i messaggi con ID minore o uguale a un valore. Un tipico flusso di paginazione consiste nel recuperare la prima pagina senza parametri, quindi usare l'ID messaggio più alto della risposta come idFrom nelle chiamate successive per caricare i messaggi più recenti. Dopo aver letto i messaggi, chiama PATCH /conversations/{chatId}/read per azzerare il contatore dei non letti di questa conversazione. Restituisce 404 se il chatId non esiste o non appartiene al tuo account. Restituisce 401 se la chiave API è mancante o non valida.
Segna una conversazione come letta
Segna tutti i messaggi di una conversazione come letti, azzerando il contatore dei non letti. Chiamalo dopo che la tua applicazione ha mostrato i messaggi all'utente, in modo che il filtro unreadOnly di GET /conversations rifletta con precisione quali conversazioni richiedono ancora attenzione. Questa operazione è idempotente: chiamarla su una conversazione già completamente letta non ha alcun effetto e restituisce comunque 204. Restituisce 204 in caso di successo, senza corpo di risposta. Restituisce 404 se la conversazione non esiste o non appartiene al tuo account. Restituisce 401 se la chiave API è mancante o non valida.
Ripristina una conversazione
Ripristina una conversazione archiviata in precedenza, rendendola di nuovo visibile nella vista predefinita della posta in arrivo restituita da GET /conversations. Annulla l'effetto di PATCH /conversations/{chatId}/archive. Tutti i messaggi restano intatti; viene modificato solo il flag di visibilità. Restituisce 204 in caso di successo, senza corpo di risposta. Restituisce 404 se la conversazione non esiste, non appartiene al tuo account o non è attualmente archiviata. Restituisce 401 se la chiave API è mancante o non valida.