API reference for Skype 2.0 (beta) now available
By
on January 5, 2006 in Developer Blog.
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)
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.
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
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
ClientApplication wants to talk to Skype. OK?
-> 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.
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.
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
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.
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
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.
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 charactersERROR 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 peopleERROR 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 misspelledERROR 11 Invalid call id
ID includes characters other than numeric charactersERROR 12 Unknown call
Call with specified ID does not exist in current user's call historyERROR 13 Invalid PROP
Property name missing or misspelledERROR 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 charactersERROR 20 Unknown call
Call with specified ID does not existERROR 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 charactersERROR 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 charactersERROR 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 charactersERROR 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 charactersERROR 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 charactersERROR 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
- 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
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:
a greeting type of voicemail object which is downloaded from the server
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 existERROR 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 existERROR 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 existERROR 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 misspelledERROR 31 Unknown message id
Unknown chat message IDERROR 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
ERROR 26 Invalid user handle
Target username missing or includes symbols which are not premittedERROR 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 misspelledERROR 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 misspelledERROR 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 misspelledERROR 108 user not contact
Command is allowed for authorized contacts onlyERROR 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:
- Use the AP2AP CREATE command to register a new application object.
- 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
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
