List recent completed voicegrams
Returns the N most-recent completed voicegrams for the PAT's account, in the canonical `voicegram.completed` payload shape.
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
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | no | How 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
| Field | Type | Required | Description |
|---|---|---|---|
voicegrams | array of object | yes | |
voicegrams[].event | enum ("voicegram.completed") | yes | |
voicegrams[].event_id | string | yes | Stable 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_at | string (date-time) | yes | ISO 8601 timestamp when this delivery attempt fired. |
voicegrams[].data | object | yes | |
voicegrams[].data.id | string | yes | Voicegram row identifier. |
voicegrams[].data.created_at | string (date-time) | yes | |
voicegrams[].data.completed_at | string (date-time) | yes | |
voicegrams[].data.duration_seconds | number | yes | Audio duration in seconds. |
voicegrams[].data.sender | object | yes | |
voicegrams[].data.sender.verification_method | enum ("email", "sms", "whatsapp") | yes | How the caller verified themselves: email (verified by email code), sms (verified by text message), or whatsapp (verified by a WhatsApp code). |
voicegrams[].data.sender.email | string | null | yes | Populated when verification_method=email, null otherwise. Exactly one of email, phone, and whatsapp is populated. |
voicegrams[].data.sender.phone | string | null | yes | E.164 number, populated when verification_method=sms, null otherwise. Exactly one of email, phone, and whatsapp is populated. |
voicegrams[].data.sender.whatsapp | string | null | yes | E.164 number, populated when verification_method=whatsapp, null otherwise. Exactly one of email, phone, and whatsapp is populated. |
voicegrams[].data.channel | object | yes | |
voicegrams[].data.channel.type | enum ("domain", "campaign") | yes | |
voicegrams[].data.channel.id | string | yes | |
voicegrams[].data.channel.name | string | yes | |
voicegrams[].data.channel.page_url | string | null | yes | Page URL where the voicegram was recorded. Null for campaign-sourced voicegrams. |
voicegrams[].data.transcript | object | yes | |
voicegrams[].data.transcript.text | string | yes | Full transcript text. |
voicegrams[].data.transcript.confidence | number | yes | Transcription confidence score, 0.0 to 1.0. |
voicegrams[].data.summary | object | yes | Structured AI summary object. Groups urgency, sentiment, intent, callback_required, action items, and extracted entities. |
voicegrams[].data.summary.text | string | yes | AI-generated prose summary (max ~200 words). |
voicegrams[].data.summary.urgency | string | null | yes | AI-classified urgency. Null when not classified. |
voicegrams[].data.summary.sentiment | string | null | yes | AI-classified overall sentiment. |
voicegrams[].data.summary.intent | string | null | yes | AI-classified intent (free-form, e.g. inquiry, support, complaint, scheduling, follow-up, sales). |
voicegrams[].data.summary.callback_required | boolean | yes | True when the caller explicitly requested a callback. |
voicegrams[].data.summary.action_items | array of object | yes | AI-extracted action items, normalized to objects with task, priority, and deadline. |
voicegrams[].data.summary.action_items[].task | string | yes | |
voicegrams[].data.summary.action_items[].priority | enum ("low", "medium", "high") | yes | |
voicegrams[].data.summary.action_items[].deadline | string | null | yes | Free-form deadline (e.g. ASAP, by Friday). |
voicegrams[].data.summary.mentioned | object | yes | AI-extracted entities mentioned in the call. |
voicegrams[].data.summary.mentioned.names | array of string | yes | People or companies mentioned by name. |
voicegrams[].data.summary.mentioned.phones | array of string | yes | Phone numbers in E.164 format (+CCNNNNNNNNNN). |
voicegrams[].data.summary.mentioned.emails | array of string | yes | Email addresses. |
voicegrams[].data.audio | object | yes | |
voicegrams[].data.audio.url | string (uri) | yes | Signed 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_at | string (date-time) | yes | ISO 8601 timestamp at which url stops working. |
voicegrams[].data.audio.content_type | enum ("audio/webm") | yes | MIME type of the audio at url. Literal audio/webm in v1. |
voicegrams[].data.dashboard_url | string (uri) | yes | Permanent (auth-gated) link to the voicegram in the Voicegram dashboard. |
voicegrams[].data.tags | array of string | yes | User-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.
Need help? Email support@voicegram.io.