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. Used by Zapier's "Test Trigger" button so the trigger-setup UI shows real sample data.
When the account has zero completed voicegrams, returns one synthetic sample row so the setup UI is never empty.
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 (not rejected) so Zapier's test button, which always passes 3, can never fail validation. Non-integer or unparseable input also falls back to the default. |
Example request
bash
curl https://www.voicegram.io/api/v1/voicegrams/recent \
-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") | yes | How the caller verified themselves. Reserved for future SMS verification; only email is produced today. |
voicegrams[].data.sender.email | string | null | yes | Populated when verification_method=email, null when verification_method=sms. email and phone are mutually exclusive. |
voicegrams[].data.sender.phone | string | null | yes | Populated when verification_method=sms, null when verification_method=email. email and phone are mutually exclusive. |
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. Groups urgency, sentiment, intent, callback_required, action items, and extracted entities so consumers can route on any of them without parsing prose. |
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. Mirrors the "Mentioned" section on the voicegram detail page. |
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 (+CCNNNNNNNNNN). Includes spelled-out digits and respects geographic cues ("I'm in London" → +44...). |
voicegrams[].data.summary.mentioned.emails | array of string | yes | Email addresses. Includes obfuscated forms ("at" / "dot"). |
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
},
"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"
]
}
}
]
}
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.