API pubblica Beta

Trova le conversazioni che richiedono attenzione

Filtra per awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority o tagIds. In attesa di risposta ignora le note interne; non letto è specifico del collega autenticato. Non assegnata significa senza assegnatario individuale, anche se è assegnato un team. Le etichette corrispondono a uno qualsiasi degli ID forniti.

GET /api/v1/conversations?status=open&awaitingReply=true&compact=true&sort=waitingSince&direction=asc

Ordina per waitingSince, lastMessageAt, createdAt o priorità di business con direction asc o desc. Gli ID risolvono i pareggi. I filtri omessi mantengono compact=false e snoozed=any. In REST tagIds accetta ID separati da virgola; MCP accetta anche un array. waitingSince parte dal primo messaggio in arrivo dopo l'ultima risposta; solleciti e note interne non lo azzerano. Esegui questa scansione della coda in attesa in modo programmato anche quando non arriva alcun webhook, così i thread vecchi riemergono.

Recupera gli aggiornamenti senza rileggere la posta in arrivo

Usa GET /api/v1/sync con conversations:read. Il feed persistente include modifiche alle conversazioni, etichette, messaggi, proprietà dei contatti, memorie e record delle eliminazioni. Ogni payload richiede anche il proprio ambito di lettura: i corpi dei messaggi richiedono messages:read e le memorie contact-memory:read. Le credenziali limitate ricevono solo i canali consentiti.

1. Parti senza cursore, segui nextCursor finché hasMore non è false e salva quel cursore.
2. Leggi gli elenchi attuali di conversazioni e contatti e la cronologia che ti serve per lo stato iniziale.
3. Riparti dal cursore salvato per recuperare le modifiche avvenute durante quella lettura. Elabora ogni pagina, poi salva nextCursor.

Elimina i duplicati in base all'id dell'evento: la riproduzione avviene almeno una volta, quindi le azioni a valle devono avere una propria protezione dai duplicati. Una richiesta senza cursore copre l'ultima ora, non un'istantanea completa. Gli eventi vengono conservati per 30 giorni; HTTP 410 resync_required significa che devi ricaricare lo stato da capo. Fallo anche dopo aver ampliato ambiti o accesso ai canali. Usa limit fino a 100 e maxBodyChars fino a 10.000 (predefinito 500). Imposta compact=true per avere i campi del messaggio textPreview/textTruncated limitati a 200 caratteri invece di body/bodyTruncated. I webhook possono riattivare un agente; il feed resta disponibile anche senza iscrizioni ai webhook o quando la consegna dei webhook è in arretrato.

Registra i controlli una volta e condividi il risultato

Prima di ripetere un'indagine, leggi list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Salva un risultato con record_conversation_check (PUT sullo stesso percorso), fornendo key, result, checkedBy e un reference facoltativo per l'ID o l'URL della scheda. Ad esempio: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. Sonny registra l'actorId autenticato e il timestamp checkedAt. Riutilizzare una key sostituisce solo quel controllo; è lo stato attuale, non uno storico. Le letture richiedono conversations:read e le scritture conversations:write, entrambe limitate al canale della conversazione. Queste chiamate non inviano una risposta e non segnano il venditore come risposto.

Assegna e aggiorna il lavoro in blocco

Trova colleghi e team attivi e assegnabili con GET /api/v1/members and /teams (members:read). Le risposte includono la disponibilità e l'accesso effettivo ai canali, senza indirizzi email. Usa conversations:write per cambiare status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds o removeTagIds.

POST /api/v1/conversations/batch
{
  "conversationIds": ["conversation_1", "conversation_2"],
  "updates": { "agentGroupId": "team_1", "assignment": "round_robin" }
}

L'assegnazione a rotazione sceglie un membro del team disponibile che può accedere al canale della conversazione. Se nessun membro è idoneo, un aggiornamento singolo restituisce 409 e l'elemento di un'operazione in blocco non riesce. Ogni operazione in blocco accetta fino a 100 ID univoci e applica una patch in modo atomico per ogni conversazione. Esamina ogni risultato { id, ok, error? }: alcuni elementi potrebbero non riuscire. Le operazioni in blocco usano l'attuale limite basato sulle richieste, senza addebiti ponderati in base al numero di elementi.

Condividi il contesto dei clienti con Sonny AI

Elenca, salva e rimuovi le memorie dei contatti con contact-memory:read/write. Fornisci sia contactId sia un sourceId accessibile; il contatto deve avere una conversazione su quella sorgente. I fatti salvati usano la stessa validazione, gestione dei duplicati e limiti dell'app e vengono registrati come memorie manuali.

Leggi le definizioni delle proprietà in /api/v1/properties e leggi o imposta i valori in /api/v1/contacts/{contactId}/properties. MCP espone list_properties, get_contact_properties e set_contact_property. Richiedono contacts:read/write e l'accesso a tutti i canali. Imposta esattamente uno tra propertyId e propertyName, con un valore stringa o null per cancellarlo. I valori di testo, numero, URL, data e selezione vengono validati in base alla definizione del campo.

PUT /api/v1/contacts/contact_1/properties
{ "propertyName": "Plan", "value": "Pro" }

GET /api/v1/contacts?property[Plan]=Pro

I filtri sulle proprietà corrispondono alle stringhe esatte salvate; più proprietà devono corrispondere tutte. I valori scritti tramite API sono etichettati come dati API in Co-Pilot e nel risponditore automatico. Restano valide le regole esistenti sui clienti verificati e sulle sorgenti. I normali valori interni inseriti a mano restano esclusi da questo contesto AI.

Leggi gli stessi report del tuo team

Con reporting:read, chiama GET /api/v1/reporting/{kind}. I tipi sono overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads e online-hours. Overview combina conteggi, tempi di risposta e CSAT. I filtri sono period (1–365 giorni, predefinito 30), date from/to abbinate (to è esclusa), granularity (day/month), source, assigneeId e tagId. Source accetta all, all-chat, all-email, website:{id} o email:{id}.

I report usano le stesse query della dashboard e gli attuali controlli di accesso. Knowledge usa le date e i canali consentiti, indipendentemente da sorgente, assegnatario o etichetta selezionati. Online hours misura la presenza nello spazio di lavoro dei colleghi accessibili; i conteggi delle conversazioni restano limitati ai canali. Gli endpoint /csat esistenti mantengono il loro ambito separato csat:read e possono descrivere un insieme diverso.

Invia file con risposte o note interne

Concedi attachments:write e carica un file fino a 25 MB per una conversazione. POST /api/v1/attachments accetta i campi multipart file e conversationId. La risposta contiene un id ed expiresAt. Passa fino a 10 attachmentIds a una risposta o nota entro un'ora. Ogni file caricato è legato al tuo utente e alla conversazione e può essere usato una sola volta. I file non usati vengono eliminati dopo la scadenza.

POST /api/v1/conversations/conversation_1/reply
{ "attachmentIds": ["upload_1"] }

Le risposte richiedono messages:send; le note interne richiedono messages:write e non arrivano mai ai clienti. Sono supportati messaggi con soli allegati. Le risposte via email includono i file entro il limite di dimensione dell'email e link per scaricare gli altri; le email delle chat offline includono link ai file. I link inviati via email restano utilizzabili finché l'allegato esiste, così i destinatari possono aprirli in seguito. Inoltrare l'email condivide l'accesso a quei file. Controlla emailDeliveryStatus per gli errori di consegna.

Le letture autorizzate dei messaggi includono downloadUrl, downloadExpiresAt, aiStatus, aiDescription e aiExtractedText, più videoTranscripts per i video collegati (Loom, Vimeo e altri). I link di download durano 15 minuti; rileggi il messaggio per ottenerne di nuovi. I nuovi caricamenti via API/MCP hanno un'archiviazione privata. Gli allegati più vecchi restano pubblici e sono contrassegnati con access=legacy_public: il loro URL originale non scade. Leggere un messaggio avvia la lettura delle sue immagini quando lo spazio di lavoro ha Sonny AI. Le letture delle immagini e le trascrizioni dei video si completano poco dopo l'arrivo di un messaggio: finché qualcuna è in corso, la risposta inizia con readsInProgress, il cui nextStep indica la chiamata esatta da fare. Passa waitSeconds (fino a 30) per attenderle in un'unica richiesta. I messaggi del widget per i clienti e quelli in tempo reale non includono mai estrazioni o trascrizioni.