The document contains the following information:

Overview of the Skype API
Using the Skype API on Windows
Using the Skype API on Linux
Using the Skype API on Mac
Skype protocol
Skype reference
Skype URI
Skype release notes
Skype commands list

API reference for Skype 2.0 (beta)

This section describes this guide to help you find what you want quickly. If you are developing for the Skype API, please read the complete document and understand its technical and procedural information.

Purpose of this guide

This document describes the public Skype application programming interface (API), version 2.0 for Windows, the Skype APIs for Linux and Mac, and provides a reference guide for the Skype developer community.

Who reads this guide?

Skype's developer community who work with us to enrich the Skype experience and extend the reach of free telephone calls on the internet.

What is in this guide?

This document contains the following information:

Overview of the Skype API
Using the Skype API on Windows
Using the Skype API on Linux
Using the Skype API on Mac
Skype protocol
Skype reference
Skype URI
Skype release notes
Skype commands list

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)

Contents

Overview of the Skype API

The Skype API passes commands in simple text messages between Skype and client applications and devices. Client applications can be applications which extend Skype functionality and devices can be hardware or software devices, such as USB phones. The Skype API has two main components; the Skype phone API and the Skype access API.

Skype protocol

The Skype protocol defines communications in Skype. Skype releases new versions of the protocol periodically to enable new communication features in Skype. Skype always uses the correct protocol version to match the protocol version reported by a connecting device or application. Skype never responds with a higher protocol than the connecting device or application and the default protocol it uses is version 1.

Skype phone API

The Skype phone API provides an interface to connecting devices such as USB phones. The Skype client controls the API and triggers events on the device (or application) driver. The connecting device receives abstract events such as:

the green button is pressed
the handset is off-hook
the device rings

During installation, Skype detects compatible audio drivers and installs them. If a new device and driver are added after Skype installation, Skype detects the new driver but the user must select the driver manually for it to become operational.

The Skype phone API uses the following commands to communicate with Skype, substituting values and setting indicators as appropriate:

NAME deviceName PROTOCOL version AUDIO_IN deviceName AUDIO_OUT deviceName HOOK ON|OFF MUTE ON|OFF BTN_PRESSED (0-9,A-Z,#,*,+,UP,DOWN,YES,NO,SKYPE) BTN_RELEASED ...

The Skype phone API uses the MUTE ON|OFF command to control the mute function on a device.

Skype access API

The Skype access API enables external applications to control certain Skype functions, for example to place a call or to get a Skype user profile. In the interests of privacy and security, before an external application can take control, Skype pops up the name of the application to the user and asks if it is OK to allow access.

When a client application starts controlling Skype, Skype switches audio devices to the devices reported by the controlling client.

The Skype access API has the following characteristics:

All actions performed using the API are mirrored on the Skype client.
Multiple applications can use the Skype access API at the same time.
All times and dates in the API are in UTC (Coordinated Universal Time)
Transmission over the API is in UTF-8 encoding.

Contents > Overview

Using the Skype API on Windows

When developing applications to work with Skype, follow these general guidelines:

Give intuitive names to executable files (.exe files) because this name is displayed to the user for confirmation. If the name is unclear, the user might not allow the application to access Skype.
Sign applications with VeriSign's CodeSigning certificate.
The application must support the NAME command and publish its name.

Skype for Windows sends and receives API commands using WM_COPYDATA messages. Use the RegisterWindowMessage method to register the following messages:

SkypeControlAPIDiscover
SkypeControlAPIAttach

To initiate communication, a client application broadcasts the SkypeControlAPIDiscover message, including its window name as a wParam parameter. Skype responds with a SkypeControlAPIAttach message to the specified window name and indicates the connection status with one of the following values:

SKYPECONTROLAPI_ATTACH_SUCCESS = 0 - The client is attached and the API window handle is provided in wParam parameter.
SKYPECONTROLAPI_ATTACH_PENDING_AUTHORIZATION = 1 - Skype acknowledges the connection request and is waiting for user confirmation. The client is not yet attached and must wait for the SKYPECONTROLAPI_ATTACH_SUCCES message.
SKYPECONTROLAPI_ATTACH_REFUSED = 2 - The user has explicitly denied access to client.
SKYPECONTROLAPI_ATTACH_NOT_AVAILABLE = 3 - The API is not available at the moment, for example because no user is currently logged in. The client must wait for a SKYPECONTROLAPI_ATTACH_API_AVAILABLE broadcast before attempting to connect again.

When the API becomes available, Skype broadcasts the SKYPECONTROLAPI_ATTACH_API_AVAILABLE = 0x8001 message to all application windows in the system. The data exchange uses commands (or responses), provided as null-terminated UTF-8 strings. The terminating 0 must be transferred as well. You cannot combine several messages in one packet. There is no limit to the length of the transferred string.

Note: The result of processing the message must be different from zero (0), otherwise Skype considers that the connection broken.

If the API client spends more than 1 second processing a message, the connection is disconnected. Use the PING command to test the connection status. To ease debugging during development, in regedit enter the key APITimeoutDisabled (DWORD value, 0 = timeout enabled 1 = timeout disabled) into the HKCU\Software\Skype\Phone\UI file in the registry to override the 1 second timeout.

To check if Skype is installed, in regedit check if the following key exists: HKCU\Software\Skype\Phone, SkypePath. This key points to the location of the skype.exe file. If this key does not exist, check if the HKLM\Software\Skype\Phone, SkypePath key exists. If the HKCU key does not exist but the HKLM key is present, Skype has been installed from an administrator account has but not been used from the current account.

Download free examples

Example code for C++

Contents > Windows

Using the Skype API on Linux

The Skype API for Linux uses the Skype protocol, version 1.1.0.3. The API uses the d-bus messaging framework and you can download the d-bus libraries from freedesktop.org.

If RPM Package Manager is installed on the Linux device, the d-bus files are automatically configured. If RPM is not installed, create a text file named skype.conf, and save it to /etc/dbus-1/system.d/skype.conf.

The configuration file enables the Skype API to use the d-bus framework and contains the following:

<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" 
 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
  <policy context="default">
    <allow own="com.Skype.API"/>
    <allow send_destination="com.Skype.API"/>
    <allow receive_sender="com.Skype.API"/>
    <allow send_path="/com/Skype"/>
  </policy>
</busconfig>

To access the Skype API from a client application:

The application passes its name to Skype:

	<- NAME clientApplication

Skype pops up a confirmation window to the user with the following response:

	ClientApplication wants to talk to Skype. OK?

If OK, protocol messages are exchanged:

	-> OK
	<- PROTOCOL 1
	-> PROTOCOL 1

The Skype protocol manages the subsequent session. The d-bus service is com.Skype.API

Two communication paths are used:

for client-to-Skype commands the path is /com/Skype
for Skype-to-client commands the path is /com/Skype/Client

Two methods are used:

use the Invoke method with one string parameter for client-to-Skype commands
use the Notify method for Skype-to-client commands and responses

More information and examples

Read the Skype API for Linux guide and download free examples for C and for Python.

Contents > Linux

Using the Skype API on Mac

The Skype API for Mac has interfaces for Cocoa, Carbon, and AppleScript. The Cocoa and Carbon interfaces are implemented in Skype.framework. Skype recommends that you include the Skype framework in your application as an embedded framework. To do so, copy it into the application bundle and link it to the application.

Client applications send string commands to control Skype. The format of these strings commands is described in the Skype API reference. If you are using a Cocoa or Carbon interface, Skype will send information back to your application by calling asynchronous delegate functions/methods.

More information and examples:

Read the Skype API for Mac guide and download the Skype framework and free examples.

Contents > Mac

Skype protocol

The Skype protocol is currently in its fifth version. Starting with protocol 1 (the first Skype protocol) a new version is created only when new commands become incompatible with existing commands. The protocol number does not increase when new commands are introduced but existing commands remain unchanged.

Protocol 5

Protocol 5 is the current version of the Skype protocol and is used by the following versions of Skype:

2.0 - Windows
1.4.0.84 - Windows
1.3.0.33 - Windows and Mac

This protocol introduced multiperson chat commands, one-to-one video calls, call forwarding, and contact grouping.

Protocol 4

Protocol 4 is used by the following versions of Skype:

1.2.0.11 - Windows
1.1.0.3 Windows and Linux

This protocol introduced ISO code prefixes for language and country.

Protocol 3

Protocol 3 is used by the following version of Skype:

1.1.0.61 - Windows

This protocol introduced a compatibility layer for previous instant messaging.

Protocol 2

Protocol 2 is used by the following version of Skype:

1.0.0.94

This protocol implemented the following changes:

Introduced the SKYPEME online status
For calls on hold, notifies clients with either LOCALHOLD or REMOTEHOLD. Protocol 1 simply returned ONHOLD.
Introduces the call status, CANCELLED.

Protocol 1 and 2 compatibility

If the requested protocol is smaller than 3, all incoming commands are converted as follows:

SEARCH MESSAGES -> SEARCH CHATMESSAGES
SEARCH MISSEDMESSAGES -> SEARCH MISSEDCHATMESSAGES
GET MESSAGE -> GET CHATMESSAGE
SET MESSAGE -> SET CHATMESSAGE

The GET MESSAGE properties are also converted:

PARTNER_HANDLE -> FROM_HANDLE
PARTNER_DISPNAME -> FROM_DISPNAME

All API notification (including GET/SET MESSAGE) replies are converted:

CHATMESSAGE * FROM_HANDLE x -> MESSAGE * PARTNER_HANDLE x
CHATMESSAGE * FROM_DISPNAME x -> MESSAGE * FROM_DISPNAME x
CHATMESSAGE * property x -> MESSAGE * property x

If the protocol is less than 3, SEARCH MESSAGES and SEARCH MISSEDMESSAGES commands return string MESSAGES 1, 2, 3.

Contents > Protocol

Skype API reference

The Skype API reference is a guide for developers working with the public Skype API. The reference contains the following information:

Terminology
Commands
Objects
Object properties
General parameters
Notifications
Error codes

Terminology

The Skype API reference uses the following terms:

The Skype access API is also known as the Skype control API.
The client application issues a command to control Skype.
In reply to some commands, Skype returns a synchronous response. Not all commands require a response. Responses are documented under their relevant commands.
Skype objects are application, call, chat, chatmessage, profile, user, and voicemail.
A notification is an asynchronous message Skype sends to a client when a change occurs, for example when a contact comes online or a new chatmessage is received.
Skype has general parameters to control the setup, current user and connection information.
Connectable users are online Skype users who are in the client contact list and also non-contacts who are in active communication with the client.

Reference > Contents

Commands

This section provides a reference to the commands used in Skype, and contains the following:

Description of command identifiers
Commands for making and managing voice calls.
Commands for making and managing video calls.
Commands for leaving and manipulating voicemails.
Commands for creating chats and sending messages
Commands for managing contacts and groups
Commands to personalise Skype
Search commands
Commands for managing history
Commands for controlling the Skype user interface
Application to application commands
Call forwarding
Testing connections

Commands > Reference > Contents

Command identifiers

A command identifier is useful to identify a response to a specific command. A command identifier is supported by most commands and is included in the response.

Syntax: #<command_id> command
Response: #<command_id> response|error
Parameters: command_id - client assigned alphanumeric identifier
Errors: all possible errors for a given command
Version: Protocol 4
Notes

A command identifier is not included in asynchronous notification events initiated by a command.
Asynchronous commands usually return a synchronous response with the command id. When the command is processed an asynchronous notification is also sent
A response may come not directly after the command because there can other messages can be received between command and response.

Examples

Simple response to command

-> #AB GET USERSTATUS 
<- #AB USERSTATUS ONLINE

Invalid command with reported error

-> #123 GET XZY 
<- #123 ERROR 7 GET: invalid WHAT

Command response and notification

-> #cmd11 SET USERSTATUS ONLINE 
// this is the response for the command
<- #cmd11 USERSTATUS ONLINE
// this is notification when the command is actually processed
<- USERSTATUS ONLINE

Command response and notification are asynchronous

-> #50 CALL +18005551234 
// note that events can arrive before response
<- CALL 651 STATUS ROUTING
<- #50 CALL 651 STATUS ROUTING
<- CALL 651 PSTN_STATUS 10503 Service Unavailable
// the following events do not have a command id
<- CALL 651 FAILUREREASON 1
<- CALL 651 STATUS FAILED

Notifications can appear between command-response

-> #50 PING 
// note that other events can arrive before command response
<- USER echo123 LASTONLINETIMESTAMP 1105764678
<- USER echo123 FULLNAME Echo Test Service
<- USER test LASTONLINETIMESTAMP 1105487965
// Now comes Skype response to command
<- #50 PONG

Commands > Reference > Contents

Making and managing voice calls

This section describes the commands for making and managing voice calls. The commands are:

Use the CALL command to make a call.
Use the GET CALL command to retrieve call information.
Use the SET CALL INPROGRESS command to take an incoming call.
Use the SET CALL FINISHED command to end a call.
Use the SET CALL ONHOLD command to place a call on hold.
Use the SET CALL JOIN CONFERENCE command to join a call to a conference.
Use the SET CALL DTMFcommand to set DTMF for a call.
Use the SET CALL SEEN command to mark a missed call as seen in order to clear the missed events list.
Use the ALTER CALL command to control call status.

Refer to Making and managing video calls for a description of video call commands.
Refer to Call failure reasons for a list of all reasons for call failure.

Calls > Commands > Reference > Contents

`CALL`

Syntax

CALL <target>[, <target>]*

Response

CALL <call_ID> <status>

Parameters

<target> - targets to be called. In case of multiple targets conference is created. Available target types:

USERNAME - Skype username, e.g. "pamela", "echo123"
PSTN - PSTN phone number, e.g. "+18005551234", "003725555555"
SPEED DIAL CODE - 1 or 2 character speed-dial code

Errors

ERROR 34 invalid user handle
Target username/number missing or contains invalid characters
ERROR 39 user blocked
Trying to call to a blocked user (unblock user in contactlist)
ERROR 73 too many participants
Call is initiated to more than 4 people
ERROR 92 call error
Call is initiated to a number that is neither PSTN number nor a speeddial number

Version: Protocol 1
Notes: The Skype call window is focused when a call is initiated through the API. It is possible to make speed dial calls via the API.
Example

-> CALL echo123 
<- CALL 1402 STATUS ROUTING
<- CALL 1402 SUBJECT
<- CALL 1402 STATUS ROUTING
<- CALL 1402 STATUS RINGING
<- CALL 1402 STATUS INPROGRESS
<- CALL 1402 DURATION 1
<- CALL 1402 STATUS FINISHED

Calls > Commands > Reference > Contents

`GET CALL`

Syntax: GET CALL <id> property
Response: CALL <id> property <value>
Parameters and response values: refer to the CALL object
Errors

ERROR 7 GET: invalid WHAT
Object name missing or misspelled
ERROR 11 Invalid call id
ID includes characters other than numeric characters
ERROR 12 Unknown call
Call with specified ID does not exist in current user's call history
ERROR 13 Invalid PROP
Property name missing or misspelled
ERROR 71 Invalid conference participant NO
Conference participant's number is not a number or is too long

Version: Protocol 1

Calls > Commands > Reference > Contents

`SET CALL INPROGRESS`

Syntax: SET CALL <id> STATUS INPROGRESS
Parameters: <id> - call ID (numeric)
Errors

ERROR 19 Invalid call id
ID includes other than numeric characters
ERROR 20 Unknown call
Call with specified ID does not exist
ERROR 23 Cannot resume this call at the moment
Given call is not ringing and therefore can not be answered.

Calls > Commands > Reference > Contents

`SET CALL FINISHED`

Syntax: SET CALL <id> STATUS FINISHED
Parameters: <id> - call ID (numeric)
Errors

ERROR 19 Invalid call id
ID includes other than numeric characters
ERROR 20 Unknown call
Call with specified ID does not exist in current user's call history nor is active.
ERROR 24 Cannot hangup inactive call
Given call is not in progress and therefore can not be hung up.

Calls > Commands > Reference > Contents

`SET CALL ONHOLD`

Syntax: SET CALL <id> STATUS value
Parameters

<id> - call ID (numeric)
value
- ONHOLD - hold call
- INPROGRESS - resume call

Errors

ERROR 19 Invalid call id
ID includes other than numeric characters
ERROR 20 Unknown call
The call ID does not exist in current user's call history nor is it active.
ERROR 22 Cannot hold this call at the moment
Given call is not in progress and therefore can not be placed on hold.
ERROR 23 Cannot resume this call at the moment
Given call is not in hold and therefore can not be resumed.

Calls > Commands > Reference > Contents

`SET CALL JOIN CONFERENCE`

Syntax: SET CALL <joining_id> JOIN_CONFERENCE <master_id>
Response: CALL <id> CONF_ID <conference_id>
Parameters

<joining_id> - call ID (numeric) to join into;
<master_id> - master call ID, where is another call's ID.

Errors

ERROR 19 Invalid call id
ID includes other than numeric characters
ERROR 20 Unknown call
Call with specified ID does not exist in current user's call history nor is active.
ERROR 72 Cannot create conference
Creating conference, for example "SET CALL 65 JOIN_CONFERENCE 66" fails for some reason.

Note

It is possible to initate a conference with the CALL target1, target2 command

Example

// make first call 
-> CALL test
<- CALL 1540 STATUS ROUTING
<- CALL 1540 SUBJECT
<- CALL 1540 STATUS ROUTING
<- CALL 1540 STATUS RINGING
<- CALL 1540 STATUS INPROGRESS
// set first call on hold ...
-> SET CALL 1540 STATUS ONHOLD
<- CALL 1540 STATUS INPROGRESS
<- CALL 1540 STATUS ONHOLD
// .. and make another call
-> CALL echo123
<- CALL 1545 STATUS ROUTING
<- CALL 1545 SUBJECT
<- CALL 1545 STATUS ROUTING
<- CALL 1545 STATUS RINGING
<- CALL 1545 STATUS INPROGRESS
// join second call (1545) into conference with first call (1540)
-> SET CALL 1545 JOIN_CONFERENCE 1540
<- CALL 1545 CONF_ID 17930
<- CALL 1545 CONF_ID 17930
<- CALL 1540 CONF_ID 17930
// first call is automatically resumed and joined to conference
<- CALL 1540 STATUS INPROGRESS
// ...
<- CALL 1540 DURATION 53
<- CALL 1540 STATUS FINISHED
<- CALL 1545 DURATION 23
<- CALL 1545 STATUS FINISHED

Calls > Commands > Reference > Contents

`SET CALL DTMF`

Syntax: SET CALL <id> DTMF <value>
Parameters

<id> - call ID (numeric)
<value> - sends value as DTMF. Permitted symbols in VALUE are: {0..9,#,*}.

Notes: DTMF support and quality for PSTN calls depends on terminating partner.
Errors

ERROR 19 Invalid call id
ID includes other than numeric characters
ERROR 20 Unknown call
Call with specified ID does not exist in current user's call history nor is it active.
ERROR 21 Unknown/disallowed call prop
DTMF property value is incorrect or misspelled

Calls > Commands > Reference > Contents

`SET CALL SEEN`

Syntax: SET CALL <id> SEEN
Response: CALL <id> SEEN TRUE
Parameters: <id> - call ID (numeric)
Errors

ERROR 19 Invalid call id
ID includes other than numeric characters
ERROR 20 Unknown call
Call with specified ID does not exist in current user's call history nor is active.

Example

-> SET CALL 15 SEEN 
<- CALL 15 SEEN TRUE

Calls > Commands > Reference > Contents

`ALTER CALL`

The ALTER CALL command controls call status.

Syntax

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> }

Version

Protocol 5

Call failure reasons

Code	Description	Possible reason
1	`CALL 181 FAILUREREASON 1`	Miscellaneous error
2	`CALL 181 FAILUREREASON 2`	User or phone number does not exist. Check that a prefix is entered for the phone number, either in the form 003725555555 or +3725555555; the form 3725555555 is incorrect.
3	`CALL 181 FAILUREREASON 3`	User is offline
4	`CALL 181 FAILUREREASON 4`	No proxy found
5	`CALL 181 FAILUREREASON 5`	Session terminated.
6	`CALL 181 FAILUREREASON 6`	No common codec found.
7	`CALL 181 FAILUREREASON 7`	Sound I/O error.
8	`CALL 181 FAILUREREASON 8`	Problem with remote sound device.
9	`CALL 181 FAILUREREASON 9`	Call blocked by recipient.
10	`CALL 181 FAILUREREASON 10`	Recipient not a friend.
11	`CALL 181 FAILUREREASON 11`	Current user not authorized by recipient.
12	`CALL 181 FAILUREREASON 12`	Sound recording error.

Calls > Commands > Reference > Contents

Making and managing video calls

The commands for making and managing video calls are:

Use the GET VIDEO_IN command to retrieve the name of the video device.
Use the GET CALL VIDEO_STATUS command to check the status of a video call.
Use the ALTER CALL VIDEO_SEND command to start or stop sending video during a call.
Use the ALTER CALL VIDEO_RECEIVE
Use the GET CALL VIDEO_SEND_STATUS command to check video send status for a call.
Use the IS_VIDEO_CAPABLE command to check if a user is video-enabled.
Use the OPEN VIDEOTEST command to open the Video Test window.
Use the OPEN OPTIONS VIDEO command to open the Video Options window.

`GET VIDEO_IN`

The GET VIDEO_IN command retrieves the name of the video device to use for a call. If no value is returned, Skype sets the default value.

Syntax

-> GET VIDEO_IN

Response

<- VIDEO_IN <devicename>

Parameters

<devicename> - the name of the video device

Note

If no devicename is returned, Skype sets the default value:

-> SET VIDEO_IN <devicename>

Version

Protocol 5

Video > Commands > Reference > Contents

`GET CALL VIDEO_STATUS`

To check if a Skype client is video-enabled:

Syntax

-> GET CALL 5921 VIDEO_STATUS

Response

Skype responds with the video status for the active call, for example:

<- CALL 5921 VIDEO_STATUS VIDEO_NONE

Parameters

VIDEO_NONE
VIDEO_SEND_ENABLED
VIDEO_RECV_ENABLED
VIDEO_BOTH_ENABLED

Version

Protocol 5

Video > Commands > Reference > Contents

`ALTER CALL VIDEO_SEND`

To start or stop sending video during a call:

Syntax

-> ALTER CALL 5921 { START_VIDEO_SEND | STOP_VIDEO_SEND }

Parameters

START_VIDEO_SEND
TOP_VIDEO_SEND

Version

Protocol 5

Video > Commands > Reference > Contents

`ALTER CALL VIDEO_RECEIVE`

To start or stop receiving video during a call:

Syntax

-> ALTER CALL 5921 { START_VIDEO_RECEIVE | STOP_VIDEO_RECEIVE }

Parameters

START_VIDEO_RECEIVE
STOP_VIDEO_RECEIVE

Version

Protocol 5

Video > Commands > Reference > Contents

`GET CALL VIDEO_SEND_STATUS`

To check video send status:

Syntax

-> GET CALL 5921 VIDEO_SEND_STATUS

Response

Skype responds with the appropriate parameter.

Parameters

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.

Version

Protocol 5

Video > Commands > Reference > Contents

`GET CALL VIDEO_RECEIVE_STATUS`

To check video receive status:

Syntax

-> GET CALL 5921 VIDEO_RECEIVE_STATUS

Response

Skype responds with the appropriate parameter.

Parameters

Version

Protocol 5

Video > Commands > Reference > Contents

`IS_VIDEO_CAPABLE`

To check if a user is video-capable:

Syntax

-> GET USER <username> IS_VIDEO_CAPABLE

Response

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

Version

Protocol 5

Video > Commands > Reference > Contents

`OPEN VIDEOTEST`

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

Syntax

-> OPEN VIDEOTEST

Version

Protocol 5

Video > Commands > Reference > Contents

`OPEN OPTIONS VIDEO`

To open the Video Options window:

Syntax

-> OPEN OPTIONS VIDEO

Version

Protocol 5

Video > Commands > Reference > Contents

Leaving and manipulating voicemails

The commands to leave and manipulate voicemails are:

Use the VOICEMAIL command to leave a voicemail for a target user.
Use the OPEN VOICEMAIL command to open and listen to voicemails.
Use the ALTER VOICEMAIL command to manipulate voicemails.

`VOICEMAIL`

To leave a voicemail:

Syntax: VOICEMAIL <target>
Response: VOICEMAIL <id> STATUS <value>
Parameters

<target> - Skype username to receive the voicemail
<value> - Refer to voicemail object for a list of available status values

Errors
Version: Protocol 5
Notes

Leaving a voicemail for a target user actually uses two types of voicemail object:
1. a greeting type of voicemail object which is downloaded from the server
2. an outgoing type of voicemail object which the user composes

Voicemail > Commands > Reference > Contents

`OPEN VOICEMAIL`

To open and start playing a voicemail:

Syntax: OPEN VOICEMAIL <id>
Notes

Voicemail is downloaded from server automatically.
The main Skype window comes into focus and switches to the Call List tab; use the ALTER VOICEMAIL command to play without a UI response.

See also the SEARCH VOICEMAILS command.

Voicemail > Commands > Reference > Contents

`ALTER VOICEMAIL`

The ALTER VOICEMAIL command allows finer control over the VOICEMAIL object.

Syntax

ALTER VOICEMAIL <id> action

Response

ALTER VOICEMAIL action

Parameters

action, possible values:

STARTPLAYBACK - starts playing downloaded voicemail
STOPPLAYBACK - stops voicemail playback
UPLOAD - uploads recorded voicemail from a local computer to a server
DOWNLOAD - downloads voicemail object from a server to a local computer
STARTRECORDING - stops playing greeting and starts recording, the equivalent to a user pressing the green button;
STOPRECORDING - ends recording, the equivalent to a user pressing the red button
DELETE - delete voicemail object

Notes

STARTPLAYBACK plays voicemail but the window does not change to the Call List tab as it does with the OPEN VOICEMAIL command.
STOPRECORDING causes automatic message upload to the server.
Voicemails are deleted as a background process and the elapsed time depends on the server response; during this period, the SEARCH VOICEMAILS command still returns an ID for the voicemail, but the status is changed to DELETING.

Voicemail > Commands > Reference > Contents

Creating chats and sending messages

The commands for creating chats and sending messages are:

Use the CHAT CREATE command to create a chat.
Use the CHATMESSAGE command to send a chat message.
Use the ALTER CHAT SETTOPIC command to set the topic for a chat.
Use the ALTER CHAT ADDMEMBERS command to add members to a chat.
Use the ALTER CHAT LEAVE command to leave a chat.
Use the GET CHAT CHATMESSAGES command to retrieve the message identifiers for a chat.
Use the GET CHAT RECENTCHATMESSAGES command to retrieve recent chat messages.
Use the SET CHATMESSAGE SEEN command to mark a chat message as seen.
The SET MESSAGE SEEN command is obsolete.
The MESSAGE command is obsolete.

Chat > Commands > Reference > Contents

`CHAT CREATE`

Syntax: CHAT CREATE <target>[, <target>]*
Response: CHAT <chat_id> STATUS <value>
Version: Protocol 5
Parameters

<target> - username(s) with whom to create a chat
<chat_id> - chat identifier; string (usually looks like "#me/$target;012345679012345")
<value> - depends on the type of chat created: DIALOG for a 1:1 chat; MULTI_SUBSCRIBED for a chat with multiple participants

Notes

The CHAT CREATE command does not open a chat window; use the OPEN CHAT command to do so.

Chat > Commands > Reference > Contents

`CHATMESSAGE`

Syntax: CHATMESSAGE <chat_id> <message>
Response: CHATMESSAGE <id> STATUS SENDING
Parameters

<chat_id> - chat identifier
<message> - message text body to send
<id> - chatmessage identifier

Version: Protocol 5
Errors

ERROR 510 Invalid/uknown chat name given
Chat with <chat_id> does not exist
ERROR 511 Sending a message to chat fails
Could not send message to chat (eg. not a member)

Chat > Commands > Reference > Contents

`ALTER CHAT SETTOPIC`

Syntax: ALTER CHAT <chat_id> SETTOPIC <topic>
Response: ALTER CHAT SETTOPIC
Version: Protocol 5
Errors

ERROR 501 CHAT: No chat found for given chat
Chat with <id> does not exist

Chat > Commands > Reference > Contents

`ALTER CHAT ADDMEMBERS`

Syntax: ALTER CHAT <chat_id> ADDMEMBERS <target>[, <target>]*
Response: ALTER CHAT ADDMEMBERS
Version: Protocol 5
Errors

ERROR 501 CHAT: No chat found for given chat
Chat with <chat_id> does not exist
ERROR 504 CHAT: Action failed
Could not add members into chat (eg <target> is already a member; you have left chat)

Chat > Commands > Reference > Contents

`ALTER CHAT LEAVE`

Syntax: ALTER CHAT <chat_id> LEAVE
Response: ALTER CHAT LEAVE
Errors

ERROR 501 CHAT: No chat found for given chat
Chat with <chat_id> does not exist
ERROR 504 CHAT: Action failed
Could not leave chat (for example if the user has already left this chat)

Chat > Commands > Reference > Contents

`GET CHAT CHATMESSAGES`

Syntax: GET CHAT <chat_id> CHATMESSAGES
Response: CHAT <chat_id> CHATMESSAGES <id>[, <id>]*
Version: Protocol 5
Errors

ERROR 501 CHAT: No chat found for given chat
Chat with <chat_id> does not exist

Chat > Commands > Reference > Contents

`GET CHAT RECENTCHATMESSAGES`

Syntax: GET CHAT <chat_id> RECENTCHATMESAGES
Response: CHAT <chat_id> RECENTCHATMESSAGES <id>[, <id>]*
Version: Protocol 5
Errors

ERROR 501 CHAT: No chat found for given chat
Chat with <chat_id> does not exist

Chat > Commands > Reference > Contents

`SET CHATMESSAGE SEEN`

Syntax: SET CHATMESSAGE <id> SEEN
Response: CHATMESSAGE <id> STATUS <value>
Parameters

<id> - chat message ID.
<value> - new value for chat message status; refer to CHATMESSAGE object for status values

Version: Protocol 3
Example

-> SET CHATMESSAGE 61 SEEN 
<- CHATMESSAGE 61 STATUS READ

Errors

ERROR 18 SET: invalid WHAT
CHATMESSAGE command is missing or misspelled
ERROR 31 Unknown message id
Unknown chat message ID
ERROR 30 Invalid message id
Chat message ID is misspelled or contains non-permitted symbols (numeric are permitted)
ERROR 32 Invalid WHAT
Invalid status given to chat message, for example the message is already marked as seen

Chat > Commands > Reference > Contents

`SET MESSAGE SEEN`- obsolete

Mark message as seen by the user and remove it from the missed messages list. This command is obsolete and has been replaced by the SET CHATMESSAGE SEEN command.

Syntax: SET MESSAGE <id> SEEN
Response: MESSAGE <id> STATUS value
Properties

<id> - message ID;
value - (new) status value

Version: Protocol 1, deprecated in protocol 3
Example

-> SET MESSAGE 1578 SEEN 
<- MESSAGE 1578 STATUS READ

Errors

ERROR 18 SET: invalid WHAT
Object name missing or misspelled.
ERROR 30 Invalid message id
ID includes other than numeric characters.
ERROR 31 Unknown message id
Message with specified ID does not exist in current user's message history.
ERROR 32 Invalid WHAT
Property name missing or misspelled.

Chat > Commands > Reference > Contents

`MESSAGE` - obsolete

The MESSAGE command is obsolete and has been replaced by the CHATMESSAGE command.

Syntax: MESSAGE <target> <text>
Response: CHATMESSAGE <id> STATUS SENDING(protocol 3 and up)
MESSAGE <id> STATUS SENDING(protocol 1 and 2)
Parameters

<target> - target username to whom to send the message
<text> - message body, for example Please call me

Version: Protocol 1

Errors

ERROR 26 Invalid user handle
Target username missing or includes symbols which are not premitted
ERROR 43 Cannot send empty message
Message has no body (e.g. "MESSAGE echo123")

Notes: When message sending fails, a LEFT-type message is received. The message's LEAVEREASON shows why it failed. See the CHATMESSAGE object for a description.
Example

-> MESSAGE echo123 Please call me 
<- MESSAGE 982 STATUS SENDING
<- MESSAGE 982 STATUS SENT

Chat > Commands > Reference > Contents

Managing contacts and groups

Users can group contacts, for example, creating separate groups for friends, family, and work. To add a user to a group, the user must be in the contact list. Contacts can be in multiple groups at the same time. Refer to the GROUP object for a description of the object properties. Contact grouping uses the following commands:

Use the GET GROUP USERS command to query the users in a group.
Use the GET GROUP VISIBLE command to query if a group is visible to the user.
Use the GET GROUP EXPANDED command to query if a group is expanded in the Skype window.
Use the GET GROUP DISPLAYNAME command to query the name of a group.
Use the SET GROUP DISPLAYNAME command to change the name of a group.
Use the GET GROUP TYPE command to query the group type.
Use the CREATE GROUP command to create a group.
Use the DELETE GROUP command to delete a group.
Use the ALTER GROUP ADDUSER command to add a contact to a group.
Use the ALTER GROUP REMOVEUSER command to remove a contact from a group.
Use the SEARCH GROUPS command to search for contact groups.
Use the SET USER DISPLAYNAME command to change the displayname for a contact.
Use the OPEN SENDCONTACTS command to send contacts to multiple users.

`GET GROUP USERS`

The GET GROUP USERS command queries the members of a group.

Syntax

-> GET GROUP <id> USERS

Response

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

Version

Protocol 5

Groups > Commands > Reference > Contents

`GET GROUP VISIBLE`

The GET GROUP VISIBLE command queries if a group is visible to the user.

Syntax

-> GET GROUP <id> VISIBLE

Response

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

Version

Protocol 5

Groups > Commands > Reference > Contents

`GET GROUP EXPANDED`

The GET GROUP EXPANDED command queries whether a group is expanded in the Skype window.

Syntax

-> GET GROUP <id> EXPANDED

Response

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

Version

Protocol 5

Groups > Commands > Reference > Contents

`GET GROUP DISPLAYNAME`

The GET GROUP DISPLAYNAME gets the displayname for a group.

Syntax

-> GET GROUP <id> DISPLAYNAME

Response

<- GROUP <id> DISPLAYNAME <name>

Version

Protocol 5

Groups > Commands > Reference > Contents

`SET GROUP DISPLAYNAME`

The SET GROUP DISPLAYNAME command changes the displayname for a group.

Syntax

-> SET GROUP <id> DISPLAYNAME <name>

Response

<- GROUP <id> DISPLAYNAME <name>

Version

Protocol 5

Groups > Commands > Reference > Contents

`GET GROUP TYPE`

The GET GROUP TYPE command queries the group type.

Syntax

-> GET GROUP <id> TYPE

Response

<- GROUP <id> TYPE <group_type>

Version

Protocol 5

Refer to the GROUP OBJECT for a list and description of group types.

Groups > Commands > Reference > Contents

`CREATE GROUP`

The CREATE GROUP command creates a contact group, for example a group named Family.

Syntax

-> CREATE GROUP <Family>

Response

<- CREATE GROUP <Family>

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 <Family>
<- GROUP <234> USERS

The command triggers the following notification:

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

Version

Protocol 5

Groups > Commands > Reference > Contents

`DELETE GROUP`

The DELETE GROUP removes a contact group.

Syntax

-> DELETE GROUP <234>

Response

<- DELETE GROUP <234>

The command triggers the following notifications:

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

`ALTER GROUP ADDUSER`

The ALTER GROUP ADDUSER command adds contacts to a group.

Syntax

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

Response

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

Parameters

ADDUSER <userhandle|PSTN>

This command triggers the following notification:

<- GROUP <234> NROFUSERS y

Note:

A contact must exist in a contactlist to be added to a group.

Version

Protocol 5

Groups > Commands > Reference > Contents

`ALTER GROUP REMOVEUSER`

The ALTER GROUP REMOVEUSER command removes contacts from a group.

Syntax

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

Response

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

Parameters

REMOVEUSER <userhandle|PSTN>

This command triggers the following notification:

<- GROUP <234> NROFUSERS y

Version

Protocol 5

Groups > Commands > Reference > Contents

`SET USER DISPLAYNAME`

The SET USER DISPLAYNAME command changes the display name for a contact.

Syntax

-> SET USER <handle|PSTN> DISPLAYNAME name

Version

Protocol 5

Groups > Commands > Reference > Contents

`OPEN SENDCONTACTS`

The OPEN SENDCONTACTS command opens the window to send contacts to other users.

Syntax

-> OPEN SENDCONTACTS  target1 target2 ...

Version

Protocol 5

Groups > Commands > Reference > Contents

Search commands

The search command requests specific information about objects. If no target is specified, all results for specified objects are returned.

Syntax: SEARCH USERS | FRIENDS | CALLS [<target>] | ACTIVECALLS | MISSEDCALLS | VOICEMAILS | CHATS | MISSEDCHATS | ACTIVECHATS | RECENTCHATS | BOOKMARKEDCHATS | CHATMESSAGES [<target>] | MISSEDCHATMESSAGES | MESSAGES [<target>] | MISSEDMESSAGES | USERSWAITINGMYAUTHORIZATION | GROUPS [{ ALL | CUSTOM | HARDWIRED }]
Notes

In Skype for Windows 1.1 only one search at a time is allowed; since version 1.2 multiple searches can executed at the same time;
The number of search results is not limited.
SkypeOut contacts: since Skype for Windows 1.2 release it is possible to get the list of SkypeOut contacts which are part of the main contact list and they are returned with the contact list numbers, if the SEARCH FRIENDS command is executed. To get more information about the number in a current user's SkypeOut contacts use the GET USER <number> <fullname>" command.

The search commands are:

Use the SEARCH FRIENDS command to search for users in the contact list.
Use the SEARCH USERS command to search for users.
Use the SEARCH CALLS command to search for calls.
Use the SEARCH ACTIVECALLS command to search for active calls.
Use the SEARCH MISSEDCALLS command to search for missed calls.
Use the SEARCH VOICEMAILS command to search for voicemails.
The SEARCH MESSAGES command is obsolete.
The SEARCH MISSEDMESSAGES command is obsolete. Use the to search for missed messages.
Use the SEARCH CHATS command to search for chats.
User the SEARCH ACTIVECHATS command to search for active chats.
Use the SEARCH MISSEDCHATS command to search for unread chat messages.
Use the SEARCH RECENTCHATS command to search for recent chats.
Use the SEARCH BOOKMARKEDCHATS command to search for bookmarked chats.
Use the SEARCH CHATMESSAGES command to search for chatmessages.
Use the SEARCH MISSEDCHATMESSAGES command to search for missed chat messages.
Use the SEARCH USERSWAITINGMYAUTHORIZATION command to search for users awaiting authorization.
Use the SEARCH GROUPS command to search for contact groups.

Search > Commands > Reference > Contents

`SEARCH FRIENDS`

Syntax: SEARCH FRIENDS
Response: USERS [user[, user]*]
returns a list of found usernames; an empty list if no match is found
Errors

ERROR 67 target not allowed with SEARCH FRIENDS
a target (such as mike) was specified with the SEARCH FRIENDS command

Version: Protocol 1
Example

-> SEARCH FRIENDS 
<- USERS tim, joe, mike

Search > Commands > Reference > Contents

`SEARCH USERS`

Syntax: SEARCH USERS <target>
Parameters: <target> - part of username or e-mail to match. If the search string contains "@", the search is performed by e-mail address and has to be an exact match. If the search string is a valid Skype username, the search is performed on the full name and username fields. In all other cases the search is made on the full name field only.
Response: SEARCH [<username>[, <username>]*]
returns a list of found usernames; list is empty if no match was found
Errors

ERROR 4 Empty target not allowed
Target username is not specified

Notes: When running the SEARCH USERS command, USER notifications are reported back to the API client as users are found on the network. The API client should ignore these events and request each user's property after the search.
Version: Protocol 1
Example

-> #123 SEARCH USERS echo123 
<- #123 USERS echo123, echo1232885

Search > Commands > Reference > Contents

`SEARCH CALLS`

Syntax: SEARCH CALLS <target>
Parameters: <target> - username. Specifying a target is optional. If a target is specified, Skype searches the call history between the current user and the target user.
Response: CALLS [id[, id]*]
Returns a list of call IDs. If a target is specified, Skype returns IDs of all calls that have been made between the current and target user.
Errors

ERROR 5 Search CALLS: invalid target
Characters that are not permitted were used in the target username. The username must have 6-22 characters and can contain only the following symbols: {a-Z0-9-_,.}.

Version: Protocol 1
Example

-> SEARCH CALLS abc 
<- CALLS 15, 16, 39

Search > Commands > Reference > Contents

`SEARCH ACTIVECALLS`

Lists all calls visible on calltabs, including members of conference calls if the user is hosting a conference.

Syntax: SEARCH ACTIVECALLS
Response: CALLS [<id>[, <id>]*]
Returns a list of active call IDs.
Errors

ERROR 3 SEARCH: unknown WHAT
ACTIVECALLS was misspelled.

Version: Protocol 1
Example

-> SEARCH ACTIVECALLS 
<- CALLS 25, 56

Search > Commands > Reference > Contents

`SEARCH MISSEDCALLS`

Syntax: SEARCH MISSEDCALLS
Response: CALLS [<id>[, <id>]*]
Returns a list of missed call IDs, calls in MISSED status.
Errors

ERROR 6 SEARCH MISSEDCALLS: target not allowed
No target is allowed with SEARCH MISSEDCALLS.

Version: Protocol 1
Example

-> SEARCH MISSEDCALLS 
<- CALLS 25, 56

Search > Commands > Reference > Contents

`SEARCH VOICEMAILS`

Syntax: SEARCH VOICEMAILS
Response: VOICEMAILS [<id>[, <id>]*]
Returns a list of voicemail IDs.||
Errors

ERROR 29 SEARCH VOICEMAILS: target not allowed
No target is allowed with SEARCH VOICEMAILS

Version: Protocol 5
Example

->SEARCH VOICEMAILS 
<- VOICEMAILS 65, 70, 71

Search > Commands > Reference > Contents

`SEARCH MESSAGES`

Syntax: SEARCH MESSAGES [<target>]
Parameters

<target> - username. It is optional to specify a target. If a target is specified, Skype searches the message history between the current user and the target user.

Response: MESSAGES [<id>[, <id>]*]
Returns a list of message IDs. If a target is specified, Skype returns IDs of all messages that have been sent between the current user and the target user.
Errors

ERROR 5 SEARCH MESSAGES: invalid target
A character was used in the target username that is not permitted. The username must have 6-22 characters and can contain only the following symbols: {a-Z0-9-_,.}.

Version: Protocol 1, deprecated in protocol 3
Notes: This search is deprecated in protocol 3, use the SEARCH CHATMESSAGES command instead.
Example

-> SEARCH MESSAGES abc 
<- MESSAGES 123, 124

Search > Commands > Reference > Contents

`SEARCH MISSEDMESSAGES`

Syntax: SEARCH MISSEDMESSAGES
Response: MESSAGES [<id>[, <id>]*]
Returns a list of message IDs.
Errors

ERROR 29 SEARCH MISSEDMESSAGES: target not allowed
No target is allowed with the SEARCH MISSEDMESSAGES command.

Version: Protocol 1, deprecated in protocol 3
Notes: This search is deprecated in protocol 3. Use the SEARCH MISSEDCHATMESSAGES command instead.
Example

-> SEARCH MISSEDMESSAGES 
<- MESSAGES 123, 124

Search > Commands > Reference > Contents

`SEARCH CHATS`

Syntax: SEARCH CHATS
Response: CHATS [<chatname>[, <chatname>]*]
Returns a list of chat IDs.
Errors

ERROR 107 target not allowed with CHATS
No target is allowed with the SEARCH CHATS command.

Version: Protocol 3
Example

-> SEARCH CHATS 
<- CHATS #bitman/$jessy;eb06e65612353279, #bitman/$jdenton;9244e98f82d7d391

Search > Commands > Reference > Contents

`SEARCH ACTIVECHATS`

Syntax: SEARCH ACTIVECHATS
Response: CHATS [<chatname>[, <chatname>]*]
Returns a list of chat IDs that are open in the window.
Errors

ERROR 29 No target allowed
No target is allowed with SEARCH ACTIVECHATS.

Version: Protocol 5
Example

-> SEARCH ACTIVECHATS 
<- CHATS #bitman/$jessy;eb06e65612353279, #bitman/$jdenton;9244e98f82d7d391

`SEARCH MISSEDCHATS`

Syntax: SEARCH MISSEDCHATS
Response: CHATS [<chatname>[, <chatname>]*]

Returns a list of chat IDs that include unread messages.
Errors

ERROR 29 SEARCH MISSEDCHATS: target no allowed

No target is allowed with SEARCH MISSEDCHATS.

Version: Protocol 5
Example



-> SEARCH MISSEDCHATS 

<- CHATS #bitman/$jessy;eb06e65612353279, #bitman/$jdenton;9244e98f82d7d391

Search > Commands > Reference > Contents

`SEARCH RECENTCHATS`

Syntax: SEARCH RECENTCHATS
Response: CHATS [<chatname>[, <chatname>]*]

Returns a list of recent chat IDs.
Errors

ERROR 29 SEARCH RECENTCHATS: target no allowed

No target is allowed with SEARCH RECENTCHATS.

Version: Protocol 5
Example



-> SEARCH RECENTCHATS 

<- CHATS #bitman/$jessy;eb06e65612353279, #bitman/$jdenton;9244e98f82d7d391

`SEARCH BOOKMARKEDCHATS`

Syntax: SEARCH BOOKMARKEDCHATS
Response: CHATS [<chatname>[, <chatname>]*]
Returns a list of bookmarked chat IDs.
Errors

ERROR 29 SEARCH BOOKMARKEDCHATS: target no allowed
No target is allowed with SEARCH BOOKMARKEDCHATS.

Version: Protocol 5
Example

-> SEARCH BOOKMARKEDCHATS 
<- CHATS #bitman/$jessy;eb06e65612353279, #bitman/$jdenton;9244e98f82d7d391

Search > Commands > Reference > Contents

`SEARCH CHATMESSAGES`

Syntax: SEARCH CHATMESSAGES [<username>]
Parameters: <username> - target username, optional. If a username is specified, only chatmessages from/to that target user are returned.
Response: CHATMESSAGES [<id>[, <id>]*]
Returns a list of chat message IDs.
Errors

ERROR 29 SEARCH CHATMESSAGES: invalid target
The target username contained a character that is not permitted. (Username must have 6-22 characters and can contain only the following symbols: {a-Z0-9-_,.}.

Version: Protocol 3
Example

-> SEARCH CHATMESSAGES abc 
<- CHATMESSAGES 60, 59

Search > Commands > Reference > Contents

`SEARCH MISSEDCHATMESSAGES`

Syntax: SEARCH MISSEDCHATMESSAGES
Response: CHATMESSAGES [<id>[, <id>]*]
Returns a list of missed chat message IDs.
Errors

ERROR 29 SEARCH MISSEDCHATMESSAGES: target not allowed
No target is allowed with SEARCH MISSEDCHATMESSAGES.

Version: Protocol 3
Example

-> SEARCH MISSEDCHATMESSAGES 
<- CHATMESSAGES 61, 62

Search > Commands > Reference > Contents

`SEARCH USERSWAITINGMYAUTHORIZATION`

Syntax: SEARCH USERSWAITINGMYAUTHORIZATION
Response: USERS [<id>[, <id>]*]
List of users who are waiting for authorization
Errors

ERROR 29 SEARCH USERSWAITINGMYAUTHORIZATION: target no allowed

Version: Protocol 5
Example

-> SEARCH USERSWAITINGMYAUTHORIZATION 
<- USERS tim, john, echo123

`SEARCH GROUPS`

The SEARCH GROUPS command returns existing contact groups.

Syntax

-> SEARCH GROUPS [{ ALL | CUSTOM | HARDWIRED }]

Response

<- GROUPS <id1>, <id2>, <id3>, ...

Version

Protocol 5

Errors

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

Search > Commands > Reference > Contents

Managing history

These commands are available to clear chat, voicemail, and call history.

`CLEAR CHATHISTORY`

Syntax: CLEAR CHATHISTORY

`CLEAR VOICEMAILHISTORY`

Syntax: CLEAR VOICEMAILHISTORY

`CLEAR CALLHISTORY`

Syntax: CLEAR CALLHISTORY

History > Commands > Reference > Contents

Controlling Skype user interface

This section lists the commands used to control the Skype user interface. The commands are:

Use the FOCUS command to bring the Skype window into focus.
Use the MINIMIZE command to minimize the Skype window.
Use the OPEN ADDAFRIEND command to open the Add a Contact window.
The OPEN IM command opens a chat window. However, this command has been superceded by the OPEN CHAT command and new chat management commands in protocol 5.
Use the OPEN CHAT command to open a chat window.
Use the OPEN FILETRANSFER command to open a file transfer window.
Use the OPEN_VIDEOTEST command to test if video is working.
Use the OPEN VOICEMAIL command to open a voicemail window.
Use the OPEN PROFILE command to open the profile for the current user.
Use the OPEN USERINFO command to open the profile window for a named Skype contact.
Use the OPEN CONFERENCE command to open the create conference window.
Use the OPEN SEARCH command to open a search window.
Use the OPEN OPTIONS command to open the options configuration window.
Use the OPEN CALLHISTORY command to open the call history tab in the main Skype window.
Use the OPEN CONTACTS command to open the contacts tab in the main Skype window.
Use the OPEN DIALPAD command to open the dialpad tab in the main Skype window.
Use the OPEN SENDCONTACTS command to open the send contacts window.
Use the OPEN BLOCKEDUSERS command to open the blocked users window.
Use the OPEN IMPORTCONTACTS command to open the import contacts window.
Use the OPEN GETTINGSTARTED command to open the getting started wizard.
Use the OPEN AUTHORIZATION command to open the authorization window.
Use the BTN_PRESSED command to simulate page scrolling.

`FOCUS`

The FOCUS brings the Skype window into focus on screen (on top).

Syntax: FOCUS
Response: If successful command is echoed back
Version: Protocol 1

User interface > Commands > Reference > Contents

`MINIMIZE`

This command minimizes the main Skype window into the system tray.

Syntax: MINIMIZE
Response: If successful command is echoed back
Version: Skype for Windows 1.3
Notes: This command does not minimize other Skype windows, such as chat or filetransfer.

User interface > Commands > Reference > Contents

`OPEN ADDAFRIEND`

This command opens the Add a Contact window.

Syntax: OPEN ADDAFRIEND [<username>]
Parameters: <username> - target username is optional. If a username is specified, the window is prefilled with it.
Response: If successful command is echoed back
Errors: ERROR 69 OPEN: invalid WHAT
Open target is missing or misspelled
Version: Skype for Windows 1.0

User interface > Commands > Reference > Contents

`OPEN IM`

This command opens the chat window with prefilled message.

Syntax: OPEN IM <username> [<message>]
Response: If successful command is echoed back
Parameters

<username> - contact username to whom to send the message
<message> - optional message body prefilled into the window

Errors

ERROR 69 OPEN: invalid WHAT
Open target is missing or misspelled
ERROR 70 Invalid user handle
Username is missing or contains not permitted symbols

Version: Skype for Windows 1.0
Notes: The protocol 5 chat management commands and Skype for Windows 1.3 OPEN CHAT command are preferable to the OPEN IM command.
Example

// IM dialog with echo123 will pop up, with text "This is a test!" already filled in as message text 
-> OPEN IM echo123 This is a test!
<- OPEN IM echo123 This is a test!

User interface > Commands > Reference > Contents

`OPEN CHAT`

Syntax: OPEN CHAT <chat_id>
Parameters: <chat_id> - existing chat identifier (see CHAT CREATE, SEARCH ...CHATS commands)
Response: If successful command is echoed back
Errors

ERROR 69 invalid open what
Open target is missing or misspelled
ERROR 105 Invalid chat name
Chat id is missing or chat with this id doesn't exist.

Version: Skype for Windows 1.3
Example

-> OPEN CHAT #test/$echo123;52c2750d8686c10c 
<- OPEN CHAT #test/$echo123;52c2750d8686c10c

User interface > Commands > Reference > Contents

`OPEN FILETRANSFER`

Syntax: OPEN FILETRANSFER <username>[, <username>]*[ IN <folder>]
Response: If successful command is echoed back
Parameters

<username> - list of usernames to transfer file to;
<folder> - optional, filesystem folder for file selection window. If not specified, the file transfer window opens in the default directory.

Errors

ERROR 69 invalid open what
Open target is missing or misspelled
ERROR 108 user not contact
Command is allowed for authorized contacts only
ERROR 109 directory doesn't exist
Given folder does not exist or user has no access to it

Version: Skype for Windows 1.3
Example

-> OPEN FILETRANSFER echo123 IN C:\temp
<- ERROR 108 user not contact
-> OPEN FILETRANSFER myfriend IN C:\temp
<- OPEN FILETRANSFER myfriend IN C:\temp

User interface > Commands > Reference > Contents

`OPEN_VIDEOTEST`

This command opens the Video test window to test if video is working.

Syntax: -> OPEN VIDEOTEST

`OPEN VOICEMAIL`

This command brings the callhistory tab into focus and starts playing a voicemail.

Syntax

OPEN VOICEMAIL <id>

Response

If successful command is echoed back

Parameters

<id> - voicemail identifier

Errors

ERROR 69 invalid open what

Open target is missing or misspelled

ERROR 512 invalid voicemail ID

Voicemail identifier is missing, is invalid or does not exist

User interface > Commands > Reference > Contents

`OPEN PROFILE`

This command opens the profile window for the current user.

Syntax: OPEN PROFILE
Response: If successful command is echoed back
Parameters
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN USERINFO`

This command opens the profile window for a named Skype contact.

Syntax: OPEN USRERINFO <skypename>
Response: If successful command is echoed back
Parameters: <skypename> - Skypename of contact
Errors

ERROR invalid skypename

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN CONFERENCE`

This command opens the create conference window.

Syntax: OPEN CONFERENCE
Response: If successful command is echoed back
Parameters: none
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN SEARCH`

This command opens the search window.

Syntax: OPEN SEARCH
Response: If successful, command is echoed back
Parameters: none
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN OPTIONS`

This command opens the options configuration window.

Syntax

OPEN OPTIONS <page>

Response

If successful, the command is echoed back

Parameters

<page>, possible values:

general

privacy

notifications

soundalerts

sounddevices

hotkeys

connection

voicemail

callforward

video

advanced

Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

Note: OPEN OPTIONS video parameter will be introduced in Skype for Windows 2.0.

User interface > Commands > Reference > Contents

`OPEN CALLHISTORY`

This command opens and sets the focus to the call history tab in the main Skype window.

Syntax

OPEN CALLHISTORY

Response

If successful, the command is echoed back

Parameters

none

Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version

Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN CONTACTS`

This command opens and sets the focus to the contacts tab in the main Skype window.

Syntax: OPEN CONTACTS
Response: If successful, the command is echoed back
Parameters: none
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN DIALPAD`

This command opens and sets the focus to the dialpad tab in the main Skype window.

Syntax: OPEN DIALPAD
Response: If successful, the command is echoed back
Parameters: none
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN SENDCONTACTS`

This command opens the send contacts window.

Syntax: OPEN SENDCONTACTS
Response: If successful, the command is echoed back
Parameters: none
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN BLOCKEDUSERS`

This command opens the blocked users window.

Syntax: OPEN BLOCKEDUSERS
Response: If successful, the command is echoed back
Parameters: none
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN IMPORTCONTACTS`

This command opens the import contacts window.

Syntax: OPEN IMPORTCONTACTS
Response: If successful, the command is echoed back
Parameters: none
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN GETTINGSTARTED`

This command opens the getting started wizard.

Syntax: OPEN GETTINGSTARTED
Response: If successful, the command is echoed back
Parameters: none
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

User interface > Commands > Reference > Contents

`OPEN AUTHORIZATION`

This command opens the authorization request window for a given user.

Syntax: OPEN AUTHORIZATION <skypename>
Response: If successful, the command is echoed back
Parameters: skypename of the user whose authorization is requested
Errors

ERROR 69 invalid open what

Open target is missing or misspelled

Version: Skype for Windows 1.4

`BTN PRESSED`

The Skype API provides the ability to simulate page scrolling through the contact list from an external device.

Syntax

BTN_PRESSED {PAGEUP|PAGEDOWN}

BTN_RELEASED {PAGEUP|PAGEDOWN}

Version

Protocol 5

User interface > Commands > Reference > Contents

Application to application commands

The AP2AP feature in Skype allows two API clients to exchange information without the communication being visible on the client. Application to application communication has the following characteristics:

Connections are only allowed to connectable users, online parties who are in the user's contact list or have active ongoing communication with the user.

Connections are only attempted to connectable users at CONNECT.

Connections are established only when there is a matching application on the other side.

The application name is limited to 32 bytes.

Idle connections are dropped in a specific amount of time (typically 8 minutes).

When connection is relayed, throttling is engaged.

If the other party is logged in to multiple Skype instances, a stream for each instance is created.

The stream write provides reliable transmission to deliver a large amount of data.

The maximum amount of write to a stream can be 0xFFFF bytes long.

Any character except 0x00 is allowed in a message.

Datagrams are unreliable packets sent over a network (usually translates to UDP).

The maximum size of datagrams is 1400 bytes.

There is no guarantee that datagrams will be delivered.

The application to application commands are:

AP2AP CREATE command

Use the AP2AP CONNECT command to create a stream from an application to a Skype user's instance of the application.

Use the AP2AP WRITE command to write text to the application stream.

Use the AP2AP DATAGRAM command to add a datagram to the application stream.

Use the AP2AP READ command to read data from the application stream.

Use the AP2AP DISCONNECT command to disconnect a user stream from an application.

Use the AP2AP DELETE conmmand to delete an application and all connections to it.

Read an application to application example to get you started.

`AP2AP CREATE`

This command registers a new application object with Skype.

Syntax: CREATE APPLICATION <appname>
Response: If successful, the command is echoed back
Parameters: <appname>: An arbitrary name to identify the application that will be exchanging data
Errors

ERROR 536 CREATE: no object or type given
ERROR 537 CREATE: Unknown object type given
ERROR 540 CREATE APPLICATION: Missing or invalid name

Version

Protocol 5
Skype for Windows 1.4

AP2AP > Commands > Reference > Contents

`AP2AP CONNECT`

This command creates a stream from the application to another Skype user's instance of the same application.

Syntax: ALTER APPLICATION <appname> CONNECT <skypename>
Response: If successful, the command is echoed back
Parameters

<appname>: An arbitary name to identify the application that will be exchanging data
<skypename>: The user to connect to this application

Errors

ERROR 546 ALTER APPLICATION : Missing or invalid action
ERROR 547 ALTER APPLICATION CONNECT: Invalid user handle

Version

Protocol 5
Skype for Windows 1.4

Note: If the user identified by <skypename> is logged in from multiple locations, a stream will be created to each location.

AP2AP > Commands > Reference > Contents

`AP2AP WRITE`

This command writes text into the application stream identified by the destination user's Skypename and stream ID.

Syntax: ALTER APPLICATION <appname> WRITE <skypename>:<id> <text>
Response: If successful, the command is echoed back
Note: There is a bug in Skype 1.4 where the number of SENDING notification following an application WRITE reports that the number of bytes sent is two characters longer than that which was written.
Parameters

<appname>: An arbitary name to identify the application that will be exchanging data
<skypename>: The name of the skype contact to whom the message will be sent
<id>: The numeric identifier for the skype instance to which the message will be sent
<text>: The text to send

Errors

ERROR 546 ALTER APPLICATION : Missing or invalid action
ERROR 550 ALTER APPLICATION READ: Missing or Invalid stream identifier

Version

Protocol 5
Skype for Windows 1.4

Example

//Send "Hello world!" to user "testtest20" stream "1" (application "exe") -> ALTER APPLICATION exe WRITE testtest20:1 Hello world! <- ALTER APPLICATION exe WRITE testtest20:1 // The message has been queued for sending, message length is reported back <- APPLICATION exe SENDING testtest20:1 14 // The message has been sent -- note missing stream ID from the end of response <- APPLICATION exe SENDING

-> ALTER APPLICATION exe WRITE testtest20:1 1234567890 <- ALTER APPLICATION exe WRITE testtest20:1 <- APPLICATION exe SENDING testtest20:1 12 <- APPLICATION exe SENDING

`AP2AP DATAGRAM`

This command sends a datagram to the application stream.

Syntax: ALTER APPLICATION <appname> DATAGRAM <skypename>:<id> <text>
Response: If successful, the command is echoed back
Parameters: <appname>: An arbitrary name to identify the application that will be exchanging data
Errors

ERROR 546 ALTER APPLICATION : Missing or invalid action
ERROR 551 ALTER APPLICATION DATAGRAM: Missing or invalid stream identifier

Version

Protocol 5
Skype for Windows 1.4

AP2AP > Commands > Reference > Contents

`AP2AP READ`

This command reads data from an application stream.

Syntax: ALTER APPLICATION <appname> READ <skypename>:<id>
Response: If successful, the command is echoed back
Parameters: <appname>: An arbitrary name to identify the application that will be exchanging data
Errors

ERROR 546 ALTER APPLICATION : Missing or invalid action
ERROR 550 ALTER APPLICATION READ: Missing or invalid stream identifier

Version

Protocol 5
Skype for Windows 1.4

AP2AP > Commands > Reference > Contents

`AP2AP DISCONNECT`

This command disconnects a user stream from an application.

Syntax

ALTER APPLICATION <appname> DISCONNECT <skypname>:<id>

Response

If successful, the command is echoed back

Parameters

<appname>: An arbitrary name to identify the application that will be exchanging data
<skypename>:<id>: The user and stream to disconnect

Errors

ERROR 546 ALTER APPLICATION : Missing or invalid action
ERROR 548 ALTER APPLICATION DISCONNECT: Invalid stream identifier

Version

Protocol 5
Skype for Windows 1.4

AP2AP > Commands > Reference > Contents

`AP2AP DELETE`

This command deletes an application and drops all connections to it.

Syntax: DELETE APPLICATION <appname>
Response: If successful, the command is echoed back
Parameters: <appname>: The name of the application to be deleted
Errors

ERROR 538 DELETE: no object or type given
ERROR 539 DELETE: Unknown object type given
ERROR 542 DELETE APPLICATION : missing or invalid application name

Version

Protocol 5
Skype for Windows 1.4

AP2AP > Commands > Reference > Contents

Application to application example

Jim and Joe are two users who installed "toru" application.

// register application on both sides 
[JIM] => CREATE APPLICATION toru
[JIM] <= CREATE APPLICATION toru

[JOE] => CREATE APPLICATION toru
[JOE] <= CREATE APPLICATION toru

// JIM initiates communication to JOE
[JIM] => ALTER APPLICATION toru CONNECT joe
[JIM] <= ALTER APPLICATION toru CONNECT joe

// connection establishing ...
[JIM] <= APPLICATION toru CONNECTING joe

// .. and is successful
[JIM] <= APPLICATION toru CONNECTING

// .. and creates one stream
[JIM] <= APPLICATION toru STREAMS joe:1

// and JOE is notified by new stream
[JOE] <= APPLICATION toru STREAMS jim:1

// JIM sends data over stream to JOE
[JIM] => ALTER APPLICATION toru WRITE joe:1 Hello world!
[JIM] <= ALTER APPLICATION toru WRITE joe:1

// stay tuned while data is transmitted...
[JIM] <= APPLICATION toru SENDING joe:1

// .. and you are notified on delivery success
[JIM] <= APPLICATION toru SENDING

// JOE receives notification about the incoming message
[JOE] <= APPLICATION toru RECEIVED jim:1

// .. and reads data from stream
[JOE] => ALTER APPLICATION toru READ jim:1
[JOE] <= ALTER APPLICATION toru READ jim:1 Hello world!

// ... and is notified that stream is empty
[JOE] <= APPLICATION toru RECEIVED

// JOE sends back acknowledgement of message

// A datagram is used because it is not so important to acknowledge
[JOE] => ALTER APPLICATION toru DATAGRAM jim:1 Hello back!
[JOE] <= ALTER APPLICATION toru DATAGRAM jim:1

// Now data is transmitted...
[JOE] <= APPLICATION toru SENDING jim:1=11

// .. and notificed when it was sent (but delivery not assured)
[JOE] <= APPLICATION toru SENDING

// JIM receives datagram notifcation
[JIM] <= APPLICATION toru DATAGRAM joe:1 Hello back!

// JIM decides to end the communication
[JIM] => ALTER APPLICATION toru DISCONNECT joe:1
[JIM] <= ALTER APPLICATION toru DISCONNECT joe:1

// .. and when stream is closed it is notified
[JIM] <= APPLICATION toru STREAMS

// Also JOE receives notification that stream was closed
[JOE] <= APPLICATION toru STREAMS

// JIM unregisters applicaton
[JIM] => DELETE APPLICATION toru
[JIM] <= DELETE APPLICATION toru

// JOE unregisters applicaton
[JOE] => DELETE APPLICATION toru
[JOE] <= DELETE APPLICATION toru

AP2AP > Commands > Reference > Contents

Call forwarding

To set up call forwarding rules for an account:

Syntax: GET/SET PROFILE
{ CALL_NOANSWER_TIMEOUT <timeout>
| CALL_NOANSWER_ACTION {REJECT|FORWARD|VOICEMAIL} // action if user does not answer
| CALL_FORWARD_RULES [<start_time>,<end_time>,{<username>|<+PSTN>}[ <start_time>,<end_time>,{<username>|<+PSTN>}]*]
}
Parameters

timeout- in seconds for call forward
start_time- in seconds when connecting to this number/user starts
end_time - in seconds when ringing to this number/user ends
username - another Skype username to forward call
+PSTN - PSTN number to forward a call

A call can be forwarded to multiple numbers and the numbers can overlap in time, with all ringing and the first to pick up the call takes it.

Version: Skype for Windows 1.4
Notes

Skype Windows 1.4 UI defaults to no-answer timeout is 15 seconds
Skype Windows 1.4 UI defaults to 0,60 start_time and end_time in rules
Skype Windows 1.4 UI allows to set a maximum of 3 numbers for forwarded calls

Call forwarding > Commands > Reference > Contents

Testing connections

To query the connection status:

Syntax: PING
Response: If successful PONG is echoed back
Version: Protocol 1

Commands > Reference > Contents

Objects

Skype has the following objects:

USER
PROFILE
CALL
MESSAGE
CHAT
CHATMESSAGE
VOICEMAIL
APPLICATION
GROUP

`USER`

The user object has the following properties:

HANDLE - username, for example: USER pamela HANDLE pamela.
FULLNAME - user's full name, for example: USER pamela FULLNAME Jane Doe.
BIRTHDAY - user's birth date in YYYYMMDD format, for example: USER bitman BIRTHDAY 19780329.
SEX - example: USER pamela SEX UNKNOWN. Values:
- UNKNOWN - user has not specified sex in personal profile.
- MALE
- FEMALE
LANGUAGE - name of language, for example: USER mike LANGUAGE English. In protocol 4 with the ISO 639 prefix, example: USER mike