Voicemail

Send ringless voicemail drops and track their delivery status through channel use cases.

Ringless voicemail is delivered through a channel use case. Define a ringless_voicemail use case, assign phone numbers to it, and bind it to the service that owns the workflow (see Use Cases & Bindings). Voicemail sends are then queued through the channel management API.

Send a Voicemail

POST /v1/ringless-voicemail

Queues one ringless voicemail drop to a recipient. Requires the ringless-voicemail:send scope on the target setup. The sender number is picked at random from the phone numbers assigned to the use case, and the audio is handed to the voicemail delivery provider.

Request Body (multipart form)

Field	Type	Required	Description
use_case_id	string (UUID)	Yes	ID of the ringless_voicemail use case to send through
recipient_phone_number	string	Yes	Destination phone number in E.164 format (US/CA)
audio	file	Yes	MP3 audio, 10-60 seconds, up to 8 MB

Response (201)

Field	Type	Description
voicemail_id	string	Correlation key for tracking the drop's delivery status
sender_phone_number	string	E.164 phone number the voicemail is sent from

Error Responses

Status	Condition
401	Missing, expired, or invalid bearer token
403	Token lacks the required scope or access to this use case's setup
404	Use case not found, not bound to ringless_voicemail, or has no assigned phone numbers
413	Audio file exceeds 8 MB
422	Audio is not a valid MP3, duration is outside 10-60 seconds, or the delivery provider rejected the send

List Voicemails

GET /v1/ringless-voicemail

Lists voicemail drops matching the request filters. At least one of use_case_id or setup_id is required (422 otherwise).

Query Parameters

Parameter	Type	Description
use_case_id	string (UUID)	Filter to voicemails sent under this use case
setup_id	string (UUID)	Filter to voicemails whose sender phone belongs to this setup
status	string (repeatable)	Filter to voicemails with any of these statuses
recipient_phone_number	string	Filter to voicemails sent to this E.164 number
sort_by	string (repeatable)	+created_at or -created_at (default -created_at, newest first)
limit	integer (1-200)	Maximum items to return (default 50)
continuation_token	string	Opaque page cursor from a prior response

Each returned item includes voicemail_id, setup_id, use_case_id, recipient_phone_number, status, the provider's native ID once known, and created_at/updated_at timestamps.

Delivery Status Lifecycle

Status	Description
pending	Queued; no delivery report received yet
delivered	Successfully delivered (terminal)
skipped	Provider skipped the send, for example do-not-contact filtering (terminal)
failed	Failure during the send attempt (terminal)
not_delivered	Carrier reported non-delivery after the attempt (terminal)

Terminal status changes are also published on the workspace SSE event stream as channel.voicemail_status events.

Operational Model

Use application-level idempotency and eligibility checks before triggering a workflow that can produce outbound voicemail. Treat voicemail as an externally visible contact attempt subject to consent, opt-out, quiet-hour, and campaign-governance rules.

Use case creation and service binding are documented under Channel Manager. If the channel is not yet enabled for your workspace, submit an access request through the Channels endpoint:

Channel ManagerChannels

API Reference

• Use Cases & Bindings
• Events