Voicemail

About Voicemail

Voicemail boxes store messages, recorded from the caller, for the voicemail box owner to listen to at a later time.

Differences between Kazoo version 3.x and 4.x

As of Kazoo 4.0 all new voicemail messages will be stored in the account MODbs.

Regarding this change voicemail API will no longer returns the messages array when fetching mailbox settings. The existing /messages API should be used to manage messages in a voicemail box.

For more information about voicemail changes see documentation for kazoo_voicemail.

Schema

Schema for a voicemail box

Key	Description	Type	Default	Required	Support Level
`after_forward_action`	Action to perform after forwarding a voicemail message	`string(‘prompt'	'save’)`	`save`	`false`
`aliases.[]`		`string(1..36)`		`false`
`aliases`	The voicemail box aliases string list	`array(string(1..36))`	`[]`	`false`
`announcement_only`	Determine if the mailbox should only play announcements	`boolean()`	`false`	`false`	`unsupported`
`check_if_owner`	Determines if when the user calls their own voicemail they should be prompted to sign in	`boolean()`	`true`	`false`	`supported`
`delete_after_notify`	Move the voicemail to delete folder after the notification has been sent	`boolean()`	`false`	`false`	`supported`
`envelope_type`	The voicemail envelope type to determine the envelope format	`string(‘default'	'caller_and_time’)`	`default`	`false`
`flags.[]`		`string()`		`false`	`supported`
`flags`	Flags set by external applications	`array(string())`		`false`	`supported`
`include_message_on_notify`	Whether or not to include the attachment when sending a new voicemail to email notification	`boolean()`	`true`	`false`	`supported`
`include_transcription_on_notify`	Whether or not to include the transcription when sending a new voicemail to email notification	`boolean()`	`true`	`false`	`supported`
`is_setup`	Determines if the user has completed the initial configuration	`boolean()`	`false`	`false`	`supported`
`is_voicemail_ff_rw_enabled`	callflow allow fastforward and rewind during voicemail message playback	`boolean()`	`false`	`false`
`mailbox`	The voicemail box number	`string(1..30)`		`true`	`supported`
`media.unavailable`	The ID of a media object that should be used as the unavailable greeting	`string(32)`		`false`	`supported`
`media`	The media (prompt) parameters	`object()`	`{}`	`false`	`supported`
`media_extension`	Voicemail audio format	`string(‘mp3'	'mp4'	'wav’)`	`mp3`
`name`	A friendly name for the voicemail box	`string(1..128)`		`true`	`supported`
`not_configurable`	Determines if the user can configure this voicemail.	`boolean()`	`false`	`false`	`supported`
`notify.callback`	Schema for a callback options	#/definitions/notify.callback		`false`
`notify`		`object()`		`false`	`supported`
`notify_email_addresses.[]`		`string()`		`false`	`supported`
`notify_email_addresses`	List of email addresses to send notifications to (in addition to owner’s email, if any)	`array(string())`	`[]`	`false`	`supported`
`oldest_message_first`	Play older voicemail messages before new ones	`boolean()`	`false`	`false`	`supported`
`operator_number`	Alternate/override number to use when calling operator from voicemail	`integer()	string()`		`false`
`owner_id`	The ID of the user object that ‘owns’ the voicemail box	`string(32)`		`false`	`supported`
`pin`	The pin number for the voicemail box	`string(4..6)`		`false`	`supported`
`require_pin`	Determines if a pin is required to check the voicemail from the users devices	`boolean()`	`false`	`false`	`supported`
`save_after_notify`	Move the voicemail to save folder after the notification has been sent (This setting will override delete_after_notify)	`boolean()`	`false`	`false`	`supported`
`seek_duration_ms`	callflow fastforward and rewind seek duration	`integer(0..)`	`10000`	`false`
`silence_hits`	The number of consecutive hits to see before the channel is considered silent	`integer(1..)`		`false`
`silence_threshold`	Threshold value compared to score - if score drops below threshold, add a hit. Lower threshold means quieter channel before hits start	`integer(1..)`		`false`
`skip_envelope`	Determines if the envelope should be skipped	`boolean()`	`false`	`false`	`beta`
`skip_greeting`	Determines if the greeting should be skipped	`boolean()`	`false`	`false`	`supported`
`skip_instructions`	Determines if the instructions after the greeting and prior to composing a message should be played	`boolean()`	`false`	`false`	`supported`
`timezone`	The default timezone	#/definitions/timezone		`false`	`supported`
`transcribe`	Transcribe voicemail using ASR engine	`boolean()`	`false`	`false`	`alpha`
`vm_message_forward_type`	Enable or disable the ability to prepend a message when forwarding a voicemail message	`string(‘only_forward'	'prepend_forward’)`	`only_forward`	`false`

notify.callback

Schema for a callback options

Key	Description	Type	Required
`attempts`	How many attempts without answer will system do	`integer()`	`false`
`disabled`	Determines if the system will call to callback number	`boolean()`	`false`
`interval_s`	How long will system wait between call back notification attempts	`integer()`	`false`
`number`	Number for callback notifications about new messages	`string()`	`false`
`schedule`	Schedules interval between callbacks	`array(integer())`	`false`
`timeout_s`	How long will system wait for answer to callback	`integer()`	`false`

timezone

The default timezone

Key	Description	Type	Default	Required	Support Level

Fetch all voicemail boxes for an account

GET /v2/accounts/{ACCOUNT_ID}/vmboxes

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": [
        {
            "id": "3a63acc3694ba189947235ae4727941b",
            "name": "VMBox 0",
            "flags": [],
            "mailbox": "3000",
            "owner_id": "f1d98a5df729f95cd208ee9430e3b21b",
            "messages": 4
        }
    ],
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Create a new voicemail box

PUT /v2/accounts/{ACCOUNT_ID}/vmboxes

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data": {"name": "VMBox 0", "require_pin": true, "is_setup": false, "pin": "0000", "mailbox": "3000", "timezone": "America/Los_Angeles", "check_if_owner": true, "delete_after_notify": false, "not_configurable": false, "notify_email_addresses": [], "save_after_notify": false, "skip_greeting": false, "skip_instructions": false, "owner_id": "f1d98a5df729f95cd208ee9430e3b21b", "media":{}}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "3a63acc3694ba189947235ae4727941b",
        "created": 63883426366,
        "modified": 63883426366
    },
    "data": {
        "name": "VMBox 0",
        "require_pin": true,
        "is_setup": false,
        "pin": "0000",
        "mailbox": "3000",
        "timezone": "America/Los_Angeles",
        "check_if_owner": true,
        "delete_after_notify": false,
        "not_configurable": false,
        "notify_email_addresses": [],
        "save_after_notify": false,
        "skip_greeting": false,
        "skip_instructions": false,
        "media": {},
        "after_forward_action": "save",
        "aliases": [],
        "announcement_only": false,
        "envelope_type": "default",
        "include_message_on_notify": true,
        "include_transcription_on_notify": true,
        "is_voicemail_ff_rw_enabled": false,
        "media_extension": "mp3",
        "oldest_message_first": false,
        "seek_duration_ms": 10000,
        "skip_envelope": false,
        "transcribe": false,
        "vm_message_forward_type": "only_forward",
        "id": "3a63acc3694ba189947235ae4727941b",
        "owner_id": "f1d98a5df729f95cd208ee9430e3b21b"
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Fetch a voicemail box

GET /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "3a63acc3694ba189947235ae4727941b",
        "created": 63883426366,
        "modified": 63883426366
    },
    "data": {
        "name": "VMBox 0",
        "require_pin": true,
        "is_setup": false,
        "pin": "0000",
        "mailbox": "3000",
        "timezone": "America/Los_Angeles",
        "check_if_owner": true,
        "delete_after_notify": false,
        "not_configurable": false,
        "notify_email_addresses": [],
        "save_after_notify": false,
        "skip_greeting": false,
        "skip_instructions": false,
        "id": "3a63acc3694ba189947235ae4727941b",
        "after_forward_action": "save",
        "aliases": [],
        "announcement_only": false,
        "envelope_type": "default",
        "include_message_on_notify": true,
        "include_transcription_on_notify": true,
        "is_voicemail_ff_rw_enabled": false,
        "media_extension": "mp3",
        "oldest_message_first": false,
        "seek_duration_ms": 10000,
        "skip_envelope": false,
        "transcribe": false,
        "vm_message_forward_type": "only_forward",
        "owner_id": "f1d98a5df729f95cd208ee9430e3b21b",
        "media": {}
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Change a voicemail box

POST /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data": {"name": "VMBox 0", "require_pin": true, "is_setup": false, "pin": "0000", "mailbox": "3000", "timezone": "America/Los_Angeles", "check_if_owner": true, "delete_after_notify": false, "not_configurable": false, "notify_email_addresses": [], "save_after_notify": false, "skip_greeting": false, "skip_instructions": false, "owner_id": "f1d98a5df729f95cd208ee9430e3b21b", "media":{}}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "3a63acc3694ba189947235ae4727941b",
        "created": 63883426366,
        "modified": 63883427077
    },
    "data": {
        "name": "VMBox 0",
        "require_pin": true,
        "is_setup": false,
        "pin": "0000",
        "mailbox": "3000",
        "timezone": "America/Los_Angeles",
        "check_if_owner": true,
        "delete_after_notify": false,
        "not_configurable": false,
        "notify_email_addresses": [],
        "save_after_notify": false,
        "skip_greeting": false,
        "skip_instructions": false,
        "id": "3a63acc3694ba189947235ae4727941b",
        "after_forward_action": "save",
        "aliases": [],
        "announcement_only": false,
        "envelope_type": "default",
        "include_message_on_notify": true,
        "include_transcription_on_notify": true,
        "is_voicemail_ff_rw_enabled": false,
        "media_extension": "mp3",
        "oldest_message_first": false,
        "seek_duration_ms": 10000,
        "skip_envelope": false,
        "transcribe": false,
        "vm_message_forward_type": "only_forward",
        "owner_id": "f1d98a5df729f95cd208ee9430e3b21b",
        "media": {}
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Patch a voicemail box

PATCH /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"some_key":"some_value"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "3a63acc3694ba189947235ae4727941b",
        "created": 63883426366,
        "modified": 63883427077
    },
    "data": {
        "name": "VMBox 0",
        "require_pin": true,
        "is_setup": false,
        "pin": "0000",
        "mailbox": "3000",
        "timezone": "America/Los_Angeles",
        "check_if_owner": true,
        "delete_after_notify": false,
        "not_configurable": false,
        "notify_email_addresses": [],
        "save_after_notify": false,
        "skip_greeting": false,
        "skip_instructions": false,
        "id": "3a63acc3694ba189947235ae4727941b",
        "after_forward_action": "save",
        "aliases": [],
        "announcement_only": false,
        "envelope_type": "default",
        "include_message_on_notify": true,
        "include_transcription_on_notify": true,
        "is_voicemail_ff_rw_enabled": false,
        "media_extension": "mp3",
        "oldest_message_first": false,
        "seek_duration_ms": 10000,
        "skip_envelope": false,
        "transcribe": false,
        "vm_message_forward_type": "only_forward",
        "owner_id": "f1d98a5df729f95cd208ee9430e3b21b",
        "media": {},
        "some_key": "some_value"
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Remove a voicemail box

DELETE /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "3a63acc3694ba189947235ae4727941b",
        "created": 63883426366,
        "modified": 63883427342,
        "deleted": true
    },
    "data": {
        "name": "VMBox 0",
        "require_pin": true,
        "is_setup": false,
        "pin": "0000",
        "mailbox": "3000",
        "timezone": "America/Los_Angeles",
        "check_if_owner": true,
        "delete_after_notify": false,
        "not_configurable": false,
        "notify_email_addresses": [],
        "save_after_notify": false,
        "skip_greeting": false,
        "skip_instructions": false,
        "vm_message_forward_type": "only_forward",
        "transcribe": false,
        "some_key": "some_value",
        "skip_envelope": false,
        "seek_duration_ms": 10000,
        "oldest_message_first": false,
        "media_extension": "mp3",
        "media": {},
        "is_voicemail_ff_rw_enabled": false,
        "include_transcription_on_notify": true,
        "include_message_on_notify": true,
        "envelope_type": "default",
        "announcement_only": false,
        "aliases": [],
        "after_forward_action": "save",
        "id": "3a63acc3694ba189947235ae4727941b",
        "owner_id": "f1d98a5df729f95cd208ee9430e3b21b"
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Fetch all voicemail messages for an account

GET /v2/accounts/{ACCOUNT_ID}/vmboxes/messages

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/messages

Fetch all messages for a voicemail box

GET /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages

Without pagination:

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "timestamp": 63630058722,
            "from": "1001@aeac33.sip.2600hz.com",
            "to": "1000@aeac33.sip.2600hz.com",
            "caller_id_number": "1001",
            "caller_id_name": "userb userb",
            "call_id": "79959ZDNmM2I5ZTliMzA0NzA4N2FjNjlmODA5OWVkZjUxZWU",
            "folder": "new",
            "length": 3140,
            "media_id": "201605-6aadef09f6fcf5fd8bcdfca312e923ba"
        },
        {
            "timestamp": 63630058413,
            "from": "1002@aeac33.sip.2600hz.com",
            "to": "1000@aeac33.sip.2600hz.com",
            "caller_id_number": "1002",
            "caller_id_name": "userd userd",
            "call_id": "79959MmNiMmJiMTIxODhjZjk0ZDhmOGNkMjJkN2MwNGQyNWY",
            "folder": "new",
            "length": 5500,
            "media_id": "201605-f0c3c16551a5ff7b5753a381892e2e01"
        }
    ],
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

With pagination:

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages?paginate=true

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "0e820108c0f4ca391500f3be1b02bdfa": {
                "timestamp": 63630058722,
                "from": "1001@aeac33.sip.2600hz.com",
                "to": "1000@aeac33.sip.2600hz.com",
                "caller_id_number": "1001",
                "caller_id_name": "userb userb",
                "call_id": "79959ZDNmM2I5ZTliMzA0NzA4N2FjNjlmODA5OWVkZjUxZWU",
                "folder": "new",
                "length": 3140,
                "media_id": "201605-6aadef09f6fcf5fd8bcdfca312e923ba"
            }
        },
        {
            "0e820108c0f4ca391500f3be1b02bdfa": {
                "timestamp": 63630058413,
                "from": "1002@aeac33.sip.2600hz.com",
                "to": "1000@aeac33.sip.2600hz.com",
                "caller_id_number": "1002",
                "caller_id_name": "userd userd",
                "call_id": "79959MmNiMmJiMTIxODhjZjk0ZDhmOGNkMjJkN2MwNGQyNWY",
                "folder": "new",
                "length": 5500,
                "media_id": "201605-f0c3c16551a5ff7b5753a381892e2e01"
            }
        }
    ],
    "next_start_key": [],
    "page_size": 50,
    "revision": "{REVERSION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Create a new voicemail message

PUT /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages

There are two methods for creating a new voicemail message - they differ in how you attach the media file.

In the first method, you can create a voicemail document first in one request and then put the media file into the document with a second request using /messages/{VM_MSG_ID}/raw API endpoint.

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d {"data":{"caller_id_name":"someone","caller_id_number":"6001","folder":"new","from":"1001@aeac33.sip.2600hz.com"}} \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
            "timestamp": 63630058722,
            "from": "1001@aeac33.sip.2600hz.com",
            "to": "1000@aeac33.sip.2600hz.com",
            "caller_id_number": "1001",
            "caller_id_name": "userb userb",
            "call_id": "79959ZDNmM2I5ZTliMzA0NzA4N2FjNjlmODA5OWVkZjUxZWU",
            "folder": "new",
            "length": 3140,
            "media_id": "201605-fadnew0mf6fcfgfd8bcdfca312e924bq"
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

And then you can use PUT method on the /messages/{VM_MSG_ID}/raw API endpoint to add the media to file (see PUT method for a message below).

In the second method, you can use a single PUT request and send a multipart content-type to add both the JSON metadata about the message and the media file itself, in a single request.

curl -v -X PUT \
     -H "Content-Type: multipart/mixed" \
     -F "content=@message.json; type=application/json" \
     -F "content=@voice.mp3; type=audio/mp3" \
     -H 'X-Auth-Token: {AUTH_TOKEN}' \
     http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/messages

The response is same as above.

Change a list of voicemail messages

POST /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages

Provide an array of message ids, e.g {"data": {"messages": ["MSG_ID1", "MSG_ID2", "MSG_ID3"]}} you can do following change operations on them. It will return two objects: the first is all the message ids that were successfully changed and the second one is those that failed with the reasons.

Change the folder of messages: set the folder that messages should move to (e.g. new or saved) by adding a query string ?folder=saved to the URL or set it in the payload as {"data": {"folder": "saved"}}.
Move messages to another voicemail box: set the destination voicemail box ID in payload like: {"data": {"source_id": "{NEW_VM_BOX_ID}"}}
Copy messages to a single or a list of voicemail boxes set the destination voicemail box ID in payload like: {"data": {"source_id": ["{NEW_VM_BOX_ID}"]}}

Note

If you didn’t move voicemail messages to the new format already, messages that are in old format will be moved to the new MODB format, which will cause their message id to change to the new format.

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data": {"folder": "saved", "messages": ["MSG_ID1", "MSG_ID2", "MSG_ID3"]}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "succeeded": ["201605-6aadef09f6fcf5fd8bcdfca312e923ba"],
        "failed": [{"201605-49be0985ea3a33046f8073083517d27b":"not_found"}]
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Remove all voicemail messages from a voicemail box

DELETE /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages

Deleting all message is easy, just use DELETE method on message API endpoint to delete all account’s messages.

Optional payload for deleting a group of messages:

One can apply a filter to delete all messages in a particular folder(e.g. new or saved) by adding a query string ?folder=saved to the URL or set it in the payload as {"data": {"folder": "saved"}}
Or providing an array of message ids, e.g {"data": {"messages": [MSG_ID1, MSG_ID2, ...]}}.

Note

If you didn’t move voicemail messages to the new format already, messages that are in old format will be moved to the new MODB format, which will cause their message id to change to the new format.

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "succeeded": ["201605-6aadef09f6fcf5fd8bcdfca312e923ba"],
        "failed": [{"201605-49be0985ea3a33046f8073083517d27b":"not_found"}]
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Fetch a single voicemail message

GET /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}

Note

If message doesn’t have a folder assign to it by any chance, it will be set to new by this method. Please also refer to the note for change the folder of a message regards of possible change of message id.

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "timestamp": 63630058722,
        "from": "1001@aeac33.sip.2600hz.com",
        "to": "1000@aeac33.sip.2600hz.com",
        "caller_id_number": "1001",
        "caller_id_name": "userb userb",
        "call_id": "79959ZDNmM2I5ZTliMzA0NzA4N2FjNjlmODA5OWVkZjUxZWU",
        "folder": "new",
        "length": 3140,
        "media_id": "201605-6aadef09f6fcf5fd8bcdfca312e923ba",
        "transcription": {
            "result": "success",
            "text": "This is a test of the voicemail transcription."
        }
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Change a single voicemail message

Change the folder of a message: set the folder that message should move to (e.g. new or saved) by adding a query string ?folder=saved to the URL or set it in the payload as {"data": {"folder": "saved"}}.
Move a message to another voicemail box: set the destination voicemail box ID in payload like: {"data": {"source_id": "{NEW_VM_BOX_ID}"}}
Copy a message to a single or a list of voicemail boxes set the destination voicemail box ID in payload like: {"data": {"source_id": ["{NEW_VM_BOX_ID}"]}}

POST /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}

Note

If you didn’t move voicemail messages to the new format already, messages that are in old format will be moved to the new MODB format, which will cause their message id to change to the new format.

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"folder": "saved"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "timestamp": 63630058722,
        "from": "1001@aeac33.sip.2600hz.com",
        "to": "1000@aeac33.sip.2600hz.com",
        "caller_id_number": "1001",
        "caller_id_name": "userb userb",
        "call_id": "79959ZDNmM2I5ZTliMzA0NzA4N2FjNjlmODA5OWVkZjUxZWU",
        "folder": "saved",
        "length": 3140,
        "media_id": "201605-6aadef09f6fcf5fd8bcdfca312e923ba",
        "transcription": {
            "result": "success",
            "text": "This is a test of the voicemail transcription."
        }
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Remove a single voicemail message

DELETE /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}

Note

If you didn’t move voicemail messages to the new format already, messages that are in old format will be moved to the new MODB format, which will cause their message id to change to the new format.

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "timestamp": 63630058722,
        "from": "1001@aeac33.sip.2600hz.com",
        "to": "1000@aeac33.sip.2600hz.com",
        "caller_id_number": "1001",
        "caller_id_name": "userb userb",
        "call_id": "79959ZDNmM2I5ZTliMzA0NzA4N2FjNjlmODA5OWVkZjUxZWU",
        "folder": "new",
        "length": 3140,
        "media_id": "201605-6aadef09f6fcf5fd8bcdfca312e923ba",
        "transcription": {
            "result": "success",
            "text": "This is a test of the voicemail transcription."
        }
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Fetch the raw audio of a list of voicemail messages as a ZIP file

POST /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/raw

You can provide a list of voicemail message ID in the payload and get raw audio of them in a single ZIP file.

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/zip" \
    -d '{"data": {"messages": ["MSG_ID1", "MSG_ID2", "MSG_ID3"]}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/raw

Fetch the raw audio for a voicemail message

GET /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}/raw

Note

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}/raw

Create the raw audio for a voicemail message

If you added a message based on the first method mentioned above (using PUT method on /messages), you can use this to upload the media file for the created message.

Note

If there’s already a media file attachment inside the message document it will be removed and replaced with the new media file!

PUT /v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}/raw

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: multipart/mixed" \
    -F "content=@voice.mp3; type=audio/mp3" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VM_BOX_ID}/messages/{VM_MSG_ID}/raw

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
            "timestamp": 63630058722,
            "from": "1001@aeac33.sip.2600hz.com",
            "to": "1000@aeac33.sip.2600hz.com",
            "caller_id_number": "1001",
            "caller_id_name": "userb userb",
            "call_id": "79959ZDNmM2I5ZTliMzA0NzA4N2FjNjlmODA5OWVkZjUxZWU",
            "folder": "new",
            "length": 3140,
            "media_id": "201605-fadnew0mf6fcfgfd8bcdfca312e924bq"
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Voicemail

About Voicemail

Differences between Kazoo version 3.x and 4.x

Schema

notify.callback

timezone

Fetch all voicemail boxes for an account

Create a new voicemail box

Fetch a voicemail box

Change a voicemail box

Patch a voicemail box

Remove a voicemail box

Fetch all voicemail messages for an account

Fetch all messages for a voicemail box

Create a new voicemail message

Change a list of voicemail messages

Remove all voicemail messages from a voicemail box

Fetch a single voicemail message

Change a single voicemail message

Remove a single voicemail message

Fetch the raw audio of a list of voicemail messages as a ZIP file

Fetch the raw audio for a voicemail message

Create the raw audio for a voicemail message

On this page