Metadata-Version: 1.1
Name: xmppwb
Version: 0.2.2
Summary: XMPP Webhook Bridge
Home-page: https://github.com/saqura/xmppwb
Author: saqura
Author-email: saqura@saqura.xyz
License: MIT
Description: ****************************
        xmppwb - XMPP Webhook Bridge
        ****************************
        
        *Note that xmppwb is currently in early development and may contain bugs.*
        
        A bot that bridges XMPP (chats and MUCs) with webhooks, thus making it possible to interact with services outside the XMPP world. This can be used to connect XMPP to other chat services that provide a webhook API (for example `Rocket.Chat`_ or `Mattermost`_).
        
        .. contents::
           :local:
           :depth: 2
           :backlinks: none
        
        =======
        Install
        =======
        
        ``xmppwb`` requires *Python 3.5+* and can be installed using pip3:
        
        .. code-block:: bash
        
            $ pip3 install --upgrade xmppwb
        
        
        which will automatically install the dependencies (*aiohttp*, *pyyaml* and *slixmpp*).
        
        =============
        Configuration
        =============
        
        A documented example config is provided in ``example.conf``. A simple config file looks like this (the ``<placeholders>`` need to be changed):
        
        .. code-block:: yaml
        
            xmpp:
              # This JID must exist.
              jid: <alice@example.com>
              password: "<bot-password>"
              # Define all MUCs that should be available to the bridges defined later.
              mucs:
                - jid: <conference1@conference.example.com>
                  nickname: <nickname>
                  # password: "<muc-password>"
            incoming_webhook_listener:
              bind_address: "127.0.0.1"
              port: 5000
            bridges:
              - xmpp:
                  - muc: <conference1@conference.example.com>
                  - relay_all_normal: true
                webhooks:
                  outgoing:
                    - url: <incoming-webhook-url-from-other-end>
                      override_username: "{nick}"
                  incoming:
                    - token: <outgoing-webhook-token-from-other-end>
        
        
        **Note that the password is stored in cleartext, so take precautions such as restricting file permissions. It is recommended to use a dedicated JID for this bridge.**
        
        The terminology ``incoming`` and ``outgoing`` in the config file refers to webhooks from the perspective of this bridge. The webhooks must also be defined on the other end (Rocket.Chat and Mattermost provide a UI for this, for example). An *outgoing webhook in Rocket.Chat* must be set up in the *incoming webhooks section in this bridge* and vice versa.
        
        ----------------------------
        Integrating with Rocket.Chat
        ----------------------------
        
        An example config for bridging XMPP with `Rocket.Chat`_ is provided in ``rocketchat.example.conf``. It is recommended to copy it and fill out all ``<placeholders>``.
        
        1. To create the corresponding webhooks in RocketChat, go to *Administration->Integrations* and create a new incoming webhook. Here you can select the channel that you want to bridge with.
        2. After saving, a webhook URL will be generated. Copy it and fill it into the ``<incoming-webhook-url-from-rocketchat>`` placeholder in the config file.
        3. Now create an outgoing webhook. The URL is of the form ``http://{bind_adress}:{port}/`` and depends on your settings in the ``incoming_webhook_listener`` section. It defaults to ``http://127.0.0.1:5000/``.
        4. Copy the token and fill it into the ``<outgoing-webhook-token-from-rocketchat>`` placeholder.
        5. After having filled out all other placeholders, the bridge is ready to run (see `usage`_).
        
        
        =====
        Usage
        =====
        *This bridge is meant to run on the same server as the application you are bridging with, as it currently uses HTTP for incoming webhooks.*
        
        To run the bridge:
        
        .. code-block:: bash
        
            $ xmppwb --config configfile.conf
        
        
        or:
        
        .. code-block:: bash
        
            $ python3 -m xmppwb --config configfile.conf
        
        Synopsis:
        
        .. code-block:: bash
        
            $ xmppwb [-h] [-v] --config CONFIG
        
        See also ``xmppwb --help``.
        
        
        
        .. _Rocket.Chat: https://rocket.chat/
        .. _Mattermost: https://about.mattermost.com
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Communications :: Chat
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.5
