Skip to main content

Manage Voicemail Messages

Retrieve, listen to, manage, and delete voicemail messages from voicemail boxes.

Endpoints​

List Messages​

GET https://api.audian.com:8443/v2/voicemail/boxes/{boxId}/messages

Get Message Details​

GET https://api.audian.com:8443/v2/voicemail/boxes/{boxId}/messages/{messageId}

Mark as Read​

PUT https://api.audian.com:8443/v2/voicemail/boxes/{boxId}/messages/{messageId}/read

Archive Message​

PUT https://api.audian.com:8443/v2/voicemail/boxes/{boxId}/messages/{messageId}/archive

Delete Message​

DELETE https://api.audian.com:8443/v2/voicemail/boxes/{boxId}/messages/{messageId}

Get Message Transcript​

GET https://api.audian.com:8443/v2/voicemail/boxes/{boxId}/messages/{messageId}/transcript

List Messages​

Retrieve all messages from a voicemail box.

Request​

curl -X GET "https://api.audian.com:8443/v2/voicemail/boxes/box_abc123def456/messages?limit=20&offset=0&status=new" \
  -H "X-Auth-Token: YOUR_API_KEY"

Parameters​

ParameterTypeDescription
limitNumberMessages per page (default: 20, max: 100)
offsetNumberPagination offset (default: 0)
statusStringFilter by status (new, read, archived)
sortStringSort order (newest, oldest, default: newest)

Examples​

JavaScript/Node.js​

const axios = require('axios');

const listMessages = async (boxId, status = 'new', limit = 20) => {
  try {
    const response = await axios.get(
      `https://api.audian.com:8443/v2/voicemail/boxes/${boxId}/messages`,
      {
        params: {
          status: status,
          limit: limit,
          offset: 0
        },
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    console.log('Messages retrieved:', response.data);
    return response.data;
  } catch (error) {
    console.error('Failed to retrieve messages:', error);
  }
};

// Usage
listMessages('box_abc123def456', 'new');

Python​

import requests

def list_messages(api_key, box_id, status=None, limit=20, offset=0):
    url = f'https://api.audian.com:8443/v2/voicemail/boxes/{box_id}/messages'
    headers = {
        'X-Auth-Token': api_key
    }
    
    params = {
        'limit': limit,
        'offset': offset
    }
    
    if status:
        params['status'] = status
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Usage
result = list_messages(
    api_key='YOUR_API_KEY',
    box_id='box_abc123def456',
    status='new'
)
print(result)

Get Only Unread Messages​

curl -X GET "https://api.audian.com:8443/v2/voicemail/boxes/box_abc123def456/messages?status=new&limit=10" \
  -H "X-Auth-Token: YOUR_API_KEY"

Response Format​

List Messages Success (200)​

{
  "messages": [
    {
      "id": "msg_abc123",
      "box_id": "box_abc123def456",
      "caller_number": "+12025551234",
      "caller_name": "John Smith",
      "duration": 45,
      "status": "new",
      "received_at": "2024-02-04T11:30:00Z",
      "transcript": null,
      "audio_url": "https://api.audian.com:8443/v2/voicemail/messages/msg_abc123/audio",
      "created_at": "2024-02-04T11:30:00Z"
    },
    {
      "id": "msg_def456",
      "box_id": "box_abc123def456",
      "caller_number": "+12025555678",
      "caller_name": "Jane Doe",
      "duration": 120,
      "status": "read",
      "received_at": "2024-02-04T10:45:00Z",
      "transcript": "Hi John, this is Jane calling about the meeting tomorrow...",
      "audio_url": "https://api.audian.com:8443/v2/voicemail/messages/msg_def456/audio",
      "created_at": "2024-02-04T10:45:00Z"
    }
  ],
  "total": 2,
  "unread": 1,
  "limit": 20,
  "offset": 0
}

Get Message Details​

Retrieve detailed information about a specific message.

curl -X GET https://api.audian.com:8443/v2/voicemail/boxes/box_abc123def456/messages/msg_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY"

Mark Message as Read​

Update message status to read.

curl -X PUT https://api.audian.com:8443/v2/voicemail/boxes/box_abc123def456/messages/msg_abc123/read \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Archive Message​

Move message to archive for long-term storage.

curl -X PUT https://api.audian.com:8443/v2/voicemail/boxes/box_abc123def456/messages/msg_abc123/archive \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Delete Message​

Permanently delete a message from the voicemail box.

curl -X DELETE https://api.audian.com:8443/v2/voicemail/boxes/box_abc123def456/messages/msg_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY"

Get Message Transcript​

Retrieve automatic or manual transcription of a message.

curl -X GET https://api.audian.com:8443/v2/voicemail/boxes/box_abc123def456/messages/msg_abc123/transcript \
  -H "X-Auth-Token: YOUR_API_KEY"

Response​

{
  "id": "msg_abc123",
  "transcript": "Hi John, this is Jane calling about the quarterly meeting. I wanted to confirm you're available tomorrow at 2 PM. Please call me back at your earliest convenience. Thanks!",
  "confidence": 0.95,
  "language": "en-US",
  "generated_at": "2024-02-04T11:35:00Z"
}

Message Download​

Download message audio file.

curl -X GET https://api.audian.com:8443/v2/voicemail/messages/msg_abc123/audio \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -o message.wav

Batch Operations​

Mark Multiple as Read​

const markMultipleAsRead = async (boxId, messageIds) => {
  const results = [];
  
  for (const messageId of messageIds) {
    try {
      const response = await axios.put(
        `https://api.audian.com:8443/v2/voicemail/boxes/${boxId}/messages/${messageId}/read`,
        {},
        {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        }
      );
      results.push({ messageId, status: 'marked_read' });
    } catch (error) {
      results.push({ messageId, status: 'failed' });
    }
  }
  
  return results;
};

Archive Old Messages​

const archiveOldMessages = async (boxId, daysOld = 30) => {
  // Get messages older than specified days
  const messages = await listMessages(boxId);
  
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - daysOld);
  
  for (const message of messages.messages) {
    if (new Date(message.received_at) < cutoffDate) {
      await archiveMessage(boxId, message.id);
    }
  }
};

Message States​

StatusDescription
newUnread message
readMessage has been reviewed
archivedMessage in long-term storage
deletedMessage marked for deletion

Best Practices​

  1. Regular Review: Check messages daily
  2. Mark as Read: Keep track of reviewed messages
  3. Archive Old: Archive messages older than 30 days
  4. Transcription: Use transcripts for quick reference
  5. Backup: Download important messages
  6. Cleanup: Delete unwanted messages to save space

Message Workflows​

Process New Voicemails​

// 1. Get new messages
const newMessages = await listMessages(boxId, 'new');

// 2. Review each message
for (const msg of newMessages.messages) {
  const transcript = await getTranscript(boxId, msg.id);
  console.log(transcript.transcript);
  
  // 3. Mark as read
  await markAsRead(boxId, msg.id);
  
  // 4. Archive if old
  if (shouldArchive(msg.received_at)) {
    await archiveMessage(boxId, msg.id);
  }
}

Limits and Quotas​

  • Max messages per list: 100 per request
  • Message retention: Per your storage plan
  • Archive retention: Unlimited (paid storage)
  • Download bandwidth: Unlimited
  • Transcription: Optional (may incur additional charges)
  • Max concurrent downloads: 10 per account