Docs / Guides

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.

See yours first

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

ScopeGrants
voicemails:readListing the voicemails left for your personas, and their webhook events.
call_settings:readReading a persona's voicemail settings.
call_settings:writeChanging 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; null until 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 to call.voicemail_received and call.voicemail_transcribed: their data is 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.
preferCallers hear
text_autotext_auto, Phound's own greeting, read aloud. What a persona that never changed its voicemail plays. Read-only.
texttext, your own words, read aloud.
urlThe audio file you uploaded — in the Phound app, or below.
url_recordThe greeting recorded in the Phound app.
url_externalThe 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: https URLs of audio files; null removes 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.

Already hosting the file?

Skip the upload: PATCH its URL as url_external, with "prefer": "url_external".

Errors

StatusWhen
400 validation_failedA malformed request: an unknown field, a URL that isn't https, an empty body.
404 persona_not_foundNot one of your own personas.
404 voicemail_not_foundNo voicemail with that id was left for your personas.
413 payload_too_largeA greeting over 10 MB.
422 validation_failedprefer 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_readyThe uploaded greeting is taking longer than usual to convert. Upload it again shortly.