Today we launched 1.4 of the Skype client.

We are still finalising the documentation and will make it available very soon, but in the meantime, this is the new APIs.

API changes for Skype for Windows 1.4 release

Today Windows Skype version 1.4 was published as secondary download.

http://www.skype.com/products/skype/windows/

Here is brief overview of new API features

* application-to-application communications
* my profile enchancements
* more control over UI
* other improvements

Application-to-Application Communications

A2A communications allows two API clients to exchange information without visual appearance.

* Connections are only allowed to online parties who are in contactlist or have active ongoing communication.
* Connections are only attempted to connectable users at CONNECT.
* Connections are established only when there is a same named application on the other side.
* Application name is limited by 32 bytes.
* Idle connections will be dropped in some time (usually 8 minutes)
* When connection is relayed throttling is engaged.
* If other party is logged in multiple Skype instances then stream for each instance is created

* Stream write provides reliable transmission to deliver large amount of data
* Maximum amount of write to stream can be 0xFFFF bytes long.
* Any character except 0x00 is allowed in message

* Datagrams are unreliable packets sent over network (usually translates to UDP).
* Datagrams maximum size is 1400 bytes.
* There is no guarantee that datagrams will be delivered.

Commands

// Register new application object
-> CREATE APPLICATION appname 
<- CREATE APPLICATION appname

// Establish connection to another user

-> ALTER APPLICATION appname CONNECT username

<- ALTER APPLICATION appname CONNECT username

// Write stream to connection "username:id"

-> ALTER APPLICATION appname WRITE username:id text

<- ALTER APPLICATION appname WRITE username:id

// Read stream to connection "username:id"

-> ALTER APPLICATION appname READ username:id

<- ALTER APPLICATION appname READ username:id text

// Write datagram "username:id"

-> ALTER APPLICATION appname DATAGRAM username:id text

<- ALTER APPLICATION appname DATAGRAM username:id

// Drop an connection to user

-> ALTER APPLICATION appname DISCONNECT username:id

<- ALTER APPLICATION appname DISCONNECT username:id

// Unregister an application

-> DELETE APPLICATION appname

<- DELETE APPLICATION appname

APPLICATION object properties

You can query properties with GET as usual and property changes are notified by Skype.
Syntax examples here are based on GET but CONNECTING, STREAMS, SENDING and RECEIVED make more sense as notifications.

// query connectable users
-> GET APPLICATION appname CONNECTABLE
<- APPLICATION appname CONNECTABLE [username[ username]*]

// query on-going connection process

// after the connection is established username is removed from CONNECTING list

-> GET APPLICATION appname CONNECTING

<- APPLICATION appname CONNECTING [username[ username]*]

// query open streams (connections)

-> GET APPLICATION appname STREAMS

<- APPLICATION appname STREAMS [username:id[ username:id]*]

// query if currently sending any data

// after the data is sent stream name is removed from SENDING list

-> GET APPLICATION appname SENDING

<- APPLICATION appname SENDING [username:id=bytes [username:id=bytes]*]

// query if there is data waiting in received buffer

// after the data is read from stream the stream name is removed from RECEIVED list

-> GET APPLICATION appname RECEIVED

<- APPLICATION appname RECEIVED [username:id=bytes [username:id=bytes]*]

// incoming datagram notification

<- APPLICATION appname DATAGRAM user:id text

Example of communiction

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 in its way...

[JIM] <- APPLICATION toru CONNECTING joe

// .. and is succeeded

[JIM] <- APPLICATION toru CONNECTING

// .. and has created 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=14

// .. and you are notified on delivery success

[JIM] <- APPLICATION toru SENDING 

// JOE receives notification about incoming message

[JOE] <- APPLICATION toru RECEIVED jim:1=12

// .. 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

// 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 notifcatoin

[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

My Profile enhancements

PROFILE object allows to
* set and get all profile fields as UI
* setup the call forwarding rules

-> GET/SET PROFILE
   { FULLNAME text
   | BIRTHDAY yyyymmdd           // 0 is returned if not set; no partial birthday allowed
   | SEX {MALE|FEMALE|UNKNOWN}
   | LANGUAGES [lang[ lang]*]    // lang is two letter ISO code (en, de, et)
   | COUNTRY iso2 name           // iso2 - two letter ISO code; name - country name
   | PROVINCE text
   | CITY text
   | PHONE_HOME text
   | PHONE_OFFICE text
   | PHONE_MOBILE text
   | HOMEPAGE text
   | ABOUT text
   | MOOD_TEXT text
   | TIMEZONE offset             // offset is given in minutes from GMT
   }

Notes:
* Windows 1.4 UI does not publish MOOD_TEXT and TIMEZONE (planned in 1.5)
* Windows 1.4 UI allows only setting one language

Call forwarding setup

-> GET/SET PROFILE

   { CALL_NOANSWER_TIMEOUT timeout                    // timeout for call forwarding

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

   }

* 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 (on forwarder expense)
* call can be forwarded multiple numbers: 0,45,jim 46,150,joe
* numbers can overlap in time (all ring, first one to pick wins): 0,45,jim 0,45,joe

Notes:
* Skype Windows 1.4 UI defaults to no-answer timeout 15 seconds
* Skype Windows 1.4 UI defaults to 0,45 start and endtime in rules
* Skype Windows 1.4 UI allows to set max 3 numbers

More control over UI

New OPEN commands:

-> OPEN

   { PROFILE                // view my profile

   | USERINFO username      // view other user profile

   | CONFERENCE             // open create conference dialog

   | SEARCH                 // open search form

   | OPTIONS [page]         // open options dialog

   | CALLHISTORY            // focus call history tab

   | CONTACTS               // focus contacts tab

   | DIALPAD                // focus dial tab

   | SENDCONTACTS           // open send contacts dialog

   | BLOCKEDUSERS           // open blocked users dialog

   | IMPORTCONTACTS         // open import contacts wizard

   | GETTINGSTARTED         // open getting started wizard

   | AUTHORIZATION username // open ask authorization dialog (this can change) 

   }

* Options page: general, privacy, notifications, soundalerts, sounddevices, hotkeys, connection, voicemail, callforward, video, advanced

Notification of when contactlist focus changes:

<- CONTACTS FOCUSED username  // when contact gains focus

<- CONTACTS FOCUSED           // when loses focus

Other improvements

New USER object properties

-> GET USER username 

   { MOOD_TEXT              // mood text for user

   | ALIASES test           // list of assigned aliases

   | TIMEZONE offset        // time offset from GMT in minutes

   }

Following privacy settings apply:
* ALIASES is visible only as result of direct match for alias search
* MOOD_TEXT is visible only for authorized contacts

Notes:
* Windows 1.4 UI does not publish MOOD_TEXT and TIMEZONE (planned in 1.5)

Query if ringtones are enabled:

-> GET RINGTONE  STATUS

<- RINGTONE  {ON|OFF}

* notice that "GET RINGTONE id" command still returns filename

Expressive content (see http://personal.skype.com/) support for SET RINGTONE/AVATAR

Support expressive content ID-s

-> SET RINGTONE 

   * 1101 - Ringtone

   * 1102 - Ringback tone

   * 1103 - Busy tone

   * 1104 - Dialing tone

   * 1105 - Connecting sound

   * 1202 - Resume sound

   * 1203 - Hangup sound

   * 1204 - Incoming message sound

   * 1205 - Online alert sound

Supports .skype files:

-> SET RINGTONE id filename:idx    // idx refers to content number (0,...)

-> SET AVATAR id filename:idx

Notes:
* .skype files can contain multiple contents which are enumerated by integer ID-s (idx)

skype: URI handler (not related to API)

Not related to API but could be useful in development.

General syntax

SKYPE_URI    = "skype:" [targets] ["?" query ] ["#" fragment ]


targets      = 1* (target / ";" )

target       = identity / PSTN

identity     = skypename / alias

skypename    = 1*(ALPHA / DIGIT / "." / "," ) ; to be clarified

skypenames   =  1*( skypename / ";")

alias        =  ... ; see ["TechGroup/DataFormats"]

                    ; unicode chars are in UTF-8 and % encoded; see RFC3987 uchar mapping

PSTN         = "+" (DIGIT / ALPHA ) *(DIGIT / ALPHA / "-" )   ; supports +800-FLOWERS

query        = action [ *( "?" term "=" conditon ) ] 

term         = 1*ALPHA

condition    = 1*unserved   ; to be clarified

fragment     = 1*unserved   ; to be clarified

Skype for Windows 1.4 version handles following:

skype:                           ; focus / open skype UI

skype:                  ; take default double-click action on contact 

skype:?call             ; call to target(s): can be skypename, alias or PSTN

skype:?chat          ; start chat/multichat with skypename(s)

skype:?voicemail      ; leave voicemail to skypename

skype:?add            ; add skypename to contactlist; show authorization dialog

skype:?sendfile      ; open sendfile dialog to skypenames

skype:?userinfo       ; show info (profile) for 

skype:?chat&id=[#time]       ; open existing multichat with ; time: YYYY-MM-DDThh:mm:ssTZ / YYYY-MM-DDZhh:mm:ss

Examples:
* skype:echo123
* skype:echo123?call
* skype:echo123?chat

Notice that there is no "//" in skype: URI - skype://echo123 does not work.