Voicemail Box

URI

  • v1/accounts/{account_id}/vmboxes
Property
Description
Validation
Modifiable
mailbox The mailbox number used to access this voicemail number, required yes
pin The pin number used to access this voicemail box   yes
timezone The timezone used when playing the timestamp that a message was left   yes
require_pin When set to true, any caller checking the mailbox will have to enter a valid pin to continue (regardless of ownership), default false boolean yes
check_if_owner By default or when true if the caller leaving a voicemail has called from a device owned by the mailbox owner redirect them to the check main menu boolean yes
skip_greeting If true then the greeting is not played when composing a voicemail message boolean yes
skip_instructions If true then the instructions are not played when composing a voicemail message boolean yes
owner_id The ID of the owner (user) of this device   yes
Verb
Accepted
Returned
Description
GET   [data:{id, mailbox},...] Fetches a summary of voicemail boxes
PUT ANY ALL Create a new voicemail box
  • Normal Response Code(s): 200
  • Error Response Code(s): 400, 401, 415, 500, 503, 504

URI

  • v1/accounts/{account_id}/vmboxes/{vmbox_id}
Property
Description
Validation
Modifiable
mailbox The mailbox number used to access this voicemail number, required yes
pin The pin number used to access this voicemail box   yes
timezone The timezone used when playing the timestamp that a message was left   yes
require_pin When set to true, any caller checking the mailbox will have to enter a valid pin to continue (regardless of ownership), default false boolean yes
check_if_owner By default or when true if the caller leaving a voicemail has called from a device owned by the mailbox owner redirect them to the check main menu boolean yes
skip_greeting If true then the greeting is not played when composing a voicemail message boolean yes
skip_instructions If true then the instructions are not played when composing a voicemail message boolean yes
owner_id The ID of the owner (user) of this device   yes
max_message_count How many messages the mailbox can hold   yes
message_max_duration Maximum duration of a message (seconds)   yes
message_retention_duration The maximum number of days a message can be retained after being heard   yes
Verb
Accepted
Returned
Description
GET   ALL Fetch the details of a voicemail box
POST ANY ALL Update the parameters of a voicemail box
DELETE     Delete a voicemail box
  • Normal Response Code(s): 200, 201
  • Error Response Code(s): 400, 401, 404, 415, 500, 503, 504

URI

  • v1/accounts/{account_id}/vmboxes/{vmbox_id}/messages
Property
Description
Validation
Modifiable
timestamp The date when the voicemail message call was made   no
from ...   no
to ...   no
caller_id_number ...   no
caller_id_name ...   no
call_id ...   no
folder The folder were the voicemail message is stored   yes
attachment The voicemail message audio file   no
 

 

  • Timestamps are in UTC Gregorian seconds. To convert to the more common UTC Unix epoch time subtract the constant 62167219200
Verb
Accepted
Returned
Description
GET   ALL Fetch the details of a voicemail box's messages
  • Normal Response Code(s): 200
  • Error Response Code(s): 400, 401, 404, 415, 500, 503, 504

URI

  • v1/accounts/{account_id}/vmboxes/{vmbox_id}/messages/{message_id}
  • message_id is the attachment name except the audio file extension
Property
Description
Validation
Modifiable
timestamp The date when the voicemail message call was made   no
from Caller's SIP address   no
to Receiver's SIP address   no
caller_id_number Caller's number   no
caller_id_name Caller's name   no
call_id Unique identifier of the call   no
folder The folder were the voicemail message is stored   yes
attachment The voicemail message audio file   no

 

 
  • Timestamps are in UTC Gregorian seconds. To convert to the more common UTC Unix epoch time subtract the constant 62167219200
Verb
Accepted
Returned
Description
GET   ALL Fetch the details of a voicemail box
POST folder ALL Update the parameters of a voicemail box
DELETE     Set the voicemail message folder to "deleted"
  • Normal Response Code(s): 200
  • Error Response Code(s): 400, 401, 404, 415, 500, 503, 504

URI

  • v1/accounts/{account_id}/vmboxes/{vmbox_id}/messages/{message_id}/raw
  • message_id is the attachment name except the audio file extension
PropertyDescriptionValidationModifiable
Verb
Accepted
Returned
Description
GET   BINARY_PAYLOAD Fetch the binary detail

Normal Response Code(s): 200

Error Response Code(s): 400, 401, 404, 415, 500, 503, 504

Property
Description
Validation
Modifiable
action The action to take, defaults to compose ["compose"|"check"] yes
id The mailbox ID, if provided   yes

 

  •  
If the mailbox ID is not provided with the action compose a prompt will be played to the caller that the mailbox is not avaliable (or if the ID is invalid). However, if the mailbox ID is not provided on with the action check then the caller will be prompted to enter the mailbox number; otherwise it will take the appropriate action to check the provided mailbox (IE: ask for pin if required or directly sign in if the caller is the owner).
{
"module":"voicemail",
"data": {
"id": "xyz987",
"action": "check"
},
"children": {}
}
Method GET
URI v1/accounts/{account_id}/vmboxes
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body  
Response Body
{
  
"auth_token":"abc123",
"status":"success",
"data":[
{
"id":"xyz987",
"mailbox":"2000"
}
]
}
Response Headers 200 OK
Content-Type: application/json

Method PUT
URI v1/accounts/{account_id}/vmboxes
Request Headers X-Auth-Token: abc123
Accept: application/json
Content-Type: application/json
Request Body  
{
"data":{
"mailbox":"2000",
"pin":"1234",
"timezone":"Pacific/New Zealand",
"skip_greeting":false,
"skip_instructions":false
}
}
Response Body  
Response Headers 201 OK
Location: v1/accounts/{account_id}/vmboxes/{vmbox_id}
Method GET
URI v1/accounts/{account_id}/vmboxes/{vmbox_id}
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body  {
"auth_token":"abc123",
"status":"success",
"data":{
"mailbox":"2000",
"pin":"1234",
"timezone":"Pacific/New Zealand",
"skip_greeting":false,
"skip_instructions":false
}
}
Response Body  
Response Headers 200 OK
Method POST
URI v1/accounts/{account_id}/vmboxes/{vmbox_id}
Request Headers X-Auth-Token: abc123
Accept: application/json
Content-Type: application/json
Request Body
{
"data":{
"mailbox":"2000",
"pin":"9876",
"timezone":"Pacific/Auckland",
"skip_greeting":false,
"skip_instructions":false
}
}
Response Body  {
"auth_token":"abc123",
"status":"success",
"data":{
"mailbox":"2000",
"pin":"9876",
"timezone":"Pacific/Auckland",
"skip_greeting":false,
"skip_instructions":false
}
}
Response Headers 200 OK
Method DELETE
URI v1/accounts/{account_id}/vmboxes/{vmbox_id}
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body
Response Body
{
"auth_token":"abc123",
"status":"success",
"data":[]
}
Response Headers 200 OK
Method GET
URI v1/accounts/{account_id}/vmboxes/{vmbox_id}/messages
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body  
Response Body
{
"auth_token":"abc123",
"status":"success",
"data": [{
"timestamp":"63471978273",
"from":"bob@conversant.co.nz",
"to":"alice@conversant.co.nz",
"caller_id_number":"1234567890",
"caller_id_name": "Bob C.",
"call_id":"ODNjNTMzZWZjNzFkODY5ZjY2Nzg1MGNkOTg0ZGNjNTE.",
"folder":"new",
"attachment":"d8646cca085448848576f41b29e2746b.wav"
},   
{
"timestamp":"63471977609",
"from":"charlie.b@carrier.com",
"to":"alice@conversant.co.nz",
"caller_id_number":"+49348567814",
"caller_id_name":"Charlie B",
"call_id":"YjE3Njg2MWY5ZTQ1MmM5YTQ5OGRmZTc3Y2VkNWNiZTk.",
"folder":"archived",
"attachment":"3ce0d6aa9ba00ff662eeb7fd3c3cd689.wav"
}]
}
Response Headers 200 OK
Method GET
URI v1/accounts/{account_id}/vmboxes/{vmbox_id}/messages/3ce0d6aa9ba00ff662eeb7fd3c3cd689
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body  
Response Body
{
"auth_token":"abc123",
"status":"success",
"data": {
"timestamp":"63471977609",
"from":"charlie.b@carrier.com",
"to":"alice@conversant.co.nz",
"caller_id_number":"+49348567814",
"caller_id_name":"Charlie B",
"call_id":"YjE3Njg2MWY5ZTQ1MmM5YTQ5OGRmZTc3Y2VkNWNiZTk.",
"folder":"archived",
"attachment":"3ce0d6aa9ba00ff662eeb7fd3c3cd689.wav"
}
}
Response Headers 200 OK
Method GET
URI v1/accounts/{account_id}/vmboxes/{vmbox_id}/messages/3ce0d6aa9ba00ff662eeb7fd3c3cd689/raw
Request Headers X-Auth-Token: abc123
Accept: application/octet-stream
Request Body  
Response Body  File binary
Response Headers  200 OK 
Content-Type: application/octet-stream 
Content-Length: 1234