===========================================
    Skype For Asterisk for Asterisk 1.4
===========================================

Skype For Asterisk (SFA) is the first and only native channel driver to
connect Asterisk to the Skype network. The channel driver supports an
unlimited number of simultaneous users and an unlimited number of simultaneous
calls per user (subject to license key restriction).

IMPORTANT NOTE: Versions of Asterisk 1.4 prior to 1.4.25 have a bug which
causes Skype For Asterisk to function improperly.  Do not use versions of
Asterisk 1.4 prior to 1.4.25 with Skype for Asterisk.

IMPORTANT NOTE: Only Skype users that are created from inside the Skype
Business Control Panel (http://skype.com/business/) can be used with Skype For
Asterisk. The account used to administer the BCP and any members that are
added via invitations to Skype names or email address will not be usable with
Skype For Asterisk at this time. Skype is looking at making it possible to
migrate existing Accounts to managed BCP accounts.


----------------------------
AsteriskNOW 1.5 Installation
----------------------------
If you wish to use the RPM installation method, you will need to have a system
with AsteriskNOW 1.5 already installed and operational. Please note that the
FreePBX GUI interface provided as part of AsteriskNOW 1.5 is not able to
configure the SFA product, so you will have to manage the SFA product
configuration via direct editing of its configuration file (see below).

To install the SFA product on AsteriskNOW 1.5, assuming you are using Asterisk
1.4, 

$ yum install asterisk14-skypeforasterisk


-------------------------
Source (TAR) Installation
-------------------------
If you are not using AsteriskNOW 1.5, you will need to use the tar-file
(source code) installation method. Note that the tar-file contains both source
code and binary-only components, and thus there are different versions for
32-bit and 64-bit Linux systems.

Before installing Skype For Asterisk, it is very important that you have a full
Asterisk installation on the machine. This includes not only the Asterisk
runtime files, but also the development headers. If you installed Asterisk
from source and ran "make install" then you should have everything you need. If
you installed Asterisk via your distribution's package management system (RPM,
deb, etc.) then you need to make sure you install the development libraries as
well (asterisk-devel on RedHat-based systems or asterisk-dev on Debian-based).

To install SFA, copy the tar-file to your Asterisk server, then log in as the
root user and issue the following commands (assuming you are on a 32-bit Linux
system and are installing version 1.4_0.9.10 of the SFA product):

$ tar xzvf skypeforasterisk-1.4_0.9.10-x86_32.tar.gz
$ cd skypeforasterisk-1.4_0.9.10-x86_32
$ make
$ make install

To install the sample configuration file, issue the following command after
the 'make install' command:

$ make samples


---------
Licensing
---------
The SFA product uses license keys issued by Digium's product registration and
activation system. Each key enables a specific number of simultaneous calls
(active channels to or from the Skype network), and multiple keys on the
system will accumulate to provide a larger number of simultaneous calls. In
addition, the Digium G.729 software transcoder module also supports SFA keys
(this requires version 3.0.0 or later of the G.729 codec module) so that SFA
users will be able to use the G.729 codec for their Skype calls (this is
commonly required for SkypeIn and SkypeOut calls, for example). Beta licenses
will not be recognized by the G.729 module and therefore Beta users will need
to obtain a separate license for the G.729 codec to guarantee that they can
process the audio for SkypeIn and SkypeOut calls.

Internet access is required from your Asterisk server in order to register
your SFA license key for use. Outgoing network traffic on TCP port 443 (SSL)
must be allowed in order for the register utility to successfully communicate
with Digium's license server and complete the registration process. There must
be at least one active Ethernet network interface on your Asterisk server for
the registration process to complete successfully.


-------------------------------------
License Activation on AsteriskNOW 1.5
-------------------------------------
AsteriskNOW 1.5 has the Digium 'register' tool automatically available, so all
that is required is for you to log in to the Asterisk system (as root) and
issue the following commands:

$ yum install register
$ register

Follow the prompts provided by the registration utility and provide the
information it requests to activate your SFA license key.


-------------------------------------
License Activation on other systems
-------------------------------------
You will need to download the 'register' utility from the Digium download
server. The utility is located at

http://downloads.digium.com/pub/register/linux/register

After downloading the register utility, copy it to your Asterisk server, then
log in as root and issue the following commands:

$ chmod +x ./register
$ ./register

Follow the prompts provided by the registration utility and provide the
information it requests to activate your SFA license key.


------------------
After Installation
------------------
The SFA product consists of two Asterisk loadable modules:

-- res_skypeforasterisk.so

   This module contains the Skype engine, along with various libraries
   and other components required to talk to the Skype engine and
   manage user accounts, calls, presence, etc. This module is provided
   in a binary-only form.

-- chan_skype.so

   This module is the Asterisk channel driver that provides calling
   services to and from the Skype network, using the library services
   provided by res_skypeforasterisk.so.

If your Asterisk modules.conf file contains an 'autoload=yes' configuration
setting, then these modules will be automatically loaded the next time you
restart Asterisk. If not, you will need to add the following lines to the
modules.conf file:

load=res_skypeforasterisk.so
load=chan_skype.so

In addition to these modules, a sample configuration file (chan_skype.conf)
was installed if you used the RPM installation method or the 'make samples'
command as part of the TAR installation method. This file documents the
configuration options available for the SFA channel driver, including how to
define users and log them in to the Skype network.

Once you have restarted Asterisk, please issue the 'skype show version'
command at the Asterisk command line prompt. If the modules have loaded as
expected you will see version information for the SFA modules that are loaded
and also the number of SFA channel licenses that are available on your system.

Congratulations, you have installed Skype For Asterisk!


------------
CLI Commands
------------
The CLI commands available with Skype For Asterisk include:

skype show version - Displays SFA version information
skype show settings - Displays global SFA configuration information
skype show users - Displays a list of SFA users and their statuses
skype show user <username> - Displays configuration information for a SFA user
skype show buddies <username> - Displays a list of buddies for a SFA user
skype set debug on/off [user] [<username>] - Set/unset debugging for a user 
skype set vedebug on/off <username> - Set/unset user voice engine debugging
skype login/logoff user <username> - Log a user in/out


-------------------------------
Dialplan Usage - Outgoing Calls
-------------------------------
Using SFA channels in Asterisk is very similar to other Asterisk
channel drivers, with a channel name prefix of 'Skype'.

Dialing to a Skype name is a simple as:

exten => ...,1,Dial(Skype/austin_powers)

Similarly, calls to SkypeOut numbers can be dialed just as if they
were Skype names:

exten => ...,1,Dial(Skype/+12564286000)

However, there is one important note to remember: when calls are placed on the
Skype network, they are placed *by* a Skype name to their destination. This
means that when placing a call, SFA must select one of the defined Skype users
to be the 'originator' of that call; to control which user is used by default
for that purpose, you can set the 'default_user' option in chan_skype.conf.
Additionally, on a call-by-call basis, you can choose a specific user to be
the 'originator' of that call by prefixing the destination Skype name or
SkypeOut number with the originator's name:

exten =>  ...,1,Dial(Skype/james_bond@austin_powers)

This would result in user 'james_bond' placing the call to 'austin_powers'.


-------------------------------
Dialplan Usage - Incoming Calls
-------------------------------
Like other Asterisk channel drivers, SFA can direct incoming calls to any
desired context (specified on a per-user basis), optionally with a target
extension specified as well. The default configuration is to use the user's
Skype name as the target extension, so if user 'james_bond' has been
configured with 'context=demo', then placing the following entries in
extensions.conf would handle incoming calls for that user:

[demo]
exten => james_bond,1,NoOp(Incoming Skype Call!)
exten => james_bond,n,Dial(SIP/shoe-phone)

If you prefer, you can directly map Skype names to numeric extensions by
specifying that extension in the user's configuration in chan_skype.conf.


-------------------------------
Dialplan Usage - Incoming Calls
-------------------------------
To transfer an incoming Skype call via the dialplan, you can use the
Transfer() dialplan application.

[demo]
exten => james_bond,1,Transfer(Skype/austin_powers)

If you wish to set a topic on a transfered call, you can use the
SkypeTransfer() application. Please note that not all Skype clients display
the call topic for non-group calls.

[demo]
exten => james_bond,1,SkypeTransfer(austin_powers,Secret Call)


---------------------------------------
Dialplan Usage - Skype name information
---------------------------------------
When an Asterisk channel is connected to a Skype user, there are quite a few
user profile details that may be available (depending on privacy policies)
about that user. These details can be obtained in the dialplan by using the
CHANNEL() dialplan function, with the following item names:

	skype_language - A space-separated list of language identifiers
	skype_topic - A user-provided string that can identify the 'topic'
		      of the call; this is most commonly provided
		      using a URL to dial a Skype name and specifying it
		      as a query parameter, like this:

		      skype:austin_powers?call&topic=secret_plans
	skype_token - Similar to skype_topic
	skype_about - 'about' profile entry
	skype_birthday - Birthday
	skype_gender - Gender
	skype_homepage - Home page URL
	skype_homephone - Home phone number
	skype_officephone - Office phone number
	skype_mobilephone - Mobile phone number
	skype_city - City name
	skype_province - State/Province name
	skype_country - Country name

For example, to set the channel's language (used by prompt playback, the
voicemail application and other applications) to the language that the
connected Skype user prefers, your dialplan could include something like:

exten => ...,1,Set(CHANNEL(language)=${CHANNEL(skype_language)})


----------------------------------------------------
Dialplan Usage - Setting call and account properties
----------------------------------------------------
Since an outbound Skype call may originate from a non-Skype channel, the
CHANNEL() dialplan function cannot always be used to set Skype call
properties. The "topic" and "token" call properties can be set via the
SKYPE_CALL_PROPERTY() dialplan function. As a convenience, using
SKYPE_CALL_PROPERTY() to retrieve call (or caller) properties is supported as
well. For example:

exten => ...,1,Set(SKYPE_CALL_PROPERTY(topic)=Secret Plans)

or

exten => ...,1,NoOp(Topic is ${SKYPE_CALL_PROPERTY(topic)})

Other call properties available are "forwarded_by" which is set if a call has
been forwarded by another Skype client and "target_identity" which is set to
the PSTN number that the caller dialed if the call is a SkypeIn call. The
caller's skype account name can be retrieved via the "skypename" property.
CALLERID(name) will be the caller's full name if available and CALLERID(num)
will be either the PSTN number for a PSTN-based call or the skype account name
for a Skype to Skype call.

Skype account properties are stored on the Skype P2P network and include
things like availability, birthday, and geographical information. These
settings can be set both in chan_skype.conf, and via the
SKYPE_ACCOUNT_PROPERTY() dialplan function. For example:

exten => ...,1,Set(SKYPE_ACCOUNT_PROPERTY(jbond,availability)=Away)

Valid availability settings are "Offline", "Online", "Away", "Not
Available", "Do Not Disturb", "Invisible", and "Skype Me"

Other properties include "fullname", "birthday", "gender", "language"
"country", "province", "city", "phone_home", "phone_office",
"phone_mobile", "email", "homepage", and "about".

You can check an account's balance and currency type with skypeout_balance
and skypeout_currency.

------------------------
Dialplan Usage - Buddies
------------------------
To retrieve a buddy list via the dialplan, use SKYPE_BUDDIES. This function
will return an id that can be used with the SKYPE_BUDDY_FETCH function, which
will allow iteration over the buddy list. An example:

exten => jbond,1,Set(id=${SKYPE_BUDDIES(${EXTEN})})
exten => jbond,n,Set(ARRAY(buddy,status)=${SKYPE_BUDDY_FETCH(${id})})
exten => jbond,n,While($[${buddy}])
exten => jbond,n,NoOp(${buddy} is ${status})
exten => jbond,n,Set(ARRAY(buddy,status)=${SKYPE_BUDDY_FETCH(${id})})
exten => jbond,n,EndWhile()

-------------------------------
Dialplan Usage - Hints/Presence
-------------------------------
Unlike other Asterisk channel drivers, SFA does not manage 'devices' at all,
so the concept of 'device state' as represented by those channel drivers does
not really apply to Skype users. However, SFA does provide a mechanism for
subscribing to and being notified of changes in the presence state of Skype
users (which normal Skype clients show via graphical representation), and
making this available to the dialplan for hints to use.

SFA provides a 'Skype' custom device state provider, which can be used like
this:

exten => ...,hint,Skype:james_bond@austin_powers

Note the use of ':' instead of '/' to separate the state provider name the
item being watched; using '/' would make Asterisk treat 'austin_powers' as a
device and look for channels open to that Skype user (thus marking
'austin_powers' as busy), which is probably not what you really want in your
dialplan. Using ':' instead means that Asterisk will *trust* the SFA module to
report back the state of 'austin_powers' and won't try to infer what it might
be from other sources.

Just like placing outgoing calls, presence state requests must 'originate'
from a specific user; but unlike outgoing calls, there is no 'default' user, a
username must always be specified through prefixing.

There is another important point to consider: the Skype network does not allow
a user (user A) to see another user's (user B) state unless user A has added
user B to his or her buddy list and user B has authorized that addition. In
the example above, this means that 'james_bond' would have to add
'austin_powers' to his buddy list, and 'austin_powers' would need to authorize
that addition.

Since SFA will often be configured to use Skype user accounts that are never
used with an interactive Skype client, chan_skype.conf has a configuration
parameter to make this process easier. The buddy_autoadd option can be set to
a combination of 'hints' and 'buddies'. When the setting includes 'hints',
only those buddies that receive a presence information request (like from a
dialplan hint), will be added to the buddy list. The 'buddies' flag will
automatically add all buddies that have been authorized to receive that user's
presence infomration to the buddy list.

Finally, in some cases you may have Skype users logged in via SFA but you are
not at all interested in presence updates for those users' Skype buddies; in
that case, you can disable presence updates for those users by setting the
'buddy_presence' option in chan_skype.conf for the relevant users.


-------------------------------
Dialplan Usage - Skype Chat
-------------------------------
As of the 1.1.0 release, SFA supports Skype Chat. To send a chat message via
the dialplan, use:

SkypeChatSend(from,to,message)
  from - Skype account to send the message from
  to - Skype account to send the message to
  message - The message to send (UTF-8 encoded)

Example:
  exten => s,1,SkypeChatSend(fromuser,touser,message)

To receive a message, use the SKYPE_CHAT_RECEIVE dialplan function:

SKYPE_CHAT_RECEIVE(to,from,timeout)
  to - The Skype account receiving the message
  from - The Skype account that will be sending the message
  timeout - The number of seconds to wait for the message

Example:
  exten => s,1,Set(message=${SKYPE_CHAT_RECEIVE(touser,fromuser,30)})
  exten => s,n,NoOp(Received message: ${message})


----------
AMI Events
----------
Asterisk Manager Interface events are triggered for Skype users defined
in chan_skype.conf for both Login and Logout events. Status changes for
contacts in a Skype user's contact list will also trigger an AMI event.
Any Skype Chat message received generates an AMI event as well.

An example SkypeAccountStatus event:

Event: SkypeAccountStatus
Privilege: system,all
Username: james_bond
Status: Logged In

Possible "Status" values are currently "Logged In" and "Logged Out".

An example SkypeBuddyStatus event:
Event: SkypeBuddyStatus
Privilege: system,all
Buddy: Skype/james_bond@austin_powers
BuddyStatus: Offline

Possible "BuddyStatus" values are currently "Waiting for Authorization",
"Blocked", "Blocked Skypeout", "Skypeout", "Offline", "Online", "Away",
"Not Available", "Do Not Disturb", "Skype Me", "Offline (Voicemail Enabled)",
"Offline (Call Forwarding Enabled)", and "Unknown".

An example SkypeChatMessage AMI event:

Event: SkypeChatMessage
Privilege: system, all
Username: jbond
From: austin_powers
Message: U2t5cGUgRm9yIEFzdGVyaXNrIHJvY2tzIQ==

The "Message" field is base64 encoded since embedded newlines are not
permissible in AMI messages.


------------
AMI Commands
------------
The buddy list of a SFA user, including the full name and status of each buddy,
is available via the SkypeBuddies manager command.

An example SkypeBuddies request and response:

Action: SkypeBuddies
User: james_bond
ActionID: abc123

Response: Success
ActionID: abc123
Message: Skype buddy status list will follow

Event: SkypeBuddyEntry
ActionID: abc123
Buddy: echo123
Status: Waiting for Authorization

Event: SkypeBuddyEntry
ActionID: abc123
Buddy: austin_powers
Fullname: Austin Powers
Status: Offline (Voicemail Enabled)

Event: SkypeBuddylistComplete
ListItems: 2
ActionID: abc123

To retrieve information about a specific buddy, use SkypeBuddy.  Example:

Action: SkypeBuddy
User: james_bond
Buddy: austin_powers
ActionID: abc123

Response: Success
ActionID: abc123
availability: Online
fullname: Austin Powers
birthday: 19450328
phone_mobile: +15555551212

To set account properties for a user, use SkypeAccountProperty. Eample:

Action: SkypeAccountProperty
ActionID: abc123
User: james_bond
variable: fullname=James Bond
variable: availability=Skype Me

Response: Success
ActionID: abc123
Message: Properties set

To add a buddy to a user, use SkypeAddBuddy. Example:

Action: SkypeAddBuddy
ActionID: abc123
User: james_bond
Buddy: austin_powers
AuthMsg: Please authorize me!

To remove a buddy from a user, use SkypeRemoveBuddy. Example:

Action: SkypeRemoveBuddy
ActionID: abc123
User: james_bond
Buddy: austin_powers 

To send a chat message to a buddy, use SkypeChatSend. Messages should be
UTF-8 encoded. Example:

Action: SkypeChatSend
ActionID: abc123
User: james_bond
Skypename: austin_powers
Message: Shaken, not stirred

To send a multi-line Skype Chat message with AMI, it must be base64 encoded.
To send a base64 encoded message, add the Encoding header. Example:

Action: SkypeChatSend
ActionID: abc123
User: james_bond
Skypename: austin_powers
Encoding: base64
Message: RG9uJ3QNClJlYWQNClRoaXM=


----- Notes -----
** Only Skype users which are created with Skype's Business Control Panel will
be able to log in via SFA.

** The res_skypeforasterisk.so module contains a binary Skype engine called
'skyhost', which SFA communicates with to make and manage connections to the
Skype network. This engine runs as a separate Linux process, and during SFA
startup it is extracted into a temporary directory and then launched and
removed. By default it is extracted into the '/tmp' directory, but on some
systems the '/tmp' directory has been mounted with the the 'noexec' flag and
does not allow files to be executed. If your system is configured this way,
you can choose (or create) a directory anywhere else on your system that the
Asterisk process can write to, and use the 'engine_directory' configuration
option in chan_skype.conf to tell SFA where to extract the Skype engine.

** The Skype engine creates a small database of information for users that it
logs in to the Skype network; this database will be stored in a 'skype'
subdirectory of Asterisk's normal 'spool' directory, which is
/var/spool/asterisk by default. If your asterisk.conf specifies a different
path for this directory (via the 'astspooldir' option) then SFA will use that
directory instead.

** There are some settings that will not be modified by issuing a reload
command. These are engine_directory, disable_tcpauto, disable_udp, and
rtp_address. To change these values, chan_skype must be fully unloaded and
loaded again.

** The current version of chan_skype.so is not able to provide passthrough
G.729 support like other Asterisk channel drivers, so when a Skype call wants
to use G.729, you must have the codec_g729a.so module loaded and licensed for
transcoding. In future releases of SFA this will be improved, but for this
release it is suggested to configure your users in chan_skype.conf to only
allow G.711 ulaw and/or alaw unless you have G.729 transcoding available.
