Public API Beta

Find conversations that need attention

Filter by awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority, or tagIds. Awaiting reply ignores internal notes; unread is specific to the authenticated teammate. Unassigned means no individual assignee, even if a team is assigned. Tags match any supplied ID.

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

Sort by waitingSince, lastMessageAt, createdAt, or business priority with direction asc or desc. IDs break ties. Omitted filters retain compact=false and snoozed=any. REST tagIds accepts comma-separated IDs; MCP also accepts an array. waitingSince starts at the first incoming message after the last reply; follow-ups and internal notes do not reset it. Run this waiting-queue scan on a schedule even when no webhook arrives, so old threads resurface.

Catch up without rereading the inbox

Use GET /api/v1/sync with conversations:read. The durable feed includes conversation changes, tags, messages, contact properties, memories, and deletion records. Each payload also requires its own read scope: message bodies need messages:read and memories need contact-memory:read. Restricted credentials receive only permitted channels.

1. Start without a cursor, follow nextCursor until hasMore is false, and save that cursor.
2. Read the current conversation/contact lists and any history you need for your initial state.
3. Replay from the saved cursor to catch changes during that read. Process each page, then save nextCursor.

Deduplicate by event id: replay is at least once, so downstream actions need their own duplicate protection. A request without a cursor covers the last hour, not a complete snapshot. Events are retained for 30 days; HTTP 410 resync_required means bootstrap again. Also bootstrap after widening scopes or channel access. Use limit up to 100 and maxBodyChars up to 10,000 (default 500). Set compact=true for message textPreview/textTruncated fields capped at 200 characters instead of body/bodyTruncated. Webhooks can wake an agent; the feed remains available without webhook subscriptions or when webhook delivery is backlogged.

Record checks once and share the result

Before repeating an investigation, read list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Save a result with record_conversation_check (PUT to the same path), supplying key, result, checkedBy and an optional reference for the card ID or URL. For example: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. Sonny records the authenticated actorId and checkedAt timestamp. Reusing a key replaces only that check; this is current state, not a history log. Reads need conversations:read and writes need conversations:write, both scoped to the conversation’s channel. These calls do not send a reply or mark the seller answered.

Assign and update work in batches

Discover active, assignable teammates and teams with GET /api/v1/members and /teams (members:read). Responses include availability and effective channel access, without email addresses. Use conversations:write to change status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds, or removeTagIds.

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

Round-robin chooses an available team member who can access the conversation's channel. With no eligible member, a single update returns 409 and a batch item fails. Each batch accepts up to 100 unique IDs and applies one patch atomically per conversation. Inspect every { id, ok, error? } result; some items may fail. Batches use the current request-based rate limit, without weighted charging by item count.

Share customer context with Sonny AI

List, save, and remove contact memories with contact-memory:read/write. Supply both contactId and an accessible sourceId; the contact must have a conversation on that source. Saved facts use the same validation, duplicate handling, and limits as the app and are recorded as manual memories.

Read property definitions at /api/v1/properties and read or set values at /api/v1/contacts/{contactId}/properties. MCP exposes list_properties, get_contact_properties, and set_contact_property. These require contacts:read/write and access to all channels. Set exactly one propertyId or propertyName, with a string value or null to clear it. Text, number, URL, date, and select values are validated against the field definition.

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

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

Property filters match exact stored strings; multiple properties must all match. API-authored values are labelled as API data in Co-Pilot and the auto-responder. Existing verified-customer and source rules still apply. Ordinary manual internal field values remain excluded from this AI context.

Read the same reports as your team

With reporting:read, call GET /api/v1/reporting/{kind}. Kinds are overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads, and online-hours. Overview combines counts, response times, and CSAT. Filters are period (1–365 days, default 30), paired from/to dates (to is exclusive), granularity (day/month), source, assigneeId, and tagId. Source accepts all, all-chat, all-email, website:{id}, or email:{id}.

Reports use the dashboard queries and current access checks. Knowledge uses dates and permitted channels, independently of the selected source, assignee, or tag. Online hours measures accessible teammates' workspace presence; its conversation counts remain channel-scoped. Existing /csat endpoints keep their separate csat:read scope and may describe a different population.

Send files with replies or internal notes

Grant attachments:write and upload a file up to 25 MB for a conversation. POST /api/v1/attachments takes multipart file and conversationId fields. The response contains an id and expiresAt. Pass up to 10 attachmentIds to a reply or note within one hour. Each upload is bound to your user and conversation and can be used only once. Unused uploads are cleaned up after expiry.

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

Replies require messages:send; internal notes require messages:write and never reach customers. Attachment-only messages are supported. Email replies include files within the email size budget and download links for the rest; offline chat emails include file links. Emailed links remain usable while the attachment exists, so recipients can open them later. Forwarding the email shares access to those files. Check emailDeliveryStatus for delivery failures.

Authorized message reads include downloadUrl, downloadExpiresAt, aiStatus, aiDescription, and aiExtractedText, plus videoTranscripts for linked videos (Loom, Vimeo and others). Download links last 15 minutes; reread the message for fresh links. New API/MCP uploads have private storage. Older attachments remain public and are marked access=legacy_public: their original URL does not expire. Reading a message starts reading its images when the workspace has Sonny AI. Image readings and video transcripts finish shortly after a message arrives: while any are still running, the response starts with readsInProgress, whose nextStep gives the exact call to make. Pass waitSeconds (up to 30) to wait for them in one request. Customer-facing widget and realtime messages never include extraction or transcripts.