Quote calls and texts

In SimpleVox, the original call or text outranks any summary. Every history entry, activity entry and summary fact points back to the call or text it came from. These requests return that original, so you or your users can check what was actually said.

Get a call or text

Build the request from the source object in a history or activity entry: its kind (call or message), id and source_version. Sending the version means you read exactly what you saw before; if the call or text has changed since, you get 409. Leave version out to read the current version. Reference: Retrieve a call or text.

curl 'https://api.simplevox.app/v1/sources/call/5d9e1b7a-2c4f-4a83-b6e0-9f3d8c2a7e51?version=2' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response has the same fields as a history entry. For a text, original_content holds its exact words. For a call, call_content lists its recordings, each with its transcript and AI summary. Trimmed to one recording:

{
  "data": {
    "id": "5d9e1b7a-2c4f-4a83-b6e0-9f3d8c2a7e51",
    "kind": "call",
    "source_version": 2,
    "call_content": {
      "has_more_recordings": false,
      "recordings": [
        {
          "id": "a4f0c8e2-6b1d-4d39-9e75-c2b8a1f3d067",
          "kind": "live",
          "state": "available",
          "transcript_version": 1,
          "transcript_state": "available",
          "summary": "Mary asked for a quote to replace a water heater at the rental on Example Street and agreed to a visit Thursday at 9am.",
          "facts": [
            { "text": "Visit agreed for Thursday at 9am.", "segments": [14, 15] }
          ],
          "freshness": "current",
          "source_url": "https://my.simplevox.app/sources/call/5d9e1b7a-2c4f-4a83-b6e0-9f3d8c2a7e51?version=2"
        }
      ]
    }
  }
}

Example values are illustrative. Treat state strings as open-ended.

The entry’s source.url is a different link: it opens the call or text in the SimpleVox inbox for a signed-in person, not in the API. See Links for people.

Recordings and summaries

Recordings come 20 at a time. When has_more_recordings is true, page through the rest with List a call’s recordings. A recording’s kind is live for a recorded call and voicemail for a voicemail.
Check freshness before you rely on a summary. A recording’s summary and facts are filled only when freshness is current, meaning the summary matches the current recording and transcript. uncertainties lists what the summary couldn’t settle.
Some summaries draw on earlier calls and texts. Then the recording’s summary stays empty. Read the call’s summary instead: it returns the summary and its facts, plus facts from earlier calls and texts with the contact, each with its own citation. Reference: Retrieve a call summary.
Missing isn’t empty. A recording, transcript or summary that’s pending, failed, unavailable or deleted doesn’t mean nothing was said.

Reading recordings and summaries never starts processing, creates tasks or updates contacts.

Quote a call

A summary fact lists the transcript segments it came from. To show the exact words, fetch those segments with the recording’s id as recording_id and its transcript_version. Reference: Retrieve a transcript.

curl --get 'https://api.simplevox.app/v1/calls/5d9e1b7a-2c4f-4a83-b6e0-9f3d8c2a7e51/transcript' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'recording_id=a4f0c8e2-6b1d-4d39-9e75-c2b8a1f3d067' \
  --data-urlencode 'transcript_version=1' \
  --data-urlencode 'segment_indices[]=14' \
  --data-urlencode 'segment_indices[]=15'

Each segment has its index, text, speaker, and when it starts and ends. Speaker labels describe the recording channel; they don’t verify who was speaking.

Without segment_indices, you get the whole transcript a page at a time. Add kind=voicemail for a voicemail’s transcript.

If the transcript has changed since that version, you get 409. Don’t swap in the latest version silently. Fetch the call again and check the citation still holds.

Play a recording

Ask for a playback link when the person presses play. SimpleVox checks access first, then returns a url and its expires_at. The link works without a token until it expires, so don’t log it or share it, and request a fresh one when you need it. A recording that isn’t ready, or was deleted, returns an error instead of a link. Reference: Get a playback link.

Versions and changes

Calls and texts can change, for example when a recording is reprocessed, a summary is regenerated or call content is deleted. Each one has a source_version.

Cite the version you read, and pass it as version (or source_version on the call reads) when you check it later.
If you request a version that’s no longer current, you get 409. Fetch the call or text again without the old version before you rely on it.
When call content is deleted, its recordings, transcripts and summaries are marked deleted and can no longer back a citation. The call record itself remains.

To learn about changes without polling every call and text, replay changes.

Status stays put

The response reports the conversation’s current shared status, including who last changed it. Fetching a call or text never changes that status.

Links for people

When you show a citation to a person, link to the source.url from the history entry, or the recording’s source_url. It opens the call or text in SimpleVox, where they sign in with their own account and see it only if their own access allows.