Agent XMPP

Agent XMPP is a simple DSL for writing XMPP automated clients that support Messaging, Ad-Hoc Commands and Publish Subscribe Events. An application that responds to an Ad-Hoc command can be written with few lines of code.

# myapp.rb
require 'rubygems'
require 'agent_xmpp'

execute 'hello' do
  'Hello World' 

Specify the application Jabber ID (JID), password and roster in agent_xmpp.yml.

jid: [email protected]
password: pass
        jid:[email protected]

Be sure libxml2 headers are available,

sudo apt-get install libxml2-dev

Install the gem

sudo gem install troystribling-agent_xmpp --source=

Install the Gajim XMPP Client,, and connect to [email protected] (Be warned that installing Gajim on OS X can be painful. Linux is recommended. Also, for Ubuntu installs, download the tar ball from the site. The version in the Ubuntu repositories is older and does not have a completed Ad-Hoc Command implementation).

Run the application

ruby myapp.rb

When started for the first time myapp.rb will automatically send buddy requests to all contacts specified in agent_xmpp.yml. Accept the buddy request and myapp will appear as a contact in the Gajim roster. Right click on myapp and select execute commands from the drop down menu. A list of Ad-Hoc Commands will be displayed containing hello. Select it and click the forward button to execute.

More Examples

More examples can be found at

Ad-Hoc Command Response Payload

Agent XMPP will map scalars, arrays and hashes returned by execute blocks to jabber:x:data command response payloads (see XEP-0004 for a description of jabber:x:data). All scalars have to_s applied prior to building the command response payload.

execute 'scalar' do

execute 'hash' do
  {:a1 => 'v1', :a2 => 'v2'}

execute 'scalar_array' do
  ['v1', 'v2','v3', 'v4']

execute 'hash_array' do
  {:a1 => ['v11', 'v11'], :a2 => 'v12'}

execute 'array_hash' do
  [{:a1 => 'v11', :a2 => 'v12'}, 
   {:a1 => 'v21', :a2 => 'v22'}, 
   {:a1 => 'v31', :a2 => 'v32'}]

execute 'array_hash_array' do
  [{:a1 => ['v11', 'v11'], :a2 => 'v12'}, 
   {:a1 => ['v21', 'v21'], :a2 => 'v22'}, 
   {:a1 => ['v31', 'v31'], :a2 => 'v32'}]

a params structure is available within the execute block containing routing information.

Send Command

Commands may be sent with or without a response callback,

command(:to=>'[email protected]/ahost', :node=> 'hello') do |status, data|
  puts "COMMAND RESPONSE: #{status}, #{data.inspect}"

command(:to=>'[email protected]/ahost', :node=> 'bye')

and within execute blocks.

execute 'hash_hello' do
  command(:to=>params[:from], :node=> 'hello') do |status, data|
    puts "COMMAND RESPONSE: #{status}, #{data.inspect}"
  {:a1 => 'v1', :a2 => 'v2'}


Publish nodes are configured in agent_xmpp.yml.

jid: [email protected]
password: pass
        jid:[email protected]
        node: time
        title: "Curent Time"   
        node: alarm
        title: "Alarms"

The nodes are created if they do not exist and publish methods are generated for each node.

publish_time('The time is:' +

publish_alarm({:severity => :major, :description => "A really bad failure"})

Publish nodes discovered that are not in agent_xmpp.yml will be deleted.

Publish Options

The following publish options are available with the indicated default values. The options may be changed in agent_xmpp.yml.

:title                    => 'event',
:access_model             => 'presence',
:publish_model            => 'publishers',
:max_items                => 20,
:deliver_notifications    => 1,
:deliver_payloads         => 1,
:persist_items            => 1,
:subscribe                => 1,
:notify_config            => 0,
:notify_delete            => 0,
:notify_retract           => 0,

See for a detailed description.


Declare event blocks in myapp.rb to subscribe to published events .

# myapp.rb
require 'rubygems'
require 'agent_xmpp'

event '[email protected]', 'time' do
  message(:to=>'[email protected]', :body=>"Got the event at: " +

Agent XMPP will verify subscription to the event and subscribe if required. Subscriptions discovered that are not declared by an event block will be deleted.

Receive Chat Messages

Declare chat blocks in myapp.rb to receive and respond to chat messages.

# myapp.rb
require 'rubygems'
require 'agent_xmpp'

chat do

If the chat block returns a String a response will be sent to the message sender.

Send Chat Messages

message(:to=>'[email protected]/onahost', :body=>"Hello from #{AgentXmpp.jid.to_s} at " +


Roster groups may be specified in agent_xmpp.yml.

jid: [email protected]
password: pass
        jid:[email protected]
        groups: [good group, owners]

        jid: [email protected]
        groups: [bad group]

Agent XMPP will update the roster maintained on the XMPP server to be consistent with to the roster specified in agent_xmpp.yml.

Routing Priority

The routing priority may be configured in agent_xmpp.yml. The default value is 1. Valid values are between -127 and 128. See for a details.

jid: [email protected]
password: pass
priority: 128
        jid:[email protected]
        groups: [good group, owners]

Major Event Callbacks

Agent XMPP provides callbacks for applications to respond to major events that occur during execution.

# application starting

# connected to server

# client restarts when disconnected form server

# a pubsub node was discovered at service
discovered_pubsub_node{|service, node|}

# command nodes were discovered at jid
discovered_command_nodes{|jid, nodes|}

# a presence message of status :available or :unavailable was received from jid
received_presence{|from, status|}


  • Basic SASL

Development with XMPP Clients

Ad-Hoc Commands, jabber:x:data Forms nor Service Discovery are widely supported by XMPP clients and I have not found a client that supports Publish-Subscribe. Gajim provides support for Ad-Hoc Commands and jabber:x:data Forms. Service Discovery, which is useful for Publish-Subscibe development, is supported by Gajim, but Psi provides a much better implementation. Both Gajim and Psi provide an interface for manual entry of XML messages. Since Publish-Subscribe is not supported on the user interface manual entry of messages is required for development. Example messages can be found at


By default log messages are written to STDOUT. A log file can be specified with the -l option.

ruby mybot.rb -l file.log

The logger can be accessed and configured.

before_start do
  AgentXmpp.logger.level = Logger::WARN 

Supported XEPs

XEP-0004 jabber:x:data Forms
XEP-0030 Service Discovery
XEP-0050 Ad-Hoc Commands
XEP-0060 Publish Subscribe
XEP-0092 Software Version

Message Processing Callbacks

Message processing callbacks are available to applications to extend the message processing work flow. To receive callbacks a delegate object must be provided that implements the callbacks of interest.

after_connected do |connection|













did_receive_presence(connection, presence)

did_receive_presence_subscribe(connection, presence)

did_receive_presence_subscribed(connection, presence)

did_receive_presence_unavailable(connection, presence)

did_receive_presence_unsubscribed(connection, presence)

did_receive_presence_error(pipe, presence)


did_receive_roster_result(connection, stanza)

did_receive_roster_set(connection, stanza)

did_receive_roster_item(connection, roster_item)

did_remove_roster_item(connection, roster_item)


did_receive_update_roster_item_result(connection, response)

did_receive_update_roster_item_error(connection, response)

did_receive_remove_roster_item(connection, response)

did_receive_remove_roster_item_error(connection, response)

Service Discovery

did_receive_version_result(connection, version)

did_receive_version_get(connection, request)

did_receive_version_error(connection, error)

did_receive_discoinfo_get(connection, request) 

did_receive_discoinfo_result(connection, discoinfo)

did_receive_discoinfo_error(connection, error)

did_receive_discoitems_result(connection, discoitems)

did_receive_discoitems_get(connection, request)

did_receive_discoitems_error(connection, result)


did_receive_command_set(connection, stanza)

did_receive_message_chat(connection, stanza)

did_receive_message_normal(connection, stanza)

did_receive_pubsub_event(connection, event, to, from)


did_receive_publish_result(connection, result, node)

did_receive_publish_error(connection, result, node)

did_discover_pubsub_service(connection, jid, ident)

did_discover_pubsub_collection(connection, jid, node)

did_discover_pubsub_leaf(connection, jid, node)

did_discover_user_pubsub_root(pipe, pubsub, node)

did_receive_pubsub_subscriptions_result(connection, result)

did_receive_pubsub_subscriptions_error(connection, result)

did_receive_pubsub_affiliations_result(connection, result)

did_receive_pubsub_affiliations_error(connection, result)

did_discover_user_pubsub_root(connection, result)

did_receive_create_node_result(connection, node, result)    

did_receive_create_node_error(connection, node, result)    

did_receive_delete_node_result(connection, node, result)    

did_receive_delete_node_error(connection, node, result)    

did_receive_pubsub_subscribe_result(connection, result, node) 

did_receive_pubsub_subscribe_error(connection, result, node) 

did_receive_pubsub_subscribe_error_item_not_found(connection, result, node) 

did_receive_pubsub_unsubscribe_result(connection, result, node) 

did_receive_pubsub_unsubscribe_error(connection, result, node)


did_receive_unsupported_message(connection, stanza)

Copyright © 2009 Troy Stribling. See LICENSE for details.