Voicemail
The voicemails callers leave your personas, whether they can leave one, and the greeting they hear first — wherever the persona's call flow sends them to voicemail. The Calls API lists the same voicemails as the Phound app, reads and changes the same settings, and takes a greeting you record yourself as an audio file.
The dashboard is built on the same API: its Voicemail page lists the voicemails left for your personas, and each persona's page under Personas changes its voicemail and greeting.
Scopes
| Scope | Grants |
|---|---|
voicemails:read | Listing the voicemails left for your personas, and their webhook events. |
call_settings:read | Reading a persona's voicemail settings. |
call_settings:write | Changing them, and uploading a greeting. |
The voicemails left are data, with a scope of their own. The settings are part of how a persona's calls are
answered, with its call flow: call_settings:*.
List your voicemails
The voicemails left for any of your own personas, the most recently saved first. Add persona_id
for one persona's; page with cursor and limit, as for calls.
curl "https://api.phound.app/calls/v1/voicemails?persona_id=1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c" \
-H "Authorization: Bearer $PHOUND_KEY"
{
"object": "list",
"has_more": false,
"next_cursor": null,
"data": [
{
"id": "df182463-8730-46ae-be2c-7cd638445db6",
"object": "voicemail",
"persona_id": "1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c",
"from": "+14155550101",
"caller_name": "Alex Rivera",
"created_at": "2026-10-26T23:56:16Z",
"duration": 8,
"audio_url": "https://example.com/f/1f173702-d469-4191-8c7e-734cc533a266",
"transcription_url": "https://example.com/f/10cc727b-efe6-46d0-970c-70517c2adfbd"
}
]
}
transcription_url— a plain-text file;nulluntil the transcription is ready, a few seconds after the voicemail is saved.GET /voicemails/{id}retrieves one. To hear about new ones as they're left, subscribe a webhook tocall.voicemail_receivedandcall.voicemail_transcribed: theirdatais the same voicemail.
See a persona's voicemail settings
curl https://api.phound.app/calls/v1/personas/1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c/voicemail \
-H "Authorization: Bearer $PHOUND_KEY"
{
"object": "voicemail_settings",
"persona_id": "1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c",
"enabled": true,
"prefer": "text",
"text": "You've reached the bakery. Leave a message and we'll call you back.",
"text_auto": "The person you are trying to reach is not available. Please leave a message after the signal.",
"url": null,
"url_record": null,
"url_external": null
}
enabled— whether callers can leave a voicemail at all.prefer— the greeting they hear, one of the fields below it.
prefer | Callers hear |
|---|---|
text_auto | text_auto, Phound's own greeting, read aloud. What a persona
that never changed its voicemail plays. Read-only. |
text | text, your own words, read aloud. |
url | The audio file you uploaded — in the Phound app, or below. |
url_record | The greeting recorded in the Phound app. |
url_external | The audio file at url_external, wherever you host
it. |
Only your own personas — not ones other Phound users share with you, whose calls are theirs.
Change it
PATCH /personas/{persona_id}/voicemail changes only the fields you send. To switch greetings, send
prefer — with the greeting itself if the persona doesn't have it yet:
curl -X PATCH https://api.phound.app/calls/v1/personas/1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c/voicemail \
-H "Authorization: Bearer $PHOUND_KEY" \
-H "Content-Type: application/json" \
-d '{"prefer": "text", "text": "You'"'"'ve reached the bakery. Leave a message and we'"'"'ll call you back."}'
text: 1 to 1,000 characters.url,url_record,url_external:httpsURLs of audio files;nullremoves one.{"enabled": false}turns voicemail off and keeps the greeting for when it's back on.
A prefer naming a greeting the persona doesn't have is refused — as is removing the one it plays.
The persona must be active.
Upload a greeting
PUT /personas/{persona_id}/voicemail/greeting takes an audio file — MP3, WAV or M4A, up to
10 MB — in a multipart part named file, makes it the persona's url greeting and
switches prefer to it:
curl -X PUT https://api.phound.app/calls/v1/personas/1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c/voicemail/greeting \
-H "Authorization: Bearer $PHOUND_KEY" \
-F file=@greeting.mp3
Phound converts the file for calls to play before answering, which takes a few seconds; the answer is the
persona's voicemail settings, as GET reads them. Greetings don't count against your storage.
Skip the upload: PATCH its URL as url_external, with
"prefer": "url_external".
Errors
| Status | When |
|---|---|
400 validation_failed | A malformed request: an unknown field, a URL that isn't
https, an empty body. |
404 persona_not_found | Not one of your own personas. |
404 voicemail_not_found | No voicemail with that id was left for your personas. |
413 payload_too_large | A greeting over 10 MB. |
422 validation_failed | prefer names a greeting the persona doesn't have;
the persona isn't active; or the uploaded file isn't audio Phound can play — errors[].pointer
names the field. |
503 not_ready | The uploaded greeting is taking longer than usual to convert. Upload it again shortly. |