Documentation
Comms
comms.list_calls
REST
ShippingPOST /api/v1/comms/list_callsMCP tool
Livecomms.list_callsExposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Comms domain.
Operating contract
The shop's phone log, newest first, narrowed by any combination of direction, status, customer_id and a since / until window.
WHAT A CALL RECORD IS HERE: who rang whom, which way, how long it ran, how it ended, and whether audio, a transcript and an AI recap exist. It is NOT the audio and NOT the words — has_recording, has_voicemail, has_transcript and has_ai_summary are booleans on purpose, so a model can see that a recording exists without any surface handing one out by accident. Fetch them with comms.get_call_recording, comms.get_call_transcript and comms.get_call_analysis, each of which is separately gated.
status is the OUTCOME. completed and missed are the two a shop asks about; ringing and in_progress are calls happening right now, so a report about yesterday should not include them. For missed calls specifically, comms.list_missed_calls also tells you whether a voicemail was left and is the better tool for a call-back list.
Each result's id is the call id that comms.get_call, comms.get_call_recording, comms.get_call_transcript and comms.get_call_analysis take. conversation is the inbox thread this call was filed into — pass it to comms.list_messages to read the texts around it. customer_id is what customers.get takes.
TRUNCATION: total is the exact number of calls matching the filter and omitted is how many are NOT in this response. 'How many calls did we miss last week' must be answered from total, never from items.length. When omitted is not 0, call again with offset set to next_offset.
Who may call it
- Permission
calls.accessThe caller must hold Calls 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
readCounted against the read budget — the widest of the four.
Partial answers
omitted is how many matching records are not in the response, and 0 is a real answer meaning you have all of them. Continue with next_offset.
Do not summarise from a truncated response
Input
| Field | Type | Description |
|---|---|---|
| direction | string | Only calls this way round. Omit for both. One of:inbound, outbound |
| status | string | Only calls that ended this way. `missed` is the one a call-back list wants. One of:ringing, in_progress, completed, missed, failed, canceled |
| customer_id | stringuuid | Only this customer's calls, as returned by customers.list or comms.resolve_contact. |
| since | stringmax 40 chars | ISO instant. Only calls that started at or after it. |
| until | stringmax 40 chars | ISO instant. Only calls that started before it. |
| limit | integer1–100 | How many calls to return, 1-100. Defaults to 25. Default:25 |
| offset | integermin 0 | How many to skip. Pass the previous response's next_offset to continue. Default:0 |
Output
| Field | Type | Description |
|---|---|---|
| items | object[] | — |
| items[].id | string | — |
| items[].conversation | string | null | — |
| items[].customer_id | string | null | — |
| items[].direction | string | — |
| items[].status | string | — |
| items[].from | string | — |
| items[].to | string | — |
| items[].started_at | string | — |
| items[].ended_at | string | null | — |
| items[].duration_seconds | number | null | — |
| items[].answered_by | string | null | — |
| items[].has_recording | boolean | — |
| items[].recording_duration_seconds | number | null | — |
| items[].has_voicemail | boolean | — |
| items[].voicemail_duration_seconds | number | null | — |
| items[].has_transcript | boolean | — |
| items[].has_ai_summary | boolean | — |
| total | number | — |
| omitted | number | — |
| next_offset | number | null | — |
Examples
Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.
export SERVICEVIN_API_KEY=svk_live_…
curl -X POST https://www.servicevin.com/api/v1/comms/list_calls \
-H "Authorization: Bearer $SERVICEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"limit":25,"offset":0}'const res = await fetch("https://www.servicevin.com/api/v1/comms/list_calls", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"limit": 25,
"offset": 0
}),
});
// 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;import os, requests
res = requests.post(
"https://www.servicevin.com/api/v1/comms/list_calls",
headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
json={
"limit": 25,
"offset": 0
},
timeout=30,
)
payload = res.json()
if not res.ok:
raise RuntimeError(payload["error"]["code"])
data = payload["data"]{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "comms.list_calls",
"arguments": {
"limit": 25,
"offset": 0
}
}
}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 calls.access. |
| 422 | validation_error | An argument was wrong. The message names the field. |
| 429 | rate_limited | Too many read calls. Back off and retry. |
| 500 | internal_error | Something failed on our side. Nothing was changed. |