Sonny MCP 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.

list_conversations({ awaitingReply: true, snoozed: "false", compact: true, sort: "priority", direction: "desc" })

Sort by 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.

Catch up without rereading the inbox

Use 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). Webhooks can wake an agent; the feed remains available without webhook subscriptions or when webhook delivery is backlogged.

Assign and update work in batches

Discover active, assignable teammates and teams with list_members / list_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.

batch_update_conversations({
  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.

set_contact_property({ contactId: "contact_1", propertyName: "Plan", value: "Pro" })
list_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_report({ kind, filters }). 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. upload_attachment takes conversationId, fileName, contentType, and dataBase64. 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.

send_message({ conversationId: "conversation_1", 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. 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. Extraction is available when Sonny's configured AI features have analyzed a supported image; customer-facing widget and realtime messages never include that extraction.