Openbare API Beta

Gesprekken vinden die aandacht nodig hebben

Filter op awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority of tagIds. Wacht op antwoord negeert interne notities; ongelezen geldt specifiek voor het ingelogde teamlid. Niet toegewezen betekent geen individuele toegewezen persoon, ook als er wel een team is toegewezen. Labels matchen op elke opgegeven ID.

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

Sorteer op waitingSince, lastMessageAt, createdAt of zakelijke prioriteit, met direction asc of desc. ID's beslissen bij gelijke waarden. Weggelaten filters houden compact=false en snoozed=any aan. REST-tagIds accepteert ID's gescheiden door komma's; MCP accepteert ook een array. waitingSince begint bij het eerste inkomende bericht na het laatste antwoord; vervolgberichten en interne notities resetten het niet. Laat deze scan van de wachtrij volgens een schema draaien, ook als er geen webhook binnenkomt, zodat oude threads weer bovenkomen.

Bijblijven zonder de inbox opnieuw te lezen

Gebruik GET /api/v1/sync met conversations:read. De duurzame feed bevat gesprekswijzigingen, labels, berichten, contacteigenschappen, geheugen en verwijderrecords. Elke payload vereist ook een eigen leesrecht: berichtteksten hebben messages:read nodig en geheugen heeft contact-memory:read nodig. Beperkte inloggegevens ontvangen alleen toegestane kanalen.

1. Begin zonder cursor, volg nextCursor tot hasMore false is en sla die cursor op.
2. Lees de huidige lijsten met gesprekken en contacten en de geschiedenis die je nodig hebt voor je beginstand.
3. Speel af vanaf de opgeslagen cursor om wijzigingen tijdens dat lezen op te vangen. Verwerk elke pagina en sla daarna nextCursor op.

Ontdubbel op event-id: het afspelen gebeurt minstens één keer, dus acties verderop hebben hun eigen bescherming tegen dubbele verwerking nodig. Een request zonder cursor beslaat het laatste uur, geen volledige momentopname. Events worden 30 dagen bewaard; HTTP 410 resync_required betekent dat je opnieuw moet beginnen. Begin ook opnieuw na het verruimen van rechten of kanaaltoegang. Gebruik limit tot 100 en maxBodyChars tot 10.000 (standaard 500). Zet compact=true voor de berichtvelden textPreview/textTruncated, begrensd op 200 tekens, in plaats van body/bodyTruncated. Webhooks kunnen een agent wekken; de feed blijft beschikbaar zonder webhookabonnementen of als de webhookaflevering achterloopt.

Controles één keer vastleggen en het resultaat delen

Lees list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks) voordat je een onderzoek herhaalt. Sla een resultaat op met record_conversation_check (PUT naar hetzelfde pad), met key, result, checkedBy en een optionele reference voor de kaart-ID of URL. Bijvoorbeeld: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. Sonny legt de ingelogde actorId en het tijdstempel checkedAt vast. Hergebruik je een key, dan wordt alleen die controle vervangen; dit is de huidige stand, geen geschiedenislog. Lezen vereist conversations:read en schrijven conversations:write, allebei beperkt tot het kanaal van het gesprek. Deze aanroepen versturen geen antwoord en markeren het gesprek niet als beantwoord.

Werk in bulk toewijzen en bijwerken

Vind actieve teamleden en teams aan wie je kunt toewijzen met GET /api/v1/members and /teams (members:read). Responses bevatten beschikbaarheid en daadwerkelijke kanaaltoegang, zonder e-mailadressen. Gebruik conversations:write om status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds of removeTagIds te wijzigen.

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

Round-robin kiest een beschikbaar teamlid dat toegang heeft tot het kanaal van het gesprek. Is er niemand geschikt, dan geeft een losse update 409 terug en mislukt een item in de bulkactie. Elke bulkactie accepteert maximaal 100 unieke ID's en past per gesprek één patch atomair toe. Controleer elk { id, ok, error? }-resultaat; sommige items kunnen mislukken. Bulkacties vallen onder de huidige limiet per request, zonder extra gewicht per aantal items.

Klantcontext delen met Sonny AI

Toon, bewaar en verwijder contactgeheugen met contact-memory:read/write. Geef zowel contactId als een toegankelijke sourceId mee; het contact moet een gesprek op die bron hebben. Opgeslagen feiten gebruiken dezelfde validatie, verwerking van dubbelingen en limieten als de app en worden vastgelegd als handmatig geheugen.

Lees eigenschapsdefinities via /api/v1/properties en lees of stel waarden in via /api/v1/contacts/{contactId}/properties. MCP biedt list_properties, get_contact_properties en set_contact_property. Hiervoor zijn contacts:read/write en toegang tot alle kanalen nodig. Geef precies één propertyId of propertyName op, met een tekstwaarde of null om hem te wissen. Waarden voor tekst, getal, URL, datum en keuze worden gevalideerd tegen de velddefinitie.

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

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

Eigenschapsfilters matchen op exact opgeslagen tekst; bij meerdere eigenschappen moeten ze allemaal overeenkomen. Waarden die via de API zijn ingesteld, worden in AI Copilot en de autoresponder gelabeld als API-gegevens. Bestaande regels voor geverifieerde klanten en bronnen blijven gelden. Gewone handmatige interne veldwaarden blijven buiten deze AI-context.

Dezelfde rapporten lezen als je team

Roep met reporting:read GET /api/v1/reporting/{kind} aan. De soorten zijn overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads en online-hours. Overview combineert aantallen, reactietijden en CSAT. Filters zijn period (1–365 dagen, standaard 30), from/to als paar (to telt niet mee), granularity (day/month), source, assigneeId en tagId. Source accepteert all, all-chat, all-email, website:{id} of email:{id}.

Rapporten gebruiken dezelfde queries als het dashboard en de huidige toegangscontroles. Knowledge gebruikt datums en toegestane kanalen, los van de gekozen bron, toegewezen persoon of label. Online-hours meet de aanwezigheid van toegankelijke teamleden in de werkruimte; de gespreksaantallen daarin blijven beperkt tot kanalen. De bestaande /csat-endpoints houden hun eigen recht csat:read en kunnen een andere groep beschrijven.

Bestanden meesturen met antwoorden of interne notities

Geef attachments:write en upload een bestand van maximaal 25 MB voor een gesprek. POST /api/v1/attachments gebruikt de multipart-velden file en conversationId. De response bevat een id en expiresAt. Geef binnen een uur maximaal 10 attachmentIds mee aan een antwoord of notitie. Elke upload is gekoppeld aan jouw gebruiker en gesprek en kan maar één keer worden gebruikt. Ongebruikte uploads worden na het verlopen opgeruimd.

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

Antwoorden vereisen messages:send; interne notities vereisen messages:write en bereiken klanten nooit. Berichten met alleen bijlagen worden ondersteund. E-mailantwoorden bevatten bestanden binnen de maximale e-mailgrootte en downloadlinks voor de rest; offline chatmails bevatten links naar bestanden. Gemailde links blijven bruikbaar zolang de bijlage bestaat, zodat ontvangers ze later kunnen openen. Wie de e-mail doorstuurt, deelt ook toegang tot die bestanden. Controleer emailDeliveryStatus op mislukte afleveringen.

Geautoriseerde berichten bevatten downloadUrl, downloadExpiresAt, aiStatus, aiDescription en aiExtractedText, plus videoTranscripts voor gelinkte video's (Loom, Vimeo en andere). Downloadlinks zijn 15 minuten geldig; lees het bericht opnieuw voor verse links. Nieuwe uploads via API/MCP worden privé opgeslagen. Oudere bijlagen blijven openbaar en zijn gemarkeerd met access=legacy_public: hun oorspronkelijke URL verloopt niet. Het lezen van een bericht start het lezen van de afbeeldingen als de werkruimte Sonny AI heeft. Het lezen van afbeeldingen en videotranscripten is kort na binnenkomst van een bericht klaar: zolang er nog iets loopt, begint de response met readsInProgress, waarvan nextStep precies aangeeft welke aanroep je moet doen. Geef waitSeconds (maximaal 30) mee om er in één request op te wachten. Widget- en realtimeberichten voor klanten bevatten nooit uitgelezen inhoud of transcripten.