List Voicemails

User Guide > Resources > List Voicemails

This request returns a paginated list of voicemail messages for the currently logged-in user, including voicemails from visible lines.
Results are ordered descending by date and OID, so the most recent voicemail appears first.

Resource

GET /communications/voicemails[?parameters]

Parameters

Name Type Description

where

String

Filter results. Supported filters:

Filter Description

isHeard=false

Return only unheard voicemails. Useful for surfacing voicemails that have been unheard for a long time and would otherwise appear far down the list.

isHeard=true

Return only heard voicemails.

before

[id]

Paging: return results before the specified cursor ID.

after

[id]

Paging: return results after the specified cursor ID.

limit

Integer

Maximum number of results to return. Default: 20.

Paging

Paging works similarly to the communications endpoint, but uses a compound cursor based on epoch seconds and OID (epoch_oid). Results are always ordered descending by date and OID.

Next page (older results)

Make the initial call:
GET /communications/voicemails?limit=20

The response includes a meta.paging.previousId value. Pass this as the after parameter to fetch the next (older) page:
GET /communications/voicemails?limit=20&after={nextId}

Previous page (newer results)

Use the meta.paging.nextId value and pass it as the before parameter:
GET /communications/voicemails?limit=20&before={nextId}

If the number of returned results is less than the limit, there are no more older results.

Payload

None

Response

List Response < Communication >

Field Type Description

oid

String

The unique identifier of the call log.

commonName

String

The display name of the voicemail.

date

DateTime

The date and time the voicemail was received (UTC).

displayed

Boolean

Whether the voicemail has been displayed to the user.

displayedUser

String

The user to whom the voicemail was displayed.

phoneLine.oid

String

The OID of the phone line on which the voicemail was received.

phoneLine.commonName

String

The display name of the phone line.

voicemailIsHeard

Boolean

Whether the voicemail has been heard.

voicemailDuration

Integer

The duration of the voicemail in seconds.

participants

Array

The participants of the call. Contains the caller (rtFrom role).

participants[].oid

String

The OID of the addressee.

participants[].role

String

The role of the participant (e.g. rtFrom).

participants[].address

String

The phone address of the participant.

participants[].label

String

The display label of the participant.

participants[].addressable.oid

String

The OID of the addressable object (e.g. Person).

participants[].addressable.objectType

String

The object type of the addressable (e.g. Person).

participants[].addressable.commonName

String

The display name of the addressable.

participants[].addressable.iconId

String

The icon ID of the addressable.

Context

Authorization

User

Errors

Common Errors

Example

Request
GET https://xelion.nl/api/v1/master/communications/voicemails?limit=2
Response
{
    "data": [
        {
            "object": {
                "date": "2024-03-15 10:32:11",
                "commonName": "Alice <- Bob, 2024-03-15",
                "oid": "2400123",
                "objectType": "CallLog",
                "displayed": false,
                "displayedUser": "",
                "phoneLine": {
                    "commonName": "Alice's Phone Line",
                    "oid": "1651130",
                    "objectType": "XCCPhoneLine"
                },
                "voicemailIsHeard": false,
                "voicemailDuration": 42,
                "participants": [
                    {
                        "role": "rtFrom",
                        "address": "0612345678",
                        "label": "Bob",
                        "addressable": {
                            "commonName": "Bob",
                            "oid": "1650938",
                            "objectType": "Person",
                            "iconId": "1820079"
                        },
                        "oid": "2400124",
                        "objectType": "Addressee"
                    }
                ]
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://xelion.nl/api/v1/master/communications/2400123",
                    "method": "GET"
                }
            ]
        },
        {
            "object": {
                "date": "2024-03-14 08:11:45",
                "commonName": "Alice <- Charlie, 2024-03-14",
                "oid": "2400098",
                "objectType": "CallLog",
                "displayed": true,
                "displayedUser": "alice",
                "phoneLine": {
                    "commonName": "Alice's Phone Line",
                    "oid": "1651130",
                    "objectType": "XCCPhoneLine"
                },
                "voicemailIsHeard": true,
                "voicemailDuration": 17,
                "participants": [
                    {
                        "role": "rtFrom",
                        "address": "0687654321",
                        "label": "Charlie",
                        "addressable": {
                            "commonName": "Charlie",
                            "oid": "1650975",
                            "objectType": "Person",
                            "iconId": ""
                        },
                        "oid": "2400099",
                        "objectType": "Addressee"
                    }
                ]
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://xelion.nl/api/v1/master/communications/2400098",
                    "method": "GET"
                }
            ]
        }
    ],
    "meta": {
        "links": [
            {
                "rel": "refresh",
                "href": "https://xelion.nl/api/v1/master/communications/voicemails",
                "method": "GET"
            },
            {
                "rel": "next",
                "href": "https://xelion.nl/api/v1/master/communications/voicemails?after=1710494331_2400123",
                "method": "GET"
            },
            {
                "rel": "previous",
                "href": "https://xelion.nl/api/v1/master/communications/voicemails?before=1710411105_2400098",
                "method": "GET"
            }
        ],
        "paging": {
            "previousId": "1710411105_2400098",
            "nextId": "1710494331_2400123"
        }
    }
}