Lance's Blog

Creating a simple Adhearsion app with XMPP in Adhearsion 1.2

 

Ahearsion has many features including the ability to integrate with XMPP to send messages via jabber.  Unfortunately the documentation did not get the attention that we wanted to give it in this version so here is a tutorial on how to get XMPP working with Adhearsion.  Our app will create a Adhearsion app that will send a message to various users whenever a new call connects and disconnects from our rudimentary application that will be joining two calls together. This tutorial assumes that you are familiar with the basics of Adhearsion and are able to create a basic adhearsion app that uses an Asterisk server.

 

pre-requisites

You will need an Ruby dev environment,  a Asterisk server and a Jabber server.  For this example I am going to use a Ubuntu box and install ejabberd via

 

“apt-get install ejabberd”  

 

Once you have that installed you will need to create a  few users.

 

ejabberdctl register adhearsion <ip address of server> <some password>
ejabberdctl register client1 <ip address of server> <some password>
ejabberdctl register client2 <ip address of server> <some password> 

 

When we connect everything up we are going to be communicating between the various users via direct messages.  It is also possible to use a MUC (what might more commonly be called a chat room),  but that will not be covered in this tutorial.

 

Asterisk has a number of settings.  For this example my files are set up as follows.

 

extensions.conf

 

[default]
exten => 101,1,Dial(SIP/client1)
exten => 102,1,Dial(SIP/client2) 
exten => localhost,1,Dial(SIP/localhost)
exten => blink,1,Dial(SIP/blink)
exten => _.,1,AGI(agi://localhost/adhearsion)
exten => _.,n,Hangup

[from-sipp]
exten => _.,1,AGI(agi://localhost/adhearsion)
exten => _.,n,Hangup

  

sip.conf

 

[general]
tos=none
dtmfmode=info
allow=alaw
allow=ulaw

[127.0.0.1](!)
type=friend
callerid=112
host=dynamic
canreinvite=no
context=from-sipp
dtmfmode=rfc2833
qualify=2000

[client1](127.0.0.1)
[client2](127.0.0.1)
[blink](127.0.0.1)
[localhost](127.0.0.1)
 

Without going into a long explanation these are setting up accounts and extensions for users called client1,  client2,  blink,  and localhost.  You should be able to use your favorite sip client to connect to your asterisk server after you start it up with any of these 4 users.

 

Now we will create our basic Adhearsion app.

 

ahn create jabber_app

 

edit the config/startup.rb file.

 

In it you will find a XMPP section.  Uncomment the settings and set them to match your local xmpp server.

 

  config.enable_xmpp :jid => 'adhearsion@<ip addres of ejabberd server>',
                      :password =>  <secret>,
                      :server => <ip address of ejabberd server>,
                      :port => 5222

 

outside of the “Adhearsion::Configuration.configure do |config|” you will also want to add the following in the same file.  These are global variables that we will be using in out dialplan,  and are not required for XMPP support.

 

$agents = {:client1 => :free, :client2 => :free}
$extensions = {:client1 => 101, :client2 => 102}

 

For this demo we are going to be registering with ejabberd as the adhearsion user from the Adhearsion application.

 

You will also need to add the blather gem to your gemfile

 

gem ‘blather’ 

 

and install it

 

bundle install

 

Adhearsion XMPP support uses a gem called blather.  There is some documentation on how to use it at their site,  but at the time of this writing I could not find any documentation describing what I was trying to do. 

 

When you enable XMPP support Adhearsion includes Blather for you.  Now make sure that your ejabberd server is running.  Lets test things out to make sure that everything is running correctly.  First we are going to set up a jabber client to make sure that our server is working correctly.  In Adium that is as simple as setting up one account with client1 and another as adhearsion using

 

Jabber ID:  ‘adhearsion@<ejabberd server ip address>’
Password:  ‘you account password’

 

Using one up for adhearsion and client1.  Once you have done that send a test message from adhearsion to client1@<jabberd server ip address> .  If everything is working correctly you will see the message pop up under the client1 account.

 

Now go to a command prompt and from your adhearsion app directory and start up the adhearsion console via

 

ahn start console .

 

For our app we will only be sending outbound messages,  so lets create a Blather message object and populate it.  At the console prompt type the following.

 

msg = Blather::Stanza::Message.new
msg.body = “Friday hugs from Adhearsion”
msg.to = “client1@<ejabberd server ip address>”
msg.from = “whoever you want”

 

Now you can send it via the adhearsion reference to your open chat connection client via

 

XMPP::Connection.client.write msg

 

If everything is working correctly you should see a message pop up from Adhearsion to your client1 account in your chat client.

 

Now for the final pieces to finish out our application.

 

Add the following code to your dialplan.rb file

 

from_sipp {
  agent = $agents.index :free
  if agent
    $agents[agent] = :on_call
    extension = $extensions[agent]
    message = Blather::Stanza::Message.new
    message.to = "#{agent}@#{$xmpp_ip_address}"
    message.body = $agents[agent]
 
    XMPP::Connection.client.write message
    dial 'SIP/blink'
    $agents[agent] = :free
    message.body = $agents[agent]
    XMPP::Connection.client.write message
  end
}

 

now make sure that you have accounts set up in your sip client for client1,  client2,  localhost,  and blink.  If you dial localhost you should see a message pop up from adhearsion to one of the free clients and also have a call dial out to the client.  When you pick up the call from the client the two calls will be joined.  Once one of the parties hangs up a message will be sent indicating that the call has been ended,  the call will be hung up and the client will be set to a free state. 

 

There is a lot of other stuff that can be done with this,  but this should be enough to get you started using XMPP in Adhearsion.