Getting started

This guide will show you how to use the library to create a simple XMPP client.

Creating a client

First, you need to create a client instance:

from osmxmpp import XmppClient
client = XmppClient("jabber.org", port=5222)

The first argument is the hostname of the XMPP server, and the second argument is the port.

Registering handlers

After creating the client instance, you need to register handlers for the events you want to listen to. For example, to listen to the ready event, you can use the on_ready method:

@client.on_ready
def on_ready():
    print(f"Logged in as {client.jid}")

The on_ready method is a decorator that registers the on_ready handler. The handler will be called when the client is ready to send and receive XMPP stanzas.

Note

The on_ready will return immediately after registering the handler. It will not call handler immediately, but after event is triggered.

You can still call the handler immediately by calling the on_ready method without the decorator:

on_ready()

Managing messages

To send a message, use the send_message method:

client.send_message("john@jabber.org", "Hello, John!")

To reply to a message, use the reply_to_message method:

client.reply_to_message("12345678", "john@jabber.org", "Thanks you very m.ch, John!")

To edit a message, use the edit_message method:

client.edit_message("87654321", "john@jabber.org", "Thank you very much, John!")

Receiving stanzas

To receive a message, you need to register a handler for the message event:

@client.on_message
def on_message(message):
    if message.body is None: #Messages body can be empty
        return

    print(f"Received message from {message.from_jid}: {message.body}")

To receive a presence, you need to register a handler for the presence event:

@client.on_presence
def on_presence(presence):
    print(f"Received presence from {presence.from_jid}: {presence.body}")

To receive an IQ, you need to register a handler for the iq event:

@client.on_iq
def on_iq(iq):
    print(f"Received IQ from {iq.from_jid}: {iq.body}")

Features

Features are used to implement specific XMPP stream features. After connecting to the XMPP server, server will send a stream features stanza.

To connect features to the client, you need to call the connect_feature method before connecting to the XMPP server:

from osmxmpp.features.tls import TlsFeature
from osmxmpp.permission import XmppPermission

# ...create client instance...

client.connect_feature(
    TlsFeature(),
    [
        XmppPermission.SEND_XML,
        XmppPermission.RECV_XML,
        XmppPermission.CHANGE_SOCKET,
        XmppPermission.GET_SOCKET,
        XmppPermission.OPEN_STREAM
    ]
)
# or
client.connect_feature(
    TlsFeature(),
    TlsFeature.REQUIRED_PERMISSIONS
)
# or
client.connect_feature(
    TlsFeature(),
    XmppPermission.ALL
)

Note

Connect features before connecting to the XMPP server for them to properly work.

You can see the list of available features in the Features section.

Extensions

Extensions are used to implement specific XMPP extensions & etc.

To connect extensions to the client, you need to call the connect_extension method before connecting to the XMPP server:

from osmxmpp.extensions.omemo import OmemoExtension
from osmxmpp.permission import XmppPermission

# ...create client instance...

client.connect_extension(
    OmemoExtension(),
    [
        XmppPermission.GET_JID,
        XmppPermission.SEND_XML,
        XmppPermission.LISTEN_ON_READY,
        XmppPermission.LISTEN_ON_IQ,
        XmppPermission.HOOK_ON_MESSAGE,
        XmppPermission.HOOK_SEND_MESSAGE,
    ]
)
# or
client.connect_extension(
    OmemoExtension(),
    OmemoExtension.REQUIRED_PERMISSIONS
)
# or
client.connect_extension(
    OmemoExtension(),
    XmppPermission.ALL
)

Note

Connect extensions before connecting to the XMPP server for them to properly work.

You can see the list of available extensions in the Extensions section.

Authentication

To authenticate to the XMPP server, you need to connect to the XMPP server with the SaslFeature. The SaslFeature will send the authentication request to the XMPP server.

To connect to the XMPP server with the SaslFeature, you need to call the connect_feature method before connecting to the XMPP server:

from osmxmpp.features.sasl import SaslFeature, PlainMechanism

client.connect_feature(
    SaslFeature(
        [
            PlainMechanism("john", "drowssap") # username and password
        ]
    ),
    XmppPermission.ALL
)

You can see the list of available authentication mechanisms in the SASL section.

Connecting to the XMPP server

To connect to the XMPP server, you need to call the connect method:

client.connect()

This will connect to the XMPP server and start the XMPP stream.

Note

The connect method is synchronous, so it will block the execution of the program until the connection is ended. To add functionality to the program when it’s connected, you can use handlers.

Example code

Here is an example code that connects to the XMPP server, and listens to the /test command. This example also uses the certifi package for getting the SSL certificate locations:

from osmxmpp.client import XmppClient
from osmxmpp.permission import XmppPermission
from osmxmpp.message import XmppMessage
from osmxmpp.features.tls import TlsFeature
from osmxmpp.features.sasl import SaslFeature, PlainMechanism

import certifi


client = XmppClient("jabber.org", port=5222)

@client.on_disconnect
def on_disconnect():
    print("Disconnected from the XMPP server")

@client.on_ready
def on_ready():
    print(f"Logged in as {client.jid}")

@client.on_message
def on_message(message):
    if message.body is None: #Messages body can be empty
        return

    if message.body == "/test":
        client.send_message(message.from_jid, "Hello!")

client.connect_feature(
    TlsFeature(
        verify_locations=certifi.where()
    ),
    TlsFeature.REQUIRED_PERMISSIONS
)

client.connect_feature(
    SaslFeature(
        [
            PlainMechanism("john", "drowssap") # username and password
        ]
    ),
    SaslFeature.REQUIRED_PERMISSIONS
)

client.connect_feature(
    BindFeature(
        "osmxmpp" # resource
    ),
    BindFeature.REQUIRED_PERMISSIONS
)

try:
    client.connect()
except KeyboardInterrupt:
    client.disconnect()