Slixmpp Quickstart - Echo Bot#
If you have any issues working through this quickstart guide join the chat room at email@example.com.
If you have not yet installed Slixmpp, do so now by either checking out a version with Git.
As a basic starting project, we will create an echo bot which will reply to any messages sent to it. We will also go through adding some basic command line configuration for enabling or disabling debug log outputs and setting the username and password for the bot.
For the command line options processing, we will use the built-in
module and the
getpass module for reading in passwords.
TL;DR Just Give Me the Code#
As you wish: the completed example.
To get started, here is a brief outline of the structure that the final project will have:
#!/usr/bin/env python # -*- coding: utf-8 -*- import sys import asyncio import logging import getpass from argparse import ArgumentParser import slixmpp '''Here we will create out echo bot class''' if __name__ == '__main__': '''Here we will configure and read command line options''' '''Here we will instantiate our echo bot''' '''Finally, we connect the bot and start listening for messages'''
Creating the EchoBot Class#
There are three main types of entities within XMPP — servers, components, and clients. Since our echo bot will only be responding to a few people, and won’t need to remember thousands of users, we will use a client connection. A client connection is the same type that you use with your standard IM client such as Pidgin or Psi.
Slixmpp comes with a
which we can extend to add our message echoing feature.
requires the parameters
password, so we will let our
EchoBot class accept those
class EchoBot(slixmpp.ClientXMPP): def __init__(self, jid, password): super().__init__(jid, password)
Handling Session Start#
The XMPP spec requires clients to broadcast its presence and retrieve its roster (buddy list) once it connects and establishes a session with the XMPP server. Until these two tasks are completed, some servers may not deliver or send messages or presence notifications to the client. So we now need to be sure that we retrieve our roster and send an initial presence once the session has started. To do that, we will register an event handler for the session_start event.
def __init__(self, jid, password): super().__init__(jid, password) self.add_event_handler('session_start', self.start)
Since we want the method
self.start to execute when the session_start event is triggered,
we also need to define the
async def start(self, event): self.send_presence() await self.get_roster()
Not sending an initial presence and retrieving the roster when using a client instance can prevent your program from receiving presence notifications or messages depending on the XMPP server you have chosen.
Our event handler, like every event handler, accepts a single parameter which typically is the stanza
that was received that caused the event. In this case,
event will just be an empty dictionary since
there is no associated data.
The second requirement is fulfilled using
will send an IQ stanza requesting the roster to the server and then wait for the response. You may be wondering
get_roster returns since we are not saving any return
value. The roster data is saved by an internal handler to
self.roster, and in the case of a
ClientXMPP instance to
self.client_roster. (The difference between
self.client_roster is that
self.roster supports storing roster information for multiple JIDs, which is useful
for components, whereas
self.client_roster stores roster data for just the client’s JID.)
It is possible for a timeout to occur while waiting for the server to respond, which can happen if the
network is excessively slow or the server is no longer responding. In that case, an
IQTimeout is raised. Similarly, an
IQError exception can
be raised if the request contained bad data or requested the roster for the wrong user. In either case, you can wrap the
get_roster() call in a
except block to retry the roster retrieval process.
The XMPP stanzas from the roster retrieval process could look like this:
<iq type="get"> <query xmlns="jabber:iq:roster" /> </iq> <iq type="result" to="firstname.lastname@example.org" from="example.com"> <query xmlns="jabber:iq:roster"> <item jid="email@example.com" subscription="both" /> </query> </iq>
get_roster is using
<iq/> stanzas, which will always receive an answer, it should be awaited on, to keep
a synchronous flow.
Responding to Messages#
Now that an
EchoBot instance handles session_start, we can begin receiving and
responding to messages. Now we can register a handler for the message event that is raised
whenever a messsage is received.
def __init__(self, jid, password): super().__init__(jid, password) self.add_event_handler('session_start', self.start) self.add_event_handler('message', self.message)
The message event is fired whenever a
<message /> stanza is received, including for
group chat messages, errors, etc. Properly responding to messages thus requires checking the
'type' interface of the message stanza object. For responding to only messages
addressed to our bot (and not from a chat room), we check that the type is either
chat. (Other potential types are
def message(self, msg): if msg['type'] in ('normal', 'chat'): msg.reply("Thanks for sending:\n%s" % msg['body']).send()
Let’s take a closer look at the
.reply() method used above. For message stanzas,
.reply() accepts the parameter
body (also as the first positional argument),
which is then used as the value of the
<body /> element of the message.
Setting the appropriate
to JID is also handled by
Another way to have sent the reply message would be to use
which is a convenience method for generating and sending a message based on the values passed to it. If we were to use
this method, the above code would look as so:
def message(self, msg): if msg['type'] in ('normal', 'chat'): self.send_message(mto=msg['from'], mbody='Thanks for sending:\n%s' % msg['body'])
Whichever method you choose to use, the results in action will look like this:
<message to="firstname.lastname@example.org" from="email@example.com" type="chat"> <body>Hej!</body> </message> <message to="firstname.lastname@example.org" type="chat"> <body>Thanks for sending: Hej!</body> </message>
XMPP does not require stanzas sent by a client to include a
from attribute, and
leaves that responsibility to the XMPP server. However, if a sent stanza does
from attribute, it must match the full JID of the client or some
servers will reject it. Slixmpp thus leaves out the
from attribute when replying
using a client connection.
Command Line Arguments and Logging#
While this isn’t part of Slixmpp itself, we do want our echo bot program to be able
to accept a JID and password from the command line instead of hard coding them. We will
argparse module for this.
We want to accept three parameters: the JID for the echo bot, its password, and a flag for displaying the debugging logs. We also want these to be optional parameters, since passing a password directly through the command line can be a security risk.
if __name__ == '__main__': # Setup the command line arguments. parser = ArgumentParser(description=EchoBot.__doc__) # Output verbosity options. parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) # JID and password options. parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", help="password to use") args = parser.parse_args() if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ")
Since we included a flag for enabling debugging logs, we need to configure the
logging module to behave accordingly.
if __name__ == '__main__': # .. option parsing from above .. logging.basicConfig(level=args.loglevel, format='%(levelname)-8s %(message)s')
Connecting to the Server and Processing#
- There are three steps remaining until our echo bot is complete:
We need to instantiate the bot.
The bot needs to connect to an XMPP server.
We have to instruct the bot to start running and processing messages.
if __name__ == '__main__': # .. option parsing and logging steps from above xmpp = EchoBot(opts.jid, opts.password) xmpp.register_plugin('xep_0030') # Service Discovery xmpp.register_plugin('xep_0199') # Ping
EchoBot class had a hard dependency on a plugin, we could register that plugin in
EchoBot.__init__ method instead.
Now we’re ready to connect and begin echoing messages. If you have the package
aiodns installed, then the
will perform a DNS query to find the appropriate server to connect to for the
given JID. If you do not have
aiodns, then Slixmpp will attempt to
connect to the hostname used by the JID, unless an address tuple is supplied
if __name__ == '__main__': # .. option parsing & echo bot configuration xmpp.connect(): xmpp.process(forever=True)
slixmpp.basexmpp.BaseXMPP.connect() will only schedule a connection
asynchronously. To actually connect, you need to let the event loop take over.
This is done with the
which can either run forever (
forever=True, the default), run for a (maximum)
duration of time (
timeout=n), and/or run until it gets disconnected (
process() is not required if you already have an event loop
running, so you can handle the logic around it however you like.
Before slixmpp, :meth:slixmpp.basexmpp.BaseXMPP.process` took
arguments. These do not make sense anymore and have been removed. Slixmpp does not use
threads at all.
The Final Product#
Here then is what the final result should look like after working through the guide above. The code can also be found in the Slixmpp examples directory.
You can run the code using:
python echobot.py -d -j email@example.com
which will prompt for the password and then begin echoing messages. To test, open your regular IM client and start a chat with the echo bot. Messages you send to it should be mirrored back to you. Be careful if you are using the same JID for the echo bot that you also have logged in with another IM client. Messages could be routed to your IM client instead of the bot.
#!/usr/bin/env python3 # Slixmpp: The Slick XMPP Library # Copyright (C) 2010 Nathanael C. Fritz # This file is part of Slixmpp. # See the file LICENSE for copying permission. import logging from getpass import getpass from argparse import ArgumentParser import slixmpp class EchoBot(slixmpp.ClientXMPP): """ A simple Slixmpp bot that will echo messages it receives, along with a short thank you message. """ def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) # The session_start event will be triggered when # the bot establishes its connection with the server # and the XML streams are ready for use. We want to # listen for this event so that we we can initialize # our roster. self.add_event_handler("session_start", self.start) # The message event is triggered whenever a message # stanza is received. Be aware that that includes # MUC messages and error messages. self.add_event_handler("message", self.message) async def start(self, event): """ Process the session_start event. Typical actions for the session_start event are requesting the roster and broadcasting an initial presence stanza. Arguments: event -- An empty dictionary. The session_start event does not provide any additional data. """ self.send_presence() await self.get_roster() def message(self, msg): """ Process incoming message stanzas. Be aware that this also includes MUC messages and error messages. It is usually a good idea to check the messages's type before processing or sending replies. Arguments: msg -- The received message stanza. See the documentation for stanza objects and the Message stanza to see how it may be used. """ if msg['type'] in ('chat', 'normal'): msg.reply("Thanks for sending\n%(body)s" % msg).send() if __name__ == '__main__': # Setup the command line arguments. parser = ArgumentParser(description=EchoBot.__doc__) # Output verbosity options. parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) # JID and password options. parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", help="password to use") args = parser.parse_args() # Setup logging. logging.basicConfig(level=args.loglevel, format='%(levelname)-8s %(message)s') if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") # Setup the EchoBot and register plugins. Note that while plugins may # have interdependencies, the order in which you register them does # not matter. xmpp = EchoBot(args.jid, args.password) xmpp.register_plugin('xep_0030') # Service Discovery xmpp.register_plugin('xep_0004') # Data Forms xmpp.register_plugin('xep_0060') # PubSub xmpp.register_plugin('xep_0199') # XMPP Ping # Connect to the XMPP server and start processing XMPP stanzas. xmpp.connect() xmpp.process()