Openbare API Beta

Vind gesprekke wat aandag nodig het

Filtreer volgens awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority of tagIds. Awaiting reply ignoreer interne notas; unread is spesifiek vir die geverifieerde spanmaat. Unassigned beteken geen individuele toegewysde nie, selfs as 'n span toegewys is. Etikette pas by enige verskafte ID.

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

Sorteer volgens waitingSince, lastMessageAt, createdAt of besigheidsprioriteit met direction asc of desc. ID's breek gelykopuitslae. Weggelate filters behou compact=false en snoozed=any. REST se tagIds aanvaar ID's geskei deur kommas; MCP aanvaar ook 'n skikking. waitingSince begin by die eerste inkomende boodskap ná die laaste antwoord; opvolgboodskappe en interne notas stel dit nie terug nie. Laat hierdie skandering van die wagtou volgens 'n skedule loop, selfs wanneer geen webhook aankom nie, sodat ou drade weer opduik.

Haal in sonder om die inkassie weer te lees

Gebruik GET /api/v1/sync met conversations:read. Die duursame voer sluit gespreksveranderinge, etikette, boodskappe, kontakeienskappe, herinneringe en skrappingsrekords in. Elke vrag vereis ook sy eie leesbestek: boodskapliggame het messages:read nodig en herinneringe het contact-memory:read nodig. Beperkte geloofsbriewe ontvang net toegelate kanale.

1. Begin sonder 'n wyser, volg nextCursor totdat hasMore false is, en stoor daardie wyser.
2. Lees die huidige gespreks-/kontaklyste en enige geskiedenis wat jy vir jou aanvanklike toestand nodig het.
3. Herspeel vanaf die gestoorde wyser om veranderinge tydens daardie lees vas te vang. Verwerk elke bladsy en stoor dan nextCursor.

Ontdubbel volgens gebeurtenis-id: herspeel is minstens een keer, so stroomaf-aksies het hul eie beskerming teen duplikate nodig. 'n Versoek sonder 'n wyser dek die laaste uur, nie 'n volledige momentopname nie. Gebeurtenisse word 30 dae lank behou; HTTP 410 resync_required beteken laai weer van voor af. Laai ook van voor af nadat bestekke of kanaaltoegang verbreed is. Gebruik limit tot 100 en maxBodyChars tot 10 000 (verstek 500). Stel compact=true vir boodskap-textPreview/textTruncated-velde beperk tot 200 karakters in plaas van body/bodyTruncated. Webhooks kan 'n agent wakker maak; die voer bly beskikbaar sonder webhook-intekeninge of wanneer webhook-aflewering agter is.

Teken kontroles een keer aan en deel die resultaat

Voordat jy 'n ondersoek herhaal, lees list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Stoor 'n resultaat met record_conversation_check (PUT na dieselfde pad), en verskaf key, result, checkedBy en 'n opsionele reference vir die kaart-ID of URL. Byvoorbeeld: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. Sonny teken die geverifieerde actorId en checkedAt-tydstempel aan. Om 'n key te hergebruik, vervang net daardie kontrole; dit is huidige toestand, nie 'n geskiedenislog nie. Lees vereis conversations:read en skryf vereis conversations:write, albei beperk tot die gesprek se kanaal. Hierdie oproepe stuur nie 'n antwoord nie en merk nie die verkoper as beantwoord nie.

Wys toe en werk werk in groepe by

Ontdek aktiewe, toewysbare spanmaats en spanne met GET /api/v1/members and /teams (members:read). Antwoorde sluit beskikbaarheid en effektiewe kanaaltoegang in, sonder e-posadresse. Gebruik conversations:write om status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds of removeTagIds te verander.

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

Om die beurt kies 'n beskikbare spanlid wat toegang tot die gesprek se kanaal het. Sonder 'n geskikte lid gee 'n enkele bywerking 409 terug en misluk 'n groepitem. Elke groep aanvaar tot 100 unieke ID's en pas een patch atomies per gesprek toe. Ondersoek elke { id, ok, error? }-resultaat; sommige items kan misluk. Groepe gebruik die huidige versoekgebaseerde tempolimiet, sonder geweegde heffing volgens aantal items.

Deel kliëntkonteks met Sonny AI

Lys, stoor en verwyder kontakherinneringe met contact-memory:read/write. Verskaf albei contactId en 'n toeganklike sourceId; die kontak moet 'n gesprek op daardie bron hê. Gestoorde feite gebruik dieselfde validering, duplikaathantering en limiete as die app en word as handmatige herinneringe aangeteken.

Lees eienskapdefinisies by /api/v1/properties en lees of stel waardes by /api/v1/contacts/{contactId}/properties. MCP stel list_properties, get_contact_properties en set_contact_property beskikbaar. Hierdie vereis contacts:read/write en toegang tot alle kanale. Stel presies een propertyId of propertyName, met 'n stringwaarde of null om dit skoon te maak. Teks-, getal-, URL-, datum- en keusewaardes word teen die velddefinisie gevalideer.

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

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

Eienskapfilters pas by presiese gestoorde strings; verskeie eienskappe moet almal pas. Waardes wat deur die API geskryf is, word in Co-Pilot en die outo-antwoorder as API-data gemerk. Bestaande reëls vir geverifieerde kliënte en bronne geld steeds. Gewone handmatige interne veldwaardes bly uit hierdie KI-konteks uitgesluit.

Lees dieselfde verslae as jou span

Roep GET /api/v1/reporting/{kind} met reporting:read. Soorte is overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads en online-hours. Overview kombineer tellings, reaksietye en CSAT. Filters is period (1–365 dae, verstek 30), gepaarde from/to-datums (to is eksklusief), granularity (day/month), source, assigneeId en tagId. Source aanvaar all, all-chat, all-email, website:{id} of email:{id}.

Verslae gebruik die paneelbord se navrae en huidige toegangskontroles. Knowledge gebruik datums en toegelate kanale, onafhanklik van die gekose bron, toegewysde of etiket. Online hours meet toeganklike spanmaats se teenwoordigheid in die werkspasie; sy gesprekstellings bly tot kanale beperk. Bestaande /csat-eindpunte behou hul aparte csat:read-bestek en kan 'n ander populasie beskryf.

Stuur lêers met antwoorde of interne notas

Gee attachments:write en laai 'n lêer van tot 25 MB vir 'n gesprek op. POST /api/v1/attachments neem multipart-velde file en conversationId. Die antwoord bevat 'n id en expiresAt. Gee binne een uur tot 10 attachmentIds aan 'n antwoord of nota deur. Elke oplaai is aan jou gebruiker en gesprek gebind en kan net een keer gebruik word. Ongebruikte oplaaie word ná verstryking opgeruim.

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

Antwoorde vereis messages:send; interne notas vereis messages:write en bereik nooit kliënte nie. Boodskappe met net aanhegsels word ondersteun. E-posantwoorde sluit lêers in binne die e-pos se groottebegroting en aflaaiskakels vir die res; e-posse vir vanlyn-kletse sluit lêerskakels in. Skakels in e-posse bly bruikbaar terwyl die aanhegsel bestaan, sodat ontvangers hulle later kan oopmaak. Om die e-pos aan te stuur, deel toegang tot daardie lêers. Gaan emailDeliveryStatus na vir afleweringsmislukkings.

Gemagtigde boodskaplesings sluit downloadUrl, downloadExpiresAt, aiStatus, aiDescription en aiExtractedText in, plus videoTranscripts vir gekoppelde video's (Loom, Vimeo en ander). Aflaaiskakels hou 15 minute; lees die boodskap weer vir vars skakels. Nuwe API-/MCP-oplaaie het privaat berging. Ouer aanhegsels bly openbaar en word as access=legacy_public gemerk: hul oorspronklike URL verval nie. Om 'n boodskap te lees, begin die lees van sy beelde wanneer die werkspasie Sonny AI het. Beeldlesings en videotranskripsies is kort nadat 'n boodskap aankom klaar: terwyl enige nog loop, begin die antwoord met readsInProgress, waarvan nextStep die presiese oproep gee om te maak. Gee waitSeconds (tot 30) deur om in een versoek daarvoor te wag. Widget- en intydse boodskappe vir kliënte bevat nooit uittreksels of transkripsies nie.