comms.update_conversation

Mark a conversation read, done, pinned or assigned — not its messages

WritesWrite budget

REST

Shipping

POST /api/v1/comms/update_conversation

MCP tool

Live

comms.update_conversation

Exposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Comms domain.

Operating contract

ONE CHANGE PER CALL, chosen by which parameter you provide: mark_read, mark_unread, mark_done, mark_open, snooze, pin, unpin, staff_id (hand it to that teammate) or unassign. To make several changes, call this once per change. Supplying none is refused, and so is supplying two — a single call that both closed a thread and reassigned it would be one audit row for two decisions.

THE MESSAGES ARE NOT TOUCHABLE AND NEVER WILL BE. This changes the SHOP'S state around a thread — its disposition, who owns it, whether it is pinned. A delivered text is history: there is no capability anywhere in this domain that edits or deletes one, and a request to 'fix' what a customer was told is a request to send another message.

mark_done is what Quo calls done and what this product stores as closed. It does not stop anything: a new inbound reopens the thread, which is the behaviour a shop wants and the reason closing a thread early is cheap.

ASSIGNING PINGS SOMEBODY. staff_id puts the thread in a real person's queue and notifies them, so it is not a bookkeeping change — assign when somebody is actually meant to act. The target must be a teammate whose role grants inbox access; anyone else is refused rather than silently parked, because a thread assigned to somebody who cannot open the inbox is work that never happens. tasks.assignees lists who qualifies.

Assigning a thread to whoever it is already assigned to is a no-op: no second activity line and, crucially, no second ping.

Who may call it

Permission: inbox.accessThe caller must hold Inbox at the ACT level. A read-only dashboard grant on the same section is refused.
Plan: Every planNo plan gate. Available on every Service VIN plan.
Retries: naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.
Rate class: writeCounted against the write budget, which is tighter than a read.

Input

Field	Type	Description
conversationrequired	stringuuid	The thread to change, as returned by comms.list_conversations.
mark_read	boolean	True to mark the thread read. One change per call.
mark_unread	boolean	True to put it back to unread. One change per call.
mark_done	boolean	True to close the thread (Quo calls this done). One change per call.
mark_open	boolean	True to reopen a closed or snoozed thread. One change per call.
snooze	boolean	True to park the thread until the next inbound. One change per call.
pin	boolean	True to pin it to the top. One change per call.
unpin	boolean	True to unpin it. One change per call.
staff_id	stringuuid	Hand the thread to this teammate, as returned by tasks.assignees. One change per call.
unassign	boolean	True to take the thread off whoever holds it. One change per call.

Output

Field	Type	Description
id	string	—
customer_id	string \| null	—
channel	string	—
status	string	—
subject	string \| null	—
contact_number	string \| null	—
assigned_to	string \| null	—
pinned	boolean	—
unread	boolean	—
is_ai_managed	boolean	—
last_message_at	string \| null	—
last_inbound_at	string \| null	—
last_outbound_at	string \| null	—
last_human_outbound_at	string \| null	—
created_at	string	—

Examples

Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.

curl

export SERVICEVIN_API_KEY=svk_live_…

curl -X POST https://www.servicevin.com/api/v1/comms/update_conversation \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation":"…"}'

TypeScript (fetch)

const res = await fetch("https://www.servicevin.com/api/v1/comms/update_conversation", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "conversation": "…"
  }),
});

// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;

Python (requests)

import os, requests

res = requests.post(
    "https://www.servicevin.com/api/v1/comms/update_conversation",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "conversation": "…"
},
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(payload["error"]["code"])
data = payload["data"]

MCP tools/call — https://www.servicevin.com/api/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comms.update_conversation",
    "arguments": {
      "conversation": "…"
    }
  }
}

Refusals

The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.

Status	Code	When
404	`not_found`	The id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both.
403	`forbidden`	This login does not hold inbox.access.
403	`insufficient_scope`	The credential is read-only and this capability writes.
422	`validation_error`	An argument was wrong. The message names the field.
429	`rate_limited`	Too many write calls. Back off and retry.
500	`internal_error`	Something failed on our side. Nothing was changed.

Operating contract#

Who may call it#

Input#

Output#

Examples#