comms.get_call_recording

Get a short-lived signed link to a call recording or voicemail message

Read-onlySensitiveRead budget

REST

Shipping

POST /api/v1/comms/get_call_recording

MCP tool

Live

comms.get_call_recording

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

Operating contract

Mints a temporary, signed URL for one call's audio and returns it with the exact instant it stops working. kind: "recording" is the two-way conversation; kind: "voicemail" is the message a caller left after nobody answered. A call can have either, both or neither — check has_recording and has_voicemail on comms.get_call first.

THIS IS THE MOST SENSITIVE THING IN THIS DOMAIN AND THE LINK IS BEARER-EQUIVALENT. Anyone holding the URL can play that one call's audio until it expires, with no further authentication — that is what makes it usable by a media player, and it is why it expires in minutes rather than days. Do not paste it into anything durable: not a ticket, not a commit message, not a shared document. Hand it to the thing that needs to play or transcribe the audio, and fetch a fresh one next time.

IT NAMES ONE CALL AND ONE KIND. A link minted for a recording will not fetch the voicemail, and a link minted for one shop cannot address another's call. There is no way to widen it, and ttl_seconds is clamped to 900 (fifteen minutes) however large a number you send — the response's expires_at is the truth, so read it rather than assuming what you asked for.

RECORDING IS A LEGAL DUTY, NOT A SETTING. Calls on this platform are recorded under a disclosure regime the shop configures (@/lib/calls/recording-consent): most of Canada and the US is one-party consent, roughly a dozen US states require the caller to be told. That decision was made when the call was answered and is not re-openable here. Nothing about fetching the audio changes who was told what — if a shop asks you to retrieve a recording it should not have, the answer is that the recording exists either way and the question is one for the shop's own counsel.

The link points at Service VIN, never at the storage provider. The provider's own URL is never returned by any capability, on any surface: it is copyable, it outlives the permission that revealed it, and on one of the two upstreams it is fetched with the platform's own account credential.

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.

Input

Field	Type	Description
callrequired	stringuuid	The call whose audio to link, as returned by comms.list_calls or comms.get_call.
kind	string	Which audio: the recorded conversation, or the voicemail the caller left. Default: `"recording"`One of: `recording`, `voicemail`
ttl_seconds	integer30–900	How long the link should live, 30-900 seconds. Defaults to 300. Default: `300`

Output

Field	Type	Description
call	string	—
kind	string	—
url	string	—
expires_at	string	—
duration_seconds	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.

curl

export SERVICEVIN_API_KEY=svk_live_…

curl -X POST https://www.servicevin.com/api/v1/comms/get_call_recording \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"call":"…","kind":"recording","ttl_seconds":300}'

TypeScript (fetch)

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

// 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/get_call_recording",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "call": "…",
    "kind": "recording",
    "ttl_seconds": 300
},
    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.get_call_recording",
    "arguments": {
      "call": "…",
      "kind": "recording",
      "ttl_seconds": 300
    }
  }
}

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.

Operating contract#

Who may call it#

Input#

Output#

Examples#