Developer Notes for 2.0 Skype release are now available.

The Skype API for Windows 2.0 introduces the following features:

• Make video calls
• Group contacts
• New buttons and screen appearance
• Tools to personalise Skype
• Change avatars
• Mood messages and timezone

This release also includes the following:

• Other enhancements
• Controlling ringing on PC speakers
• Page scrolling
• Managing echo and gain cancellation
• Contact management
• Managing call status
• Bugfixes
• Deprecations

More information

The Skype websites contain useful information for developers:

• The Skype Developer Zone is where to find all the Skype public API docs (including earlier versions) and where you can download free examples for Windows, Linux, and Mac platforms.
• Share ideas and information on the Skype Public API forum
.
• See the cool things people are creating and submit your project to the Skype Extras Gallery
.

Legal information

This document is the property of Skype Technologies S.A. and its affiliated companies (Skype) and is protected by copyright and other intellectual property rights laws in Luxembourg and abroad. Skype makes no representation or warranty as to the accuracy, completeness, condition, suitability, or performance of the document or related documents or their content, and shall have no liability whatsoever to any party resulting from the use of any of such documents. By using this document and any related documents, the recipient acknowledges Skype's intellectual property rights thereto and agrees to the terms above, and shall be liable to Skype for any breach thereof. For usage restrictions please read the end user license agreement (EULA).

Text notation

This document uses monospace font to represent code, file names, commands, objects and parameters. The following text conventions apply for syntax:

• CALL - uppercase text indicates a keyword, such as command, notification, and object.
• property - lowercase text indicates a category of a keyword
• <username> - angle brackets indicate an identifier, such as username or call id
• [<target>] - square brackets identify optional items
• * - asterisk indicates repetitive items
• | - vertical bar means "or"
• -> - command issued by client (used in examples)
• <- - response or notification from Skype (used in examples)
• // - comment line (used in examples)

Make video calls

Skype for Windows 2.0 introduces one-to-one video calls over the internet to members of the Skype community. Skype video enables the user to view a caller in the main Skype window, in a separate window, or in full screen mode. The user can also optionally view the video displayed to the other party in a secondary screen.

The following commands are introduced to support video calling:

• To set the video device to use for video calls:

-> GET VIDEO_IN
<- VIDEO_IN <devicename>
// if no value is returned, Skype uses the default value
-> SET VIDEO_IN <devicename>

• To check if the Skype client is video-enabled:

-> GET CALL 5921 VIDEO_STATUS
// VIDEO_STATUS can be one of the following values:
      VIDEO_NONE
      VIDEO_SEND_ENABLED
      VIDEO_RECV_ENABLED
      VIDEO_BOTH_ENABLED
// Skype responds with the video status for the active call, for example:
<- CALL 5921 VIDEO_STATUS VIDEO_NONE 

• To start or stop video during a call:

-> ALTER CALL 5921 { START_VIDEO_SEND | STOP_VIDEO_SEND }
-> ALTER CALL 5921 { START_VIDEO_RECEIVE | STOP_VIDEO_RECEIVE }

• To check video send and receive status:

-> GET CALL 5921 VIDEO_RECEIVE_STATUS
-> GET CALL 5921 VIDEO_SEND_STATUS
// Skype responds to each of these commands with one of the following values: 
      NOT_AVAILABLE // The client does not have video capability because video is disabled or a webcam is unplugged).
      AVAILABLE // The client is video-capable but the video is not running (can occur during a manual send).
      STARTING // The video is sending but is not yet running at full speed.
      REJECTED // The receiver rejects the video feed (can occur during a manual receive).
      RUNNING // The video is actively running.
      STOPPING // The active video is in the process of stopping but has not halted yet.
      PAUSED // The video call is placed on hold.
// For example, if video is running, Skype returns:
<- CALL 5921 VIDEO_RECEIVE_STATUS RUNNING
<- CALL 5921 VIDEO_SEND_STATUS RUNNING

• To check if a user is video-capable:

-> GET USER <username> IS_VIDEO_CAPABLE 
<- USER <username> IS_VIDEO_CAPABLE {True|False}

• To open the Video Test window to test if a video device is working:

-> OPEN VIDEOTEST

• To open the Video Options window:

-> OPEN OPTIONS VIDEO

Contents | Video | Groups | Buttons | Personalise | Enhancements | Bugfixes | Deprecations

Group contacts

Skype for Windows 2.0 introduces the ability to arrange contacts by groups, such as friends, colleagues and business contacts. One contact can be in a number of groups, for example a contact can be in an office group and a smaller project group. A user can start conference calls and chats or share files with all members of a group with just one click (subject to the standard limitations on numbers of participants).

The naming conventions in the Skype API and the Skype UI are somewhat different. The following logic is used when discussing contacts:

• Friends are contacts who are in my contactlist.
• Non-friends are contacts who are not in my contactlist.
• Users includes both contacts in my contactlist and users who are not in my contactlist.

Group object

A new GROUP object is added to the Skype API to enable this feature. There are two types of GROUP; custom groups and hardwired groups. Custom groups are user-defined groups, for example Office, Friends, and Family. Hardwire groups are "smart" groups defined and managed by Skype to support group activities. The GROUP object has the following properties:

• TYPE: {CUSTOM | HARDWIRED} // CUSTOM groups are user-defined and HARDWIRED groups are Skype-defined.
• CUSTOM_GROUP_ID // apersistent ID for custom groups which can be empty at the start of group creation.
• DISPLAYNAME // the display name of the group (read-write)
• NROFUSERS // the number of contacts in this group (read-only)
• NROFUSERS_ONLINE // the number of contacts online in this group (read-only)
• USERS // the list of contacts in the group (read-only)

Group commands

The following commands are introduced to support contact grouping:

• To list existing contact groups:

-> SEARCH GROUPS [{ ALL | CUSTOM | HARDWIRED }]
<- GROUPS <id1>, <id2>, <id3>, ...

• To query the members of a group:

-> GET GROUP <id> USERS
<- GROUP <id> USERS <user1>, <user2>, <user3>

• To query if a group is visible to the user:

-> GET GROUP <id> VISIBLE
<- GROUP <id> VISIBLE  {True|False}

• To query whether to expand a group in the Contacts window:

-> GET GROUP EXPANDED
<- GROUP <id> EXPANDED  {True|False}

• To get the display name for a group:

-> GET GROUP <id> DISPLAYNAME 
<- GROUP <id> DISPLAYNAME <name>

• To change the name of a group:

-> SET GROUP <id> DISPLAYNAME <name>
<- GROUP <id> DISPLAYNAME <name>

• To query the group type:

-> GET GROUP <id> TYPE 
<- GROUP <id> TYPE <contact_group_type>

• To create a contact group called Office:

-> CREATE GROUP <Office>
<- CREATE GROUP <Office>

The command triggers a number of GROUP properties events:
<- GROUP <234> TYPE CUSTOM_GROUP
<- GROUP <234> NROFUSERS 0
<- GROUP <234> NROFUSERS_ONLINE 0
<- GROUP <234> CUSTOM_GROUP_ID <111>
<- GROUP <234> DISPLAYNAME <Office>
<- GROUP <234> USERS

• To remove this contact group:

-> DELETE GROUP <234>
<- DELETE GROUP <234>

• The DELETE GROUP command also triggers the following notification:

<- DELETED GROUP <234>

• The CREATE GROUP and DELETE GROUP commands trigger a contact notification:

<- GROUP <234> USERS <user1> <user2>...

• When contacts are added to a group or removed from a group, the following notification event occurs:

<- GROUP <234> NROFUSERS y

• To add a contact to a group:

-> ALTER GROUP <234> ADDUSER <userhandle|PSTN>
<- ALTER GROUP <234> ADDUSER <userhandle|PSTN>

• To remove a contact from a group:

-> ALTER GROUP <id> REMOVEUSER <userhandle|PSTN>
<- ALTER GROUP <id> REMOVEUSER <userhandle|PSTN>

Note: A contact must exist in a contactlist to be assigned to a group.

Error codes

Contact group commands can generate the following errors:

• ERROR 561, "SEARCH GROUPS: invalid target"
• ERROR 562, "Invalid group id"
• ERROR 563, "Invalid group object"
• ERROR 564, "Invalid group property given"

HARDWIRE type groups are preset by Skype.

• To query a GROUP type:

-> GET GROUP 277 TYPE
<- GROUP 277 TYPE ALL_FRIENDS

HARDWIRE GROUPS are described in the following table.

Contents | Video | Groups | Buttons | Personalise | Enhancements | Bugfixes | Deprecations

New buttons and appearance

Download new Skype buttons to use in your applications from:
Skype buttons

Personalise Skype

Skype for Windows 2.0 provides a number of enhancements to personalise the Skype user experience:

• Change avatars
• Mood messages and timezone

Change avatars

• To change the avatar picture for a user profile:

-> SET AVATAR <id> <filePath + fileName>[:idx]
<- AVATAR <id> <filePath + fileName>

• The SET AVATAR command has the following parameters:

id // avatar ID
filePath // path to the avatar file directory
fileName:idx //  IDX refers to the image ID in the .skype content file

Error codes

The SET AVATAR command can generate the following error codes:

• ERROR 114, Invalid avatar
• ERROR 111, File not found
• ERROR 9901 internal error, The wrong type of file (for example an audio file or a document) is set to avatar.

Contents | Video | Groups | Buttons | Personalise | Enhancements | Bugfixes | Deprecations

Mood messages and timezone

In Skype for Windows 2.0, users can display text messages next to their avatars in the Contacts and Chat windows. As with avatars, users can change these messages to reflect their mood. A user’s profile also displays the timezone offset from GMT. The mood_text and timezone features are properties of the USER object and were introduced in the Skype API version 1.4, but not implemented until the current release.

Currently, the user cannot control when changed mood messages become visible to other users. When a user changes mood_text there can be a small delay before other users see it.

• To enter a mood_text message:

-> SET PROFILE MOOD_TEXT Life is great and then you...
<- PROFILE MOOD_TEXT Life is great and then you...

• To query a mood_text message:

-> GET PROFILE MOOD TEXT 
<- PROFILE MOOD_TEXT Life is great and then you...

• To get the mood_text of another user:

-> GET USER santa MOOD_TEXT
<- USER elvis MOOD_TEXT Are you lonesome tonight

• To query the TIMEZONE for a user:

-> GET PROFILE TIMEZONE
<- PROFILE TIMEZONE 93600

• To query the TIMEZONE for another user:

-> GET USER elvis TIMEZONE
<- USER elvis TIMEZONE 86400

Contents | Video | Groups | Buttons | Personalise | Enhancements | Bugfixes | Deprecations

Other changes

The Skype for Windows API 2.0 includes a number of additional changes:

• Controlling ringing on PC speakers
• Page scrolling
• Managing echo and gain cancellation
• Contact management
• Managing call status

Controlling ringing on PC speakers

If no speakers are connected to a PC, it is possible to hear incoming Skype calls only when wearing a headset. To overcome this inconvenience, use the following commands to query and/or change the status of the PC speaker:

-> GET PCSPEAKER 
<- PCSPEAKER {ON|OFF} 
-> SET PCSPEAKER {ON|OFF} 
<- PCSPEAKER {ON|OFF}

Contents | Video | Groups | Buttons | Personalise | Enhancements | Bugfixes | Deprecations

Page scrolling

The current version of the Skype API provides the ability to simulate page scrolling through the contactslist from an external device. To simulate page scrolling

BTN_PRESSED {PAGEUP|PAGEDOWN}
BTN_RELEASED {PAGEUP|PAGEDOWN}

Managing gain control and echo cancellation

Skype uses automatic gain control (AGC) to adjust microphone level to the volume the user speaks at. Skype uses automatic echo cancellation (AEC) to eliminate the echo that occurs if a microphone "hears" the other user's voice on the loudspeaker.

IMPORTANT: Disabling these functions can impair call quality and is not recommended in standard implementations. However, some audio devices have in-built AGC/AEC mechanisms and, in these circumstances, it can be necessary to deactivate AGC and AEC on Skype. If you disable AGC/AEC on Skype, ensure that the client defaults to enabled if the audio device is removed.

• To query if AGC and AEC are enabled:

-> GET AGC
<- AGC { ON | OFF }
-> GET AEC
<- AEC { ON | OFF }

• To activate AGC and AEC:

-> SET AGC ON
<- AGC ON
-> SET AEC ON
<- AEC ON 

Error codes

These commands can generate the following errors:

• ERROR 569, "GET AEC: target not allowed"
• 570, "SET AEC: invalid value"
• 571, "GET AGC: target not allowed"
• 572, "SET AGC: invalid value"

Contents | Video | Groups | Buttons | Personalise | Enhancements | Bugfixes | Deprecations

Improved contact management

• To change the display name for a contact:

SET USER <handle|PSTN> DISPLAYNAME name

• To send contacts to multiple targets:

OPEN SENDCONTACTS target1 target2 ... 

Controlling call status

• Use the ALTER CALL command to control call status:

ALTER CALL xxx 
  { ANSWER
  | HOLD
  | RESUME
  | HANGUP
  | END { HANGUP | REDIRECT_TO_VOICEMAIL | FORWARD_CALL } // for an incoming ringing call
  | DTMF <0|1|..|9|*|#>
  | JOIN_CONFERENCE <callID> }

Error codes

This command can generate the following errors:

• ERROR 555, "CALL: No proper call ID given"
• ERROR 556, "CALL: Invalid call ID given"
• ERROR 557, "CALL: No action given"
• ERROR 558, "CALL: Missing or invalid arguments"
• ERROR 559, "CALL: Action failed"
• ERROR 560, "CALL: Unknown action"

Note: With the ALTER CALL xxx END FORWARD_CALL command:

• If the user has voicemail enabled and call forwarding is not configured, the call is forwarded to voicemail.
• If user has call forwarding enabled, if the call is not answered it is forwarded on to voicemail.

This command replaces the SET_CALL xxx STATUS command which has been deprecated in this release.

Contents | Video | Groups | Buttons | Personalise | Enhancements | Bugfixes | Deprecations

Bugfixes

In earlier versions of Skype, the following command did not have the desired effect:

SET AUTOAWAY OFF

The issue occured because the command was being executed both at UI level and at framework level. This command is no longer executed at the UI level.

Deprecated commands

The following command is deprecated (but not removed) in this release:

SET CALL xxx STATUS {ONHOLD | INPROGRESS | FINISHED }

Contents | Video | Groups | Buttons | Personalise | Enhancements | Bugfixes | Deprecations