Voicemail

Send ringless voicemails and list voicemail delivery records.

The voicemail endpoints let you send ringless voicemails and track their delivery status. Ringless voicemails are delivered directly to a recipient's voicemail box without ringing the phone.

Base path: /v1/{workspace_id}/voicemail

Endpoints

Method	Path	Description
POST	/voicemail	Send a ringless voicemail
GET	/voicemail	List voicemail records

Send a Voicemail

POST /v1/{workspace_id}/voicemail

Send a ringless voicemail. The request uses multipart form encoding.

Permission required: Channel.send

Form Fields

Field	Type	Required	Description
use_case_id	string (UUID)	Yes	Use case ID for the voicemail
recipient_phone_number	string	Yes	Recipient phone number in US E.164 format (+1 followed by 10 digits)
audio	file	Yes	MP3 audio file (10-60 seconds, max 8 MB)

Response (201 Created)

Field	Type	Description
voicemail_id	string (UUID)	ID of the created voicemail record
sender_phone_number	string	Phone number selected for delivery

Example Request

curl -X POST \
  https://api.platform.amigo.ai/v1/{workspace_id}/voicemail \
  -H "Authorization: Bearer {api_key}" \
  -F "use_case_id={use_case_uuid}" \
  -F "recipient_phone_number=[phone]" \
  -F "[email protected]"

Error Responses

Status	Description
403	Insufficient permissions
404	Use case not found or no phone number assigned
413	Audio file exceeds 8 MB limit
422	Invalid audio or use case configuration
502	Upstream service unavailable
504	Upstream service timed out

List Voicemails

GET /v1/{workspace_id}/voicemail

List voicemail records with optional filters.

Permission required: Channel.view

Query Parameters

Parameter	Type	Required	Description
use_case_id	string (UUID)	No	Filter by use case ID
setup_id	string (UUID)	No	Filter by setup ID
status	string (repeatable)	No	Filter by status. Can be specified multiple times to match any of the given statuses
recipient_phone_number	string	No	Filter by recipient phone number

Response (200 OK)

{
  "items": [
    {
      "voicemail_id": "uuid",
      "setup_id": "uuid",
      "use_case_id": "uuid",
      "recipient_phone_number": "[phone]",
      "status": "delivered",
      "created_at": "2026-06-01T12:00:00Z",
      "updated_at": "2026-06-01T12:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
voicemail_id	string (UUID)	Voicemail record ID
setup_id	string (UUID)	Associated setup ID
use_case_id	string (UUID)	Associated use case ID
recipient_phone_number	string	Recipient phone number
status	string	Delivery status
created_at	string (ISO 8601)	Creation timestamp
updated_at	string (ISO 8601)	Last update timestamp

Error Responses

Status	Description
403	Insufficient permissions