Voicegram

List recent completed voicegrams

Returns the N most-recent completed voicegrams for the PAT's account, in the canonical `voicegram.completed` payload shape.

On this page

Returns the N most-recent completed voicegrams for the PAT's account, in the canonical voicegram.completed payload shape.

Accounts with no completed voicegrams receive a single sample row (clearly marked).

Endpoint

http
GET /api/v1/voicegrams/recent

Authentication

Bearer Personal Access Token. See Authentication.

Query parameters

NameTypeRequiredDescription
limitintegernoHow many voicegrams to return. Defaults to 3. Values outside the allowed range are clamped to the nearest valid value; non-integer or unparseable input falls back to the default.

Example request

curl "https://www.voicegram.io/api/v1/voicegrams/recent?limit=3" \
  -H "Authorization: Bearer vg_pat_<your-token>"

Responses

200OK

Recent voicegrams in webhook-payload shape

FieldTypeRequiredDescription
voicegramsarray of objectyes
voicegrams[].eventenum ("voicegram.completed")yes
voicegrams[].event_idstringyesStable event identifier of the form evt_<uuid>. The SAME value is sent across retries of the same event. Customers requiring exactly-once delivery should deduplicate on this field.
voicegrams[].delivered_atstring (date-time)yesISO 8601 timestamp when this delivery attempt fired.
voicegrams[].dataobjectyes
voicegrams[].data.idstringyesVoicegram row identifier.
voicegrams[].data.created_atstring (date-time)yes
voicegrams[].data.completed_atstring (date-time)yes
voicegrams[].data.duration_secondsnumberyesAudio duration in seconds.
voicegrams[].data.senderobjectyes
voicegrams[].data.sender.verification_methodenum ("email", "sms", "whatsapp")yesHow the caller verified themselves: email (verified by email code), sms (verified by text message), or whatsapp (verified by a WhatsApp code).
voicegrams[].data.sender.emailstring | nullyesPopulated when verification_method=email, null otherwise. Exactly one of email, phone, and whatsapp is populated.
voicegrams[].data.sender.phonestring | nullyesE.164 number, populated when verification_method=sms, null otherwise. Exactly one of email, phone, and whatsapp is populated.
voicegrams[].data.sender.whatsappstring | nullyesE.164 number, populated when verification_method=whatsapp, null otherwise. Exactly one of email, phone, and whatsapp is populated.
voicegrams[].data.channelobjectyes
voicegrams[].data.channel.typeenum ("domain", "campaign")yes
voicegrams[].data.channel.idstringyes
voicegrams[].data.channel.namestringyes
voicegrams[].data.channel.page_urlstring | nullyesPage URL where the voicegram was recorded. Null for campaign-sourced voicegrams.
voicegrams[].data.transcriptobjectyes
voicegrams[].data.transcript.textstringyesFull transcript text.
voicegrams[].data.transcript.confidencenumberyesTranscription confidence score, 0.0 to 1.0.
voicegrams[].data.summaryobjectyesStructured AI summary object. Groups urgency, sentiment, intent, callback_required, action items, and extracted entities.
voicegrams[].data.summary.textstringyesAI-generated prose summary (max ~200 words).
voicegrams[].data.summary.urgencystring | nullyesAI-classified urgency. Null when not classified.
voicegrams[].data.summary.sentimentstring | nullyesAI-classified overall sentiment.
voicegrams[].data.summary.intentstring | nullyesAI-classified intent (free-form, e.g. inquiry, support, complaint, scheduling, follow-up, sales).
voicegrams[].data.summary.callback_requiredbooleanyesTrue when the caller explicitly requested a callback.
voicegrams[].data.summary.action_itemsarray of objectyesAI-extracted action items, normalized to objects with task, priority, and deadline.
voicegrams[].data.summary.action_items[].taskstringyes
voicegrams[].data.summary.action_items[].priorityenum ("low", "medium", "high")yes
voicegrams[].data.summary.action_items[].deadlinestring | nullyesFree-form deadline (e.g. ASAP, by Friday).
voicegrams[].data.summary.mentionedobjectyesAI-extracted entities mentioned in the call.
voicegrams[].data.summary.mentioned.namesarray of stringyesPeople or companies mentioned by name.
voicegrams[].data.summary.mentioned.phonesarray of stringyesPhone numbers in E.164 format (+CCNNNNNNNNNN).
voicegrams[].data.summary.mentioned.emailsarray of stringyesEmail addresses.
voicegrams[].data.audioobjectyes
voicegrams[].data.audio.urlstring (uri)yesSigned listen URL backed by a per-recipient listener token. Validity is plan-scaled: 30 days (Free), 90 days (Starter), 365 days (Pro / Business / Enterprise). After expiry or revocation, the URL returns 403. If the underlying audio file has been deleted (plan retention reached), the URL returns 410. For permanent access, use the auth-gated dashboard_url or re-fetch the voicegram via this API to receive a fresh URL.
voicegrams[].data.audio.expires_atstring (date-time)yesISO 8601 timestamp at which url stops working.
voicegrams[].data.audio.content_typeenum ("audio/webm")yesMIME type of the audio at url. Literal audio/webm in v1.
voicegrams[].data.dashboard_urlstring (uri)yesPermanent (auth-gated) link to the voicegram in the Voicegram dashboard.
voicegrams[].data.tagsarray of stringyesUser-supplied tags from the dashboard Tags input. Distinct from the AI-derived summary.urgency / .sentiment / .intent fields. Empty array when the user has not tagged the voicegram.
json
{
  "voicegrams": [
    {
      "event": "voicegram.completed",
      "event_id": "evt_sample-12345678",
      "delivered_at": "2026-05-14T19:23:45.000Z",
      "data": {
        "id": "vg_sample_12345678",
        "created_at": "2026-05-13T19:22:00.000Z",
        "completed_at": "2026-05-13T19:23:00.000Z",
        "duration_seconds": 47,
        "sender": {
          "verification_method": "email",
          "email": "sample.customer@example.com",
          "phone": null,
          "whatsapp": null
        },
        "channel": {
          "type": "domain",
          "id": "sample-domain-id",
          "name": "example.com",
          "page_url": "https://example.com/pricing"
        },
        "transcript": {
          "text": "Hi, I wanted to ask about your enterprise pricing options. Please call me back at four one five, five five five, oh one two three or email pricing.questions@example.com. Thanks.",
          "confidence": 0.94
        },
        "summary": {
          "text": "Customer asking about enterprise pricing. Wants a callback or follow-up email.",
          "urgency": "medium",
          "sentiment": "neutral",
          "intent": "inquiry",
          "callback_required": true,
          "action_items": [
            {
              "task": "Send enterprise pricing details",
              "priority": "medium",
              "deadline": null
            },
            {
              "task": "Call back at +14155550123",
              "priority": "medium",
              "deadline": null
            }
          ],
          "mentioned": {
            "names": [
              "Example Corp"
            ],
            "phones": [
              "+14155550123"
            ],
            "emails": [
              "pricing.questions@example.com"
            ]
          }
        },
        "audio": {
          "url": "https://www.voicegram.io/api/listen/vg_sample_12345678?t=sample-token-redacted",
          "expires_at": "2026-05-15T19:23:45.000Z",
          "content_type": "audio/webm"
        },
        "dashboard_url": "https://voicegram.io/dashboard/inbox/vg_sample_12345678",
        "tags": [
          "pricing",
          "enterprise"
        ]
      }
    },
    {
      "event": "voicegram.completed",
      "event_id": "evt_sample-87654321",
      "delivered_at": "2026-05-14T20:10:00.000Z",
      "data": {
        "id": "vg_sample_87654321",
        "created_at": "2026-05-14T20:08:30.000Z",
        "completed_at": "2026-05-14T20:09:15.000Z",
        "duration_seconds": 22,
        "sender": {
          "verification_method": "sms",
          "email": null,
          "phone": "+12125550148",
          "whatsapp": null
        },
        "channel": {
          "type": "domain",
          "id": "sample-domain-id",
          "name": "example.com",
          "page_url": "https://example.com/contact"
        },
        "transcript": {
          "text": "Hi, it is Jordan. My order has not arrived yet and I need it by Friday. Could someone call me back? Thanks.",
          "confidence": 0.97
        },
        "summary": {
          "text": "Jordan reports a late order needed by Friday and requests a callback. The callback number is the verified sender phone.",
          "urgency": "high",
          "sentiment": "frustrated",
          "intent": "support",
          "callback_required": true,
          "action_items": [
            {
              "task": "Call Jordan back about the late order",
              "priority": "high",
              "deadline": null
            }
          ],
          "mentioned": {
            "names": [
              "Jordan"
            ],
            "phones": [],
            "emails": []
          }
        },
        "audio": {
          "url": "https://www.voicegram.io/api/listen/vg_sample_87654321?t=sample-token-redacted",
          "expires_at": "2026-05-16T20:10:00.000Z",
          "content_type": "audio/webm"
        },
        "dashboard_url": "https://voicegram.io/dashboard/inbox/vg_sample_87654321",
        "tags": [
          "order",
          "callback"
        ]
      }
    }
  ]
}
401Unauthorized

The PAT is missing, malformed, expired, or revoked.

See Errors for the shared error response shape.

403Forbidden

PAT is valid but the account is on the free plan.

See Errors for the shared error response shape.

429Too Many Requests

Per-account rate limit exceeded.

See Errors for the shared error response shape.

500Internal Server Error

Unexpected server error.

See Errors for the shared error response shape.

Need help? Email support@voicegram.io.