Module Skype :: Class Voicemail

Class Voicemail

source code

     object --+        
              |        
skypekit.Cached --+    
                  |    
    skypekit.Object --+
                      |
                     Voicemail

Wrapper class that includes voicemail-specific methods and properties. In the Skype Conversation API, Voicemail is actually something of a misnomer for what would be more accurately called Voice Message.

The traditional Voicemail use case involves recording a voice message when an incoming call does not get answered in a pre-determined amount of time. In the Skype Conversation API, voicemail does not depend on a call going unanswered - you can post a voice message asynchronously into any dialog conversation at any time.

In fact, a high-level action flow directing unanswered incoming live sessions to voicemail is not something provided by the Conversation API - implementation of this use case is largely up to your UI.

The fact that your UI must retrieve incoming Voicemails by monitoring changes to a Conversation instance's Messages illustrates this conceptual difference between traditional voicemail and voice messages. The message type Message::POSTED_VOICE_MESSAGE indicates that a Message instance should be handled as a voice message instead of by displaying its body text in the Conversation UI. Message::GetVoiceMessage enables you to retrieve the associated Voicemail instance; Voicemail::StartPlayback enables you to listen to the message audio.

To put it another way, the object chain goes like this: :

 Contact->Conversation->Message->Voicemail 

There are three basic types of Voicemail objects:

Before trying to send out a voicemail, you should ensure that target Contact has the capability to receive them. Use Contact::GetCapabilityStatus to check for Contact::CAPABILITY_CAN_BE_SENT_VM.

Recording and Sending a Voice Message

The first step is to obtain a dialog Conversation with the target Contact. In that conversation, you can initiate the outgoing voice message with Conversation::StartVoiceMessage

Note that this call does not return an actual Voicemail object. To catch when an object gets created, you will need to check Conversation::P_ACTIVE_VM_ID property updates.

After invoking Conversation::StartVoiceMessage, SkypeKit instantiates a Voicemail instance for the target Contact's greeting (with type CUSTOM_GREETING or DEFAULT_GREETING). At this point, the Conversation::P_ACTIVE_VM_ID property update fires, newVM contains a reference to the greeting, and playback of the greeting for the sender starts automatically.

Once the greeting playback finishes, SkypeKit instantiates a second Voicemail instance for the outgoing voice message. At this point, the Conversation::P_ACTIVE_VM_ID property update fires again, newVM now contains a reference to the outgoing message, and recording starts automatically. If you want to include notification and/or error handling for whether this message was sent successfully, you should make a copy of newVM now.

Once the user finishes (or abandons) recording of their message, they want to either send the message or to cancel it. To send the message, use Conversation::PostVoiceMessage; to cancel the message, use Conversation::LeaveLiveSession.

Both of these actions results in the Conversation::P_ACTIVE_VM_ID property update firing for a third time, setting the value to NULL. However, the Voicemail object will actually continue its existence past this point. Saving a reference to the message's Voicemail object when you start recording it enables you to keep receiving Voicemail property updates. This in turn enables your UI to check whether voice message send succeeded or failed.

The relevant terminal state Voicemail::P_STATUS property values are:

Receiving and Playing Back a Voice Message

On the remote side, the Voicemail appears as a Message object of type Message::POSTED_VOICE_MESSAGE. The message's author property contains the Skype Name of the Voicemail originator, and its BodyXml property contains the message length and title text in following format:

:

 <voicemail alt="Sent voicemail to people in this conversation."><message length="5" ></message></voicemail> 

Receiver side UI can then retrieve the Voicemail object from the message with Message::GetVoiceMessage and start local playback with Message::StartPlayback.

Instance Methods
 
_sk_init_(self, object_id, transport)
actual constructor
source code
 
__str__(self)
str(x)
source code
 
OnPropertyChange(self, property_name)
notifies from a property change
source code
 
StartRecording(self)
Start recording your own auto-answer greeting message (leave message after the beep...) only.
source code
 
StopRecording(self)
Stop recording of your own auto-answer greeting message only.
source code
 
StartPlayback(self)
Initiates playback of a voice message
source code
 
StopPlayback(self)
Terminates playback of a voice message
source code
 
Delete(self)
first from server, and then the local copy
source code
 
Cancel(self)
Canceling recording of your own auto-answer greeting message.
source code
 
CheckPermission(self)
check if we can send voicemail (unauth,blocked,no priv etc cases).
source code

Inherited from skypekit.Object: multiget

Inherited from skypekit.Cached: __copy__

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __subclasshook__

Static Methods
 
propid(propname)
convert a property name to the enum of the property
source code

Inherited from skypekit.Cached: __new__, sk_exists

Class Variables
  event_handlers = {}
  propid2label = {100: 'type', 101: 'partner_handle', 102: 'part...
  module_id = 7
  TYPE = {1: 'INCOMING', 2: 'CUSTOM_GREETING', 3: 'OUTGOING', 4:...
INCOMING
  STATUS = {1: 'NOTDOWNLOADED', 2: 'DOWNLOADING', 3: 'UNPLAYED',...
NOTDOWNLOADED
  FAILUREREASON = {1: 'MISC_ERROR', 2: 'CONNECT_ERROR', 3: 'NO_V...
MISC_ERROR
  P_TYPE = 100
  P_PARTNER_HANDLE = 101
  P_PARTNER_DISPNAME = 102
  P_STATUS = 103
  P_FAILUREREASON = 104
  P_SUBJECT = 105
  P_TIMESTAMP = 106
  P_DURATION = 107
  P_ALLOWED_DURATION = 108
  P_PLAYBACK_PROGRESS = 109
  P_CONVO_ID = 830
  P_CHATMSG_GUID = 831

Inherited from skypekit.Object: rwlock

Instance Variables

Inherited from skypekit.Object: properties

Properties
  type
  partner_handle
registered username of the other party
  partner_dispname
user's display name of the other party
  status
  failurereason
  subject
DEPRECATED: subject line
  timestamp
timestamp of creation
  duration
duration in seconds
  allowed_duration
max allowed duration in seconds
  playback_progress
VM playback progress in seconds
  convo_id
CONVERSATION_ID of corresponding conversation
  chatmsg_guid
GUID of the message that the VM is tied to

Inherited from object: __class__

Method Details

_sk_init_(self, object_id, transport)

source code 

actual constructor

Overrides: skypekit.Object._sk_init_

__str__(self)
(Informal representation operator)

source code 

str(x)

Overrides: object.__str__
(inherited documentation)

StartRecording(self)

source code 

Start recording your own auto-answer greeting message (leave message after the beep...) only. Recording of outgoing Voicemail messages start automatically (using Conversation::StartVoiceMessage) after playback of the remote side greeting message has finished.

StopRecording(self)

source code 

Stop recording of your own auto-answer greeting message only. To stop recording of and send an outgoing Voicemail, use Conversation::PostVoiceMessage.

Cancel(self)

source code 

Canceling recording of your own auto-answer greeting message. To stop recording of and cancel an outgoing Voicemail, use Conversation::LeaveLiveSession.

CheckPermission(self)

source code 

check if we can send voicemail (unauth,blocked,no priv etc cases). only OUTGOING

Return values:

  • result

Class Variable Details

propid2label

Value:
{100: 'type',
 101: 'partner_handle',
 102: 'partner_dispname',
 103: 'status',
 104: 'failurereason',
 105: 'subject',
 106: 'timestamp',
 107: 'duration',
...

TYPE

  • INCOMING
  • DEFAULT_GREETING
  • CUSTOM_GREETING
  • OUTGOING
Value:
{1: 'INCOMING',
 2: 'CUSTOM_GREETING',
 3: 'OUTGOING',
 4: 'DEFAULT_GREETING',
 'CUSTOM_GREETING': 2,
 'DEFAULT_GREETING': 4,
 'INCOMING': 1,
 'OUTGOING': 3}

STATUS

  • NOTDOWNLOADED
  • DOWNLOADING
  • UNPLAYED
  • BUFFERING
  • PLAYING
  • PLAYED
  • BLANK
  • RECORDING
  • RECORDED
  • UPLOADING
  • UPLOADED
  • DELETING
  • FAILED
  • DELETING_FAILED
  • CHECKING
  • CANCELLED
Value:
{1: 'NOTDOWNLOADED',
 2: 'DOWNLOADING',
 3: 'UNPLAYED',
 4: 'BUFFERING',
 5: 'PLAYING',
 6: 'PLAYED',
 7: 'BLANK',
 8: 'RECORDING',
...

FAILUREREASON

  • MISC_ERROR
  • CONNECT_ERROR
  • NO_VOICEMAIL_CAPABILITY
  • NO_SUCH_VOICEMAIL
  • FILE_READ_ERROR
  • FILE_WRITE_ERROR
  • RECORDING_ERROR
  • PLAYBACK_ERROR
  • NO_PERMISSION
  • RECEIVER_DISABLED_VOICEMAIL - receiver turned off voicemail
  • SENDER_NOT_AUTHORIZED - receiver has not authorized you and privacy is not set to anyone
  • SENDER_BLOCKED - receiver blocked sender
Value:
{1: 'MISC_ERROR',
 2: 'CONNECT_ERROR',
 3: 'NO_VOICEMAIL_CAPABILITY',
 4: 'NO_SUCH_VOICEMAIL',
 5: 'FILE_READ_ERROR',
 6: 'FILE_WRITE_ERROR',
 7: 'RECORDING_ERROR',
 8: 'PLAYBACK_ERROR',
...

Property Details

type

Get Method:
_sk_get_type(self)

partner_handle

registered username of the other party

Get Method:
_sk_get_partner_handle(self) - registered username of the other party

partner_dispname

user's display name of the other party

Get Method:
_sk_get_partner_dispname(self) - user's display name of the other party

status

Get Method:
_sk_get_status(self)

failurereason

Get Method:
_sk_get_failurereason(self)

subject

DEPRECATED: subject line

Get Method:
_sk_get_subject(self) - DEPRECATED: subject line

timestamp

timestamp of creation

Get Method:
_sk_get_timestamp(self) - timestamp of creation

duration

duration in seconds

Get Method:
_sk_get_duration(self) - duration in seconds

allowed_duration

max allowed duration in seconds

Get Method:
_sk_get_allowed_duration(self) - max allowed duration in seconds

playback_progress

VM playback progress in seconds

Get Method:
_sk_get_playback_progress(self) - VM playback progress in seconds

convo_id

CONVERSATION_ID of corresponding conversation

Get Method:
_sk_get_convo_id(self) - CONVERSATION_ID of corresponding conversation

chatmsg_guid

GUID of the message that the VM is tied to

Get Method:
_sk_get_chatmsg_guid(self) - GUID of the message that the VM is tied to