XMPP Bot is a tiny little bot making the link between XMPP conversations and webhooks.
Go to file
nioc e9861aaa16 Fix Travis CI badge 2022-09-28 02:23:03 +02:00
.github/ISSUE_TEMPLATE Update issue templates 2019-11-22 01:04:24 +01:00
docs Add Ansible role 2020-01-19 23:20:03 +01:00
lib Version 2.2.0 2022-09-28 01:18:01 +02:00
test Version 2.2.0 2022-09-28 01:18:01 +02:00
.eslintrc.json Add XMPP test 2019-10-20 03:01:59 +02:00
.gitignore Structure app by self-contained components 2019-10-18 22:42:04 +02:00
.travis.yml Update Travis CI distribution 2022-09-28 02:10:29 +02:00
LICENSE.md First commit 2019-10-13 03:38:25 +02:00
README.md Fix Travis CI badge 2022-09-28 02:23:03 +02:00
package-lock.json Version 2.2.0 2022-09-28 01:18:01 +02:00
package.json Version 2.2.0 2022-09-28 01:18:01 +02:00



license: AGPLv3 GitHub release Build Status Coverage Status

XMPP Bot is a tiny little bot making the link between XMPP conversations and webhooks.

User ⇄ XMPP client ⇄ XMPP Server ⇄ XMPP Bot ⇄ REST API

Key features

  • Call outgoing webhook on XMPP incoming messages from user chat or group chat (Multi-user chat "MUC"),
  • Send message templates (with values to apply to variables in that template) to user or room (MUC) on incoming authorized (basic or bearer) webhook.


An Ansible role is provided, but you can also use following commands:

  • Install Node.js:

    curl -sL https://deb.nodesource.com/setup_10.x | bash -
    apt-get install -y nodejs
  • Install npm:

    npm install npm@latest -g
  • Clone repository:

    git clone https://github.com/nioc/xmpp-bot.git /usr/local/bin/xmpp-bot/
  • Install dependency:

    cd /usr/local/bin/xmpp-bot/ && npm install --production
  • Create run user (optionnal):

    useradd -r -s /bin/false xmpp-bot
    chown xmpp-bot:xmpp-bot /usr/local/bin/xmpp-bot -R
  • Set configuration in /lib/config/config.json (you can copy config.json.dist)

  • Add systemd service from model:

    cp docs/xmpp-bot.service /etc/systemd/system/xmpp-bot.service
  • Update systemd:

    systemctl daemon-reload
  • Start service:

    systemctl start xmpp-bot
  • Start service at boot:

    systemctl enable xmpp-bot
  • Add fail2ban filter from model (optionnal):

    cp docs/xmpp-bot.conf /etc/fail2ban/filter.d/xmpp-bot.conf

    Add the jail (/etc/fail2ban/jail.local):

    enabled  = true
    port     = http,https
    filter   = xmpp-bot
    logpath  = /var/log/xmpp-bot/webhook.log
    maxretry = 3
    bantime  = 21600 ; 6 hours



  • level log4js level (all < trace < debug < info < warn < error < fatal < mark < off)
  • file, console and stdout define log appenders (see log4js doc)

Webhooks listener

  • path and port define the listening endpoint
  • ssl define key and certificat location and port used for exposing in https, make sure that user of the process is allowed to read cert
  • users is an array of user/password for basic authentication
  • accessLog define the listener logger

XMPP Server

  • service and domain define XMPP server
  • username and password define XMPP "bot" user credentials
  • rooms list rooms (and optionnal password) where bot will listen

Incoming webhooks (list)

  • path is the webhook key:a POST request on this path will trigger corresponding action
  • action among enumeration:
    • send_xmpp_message will send message (message in request body) to destination (from request body) ; if destination is found in config.xmppServer.rooms array, message will send as a groupchat). Request exemple:

      POST /webhooks/w1 HTTP/1.1
      Host: domain.ltd:8000
      Content-Type: application/json
      Authorization: Basic dXNlcjE6cGFzczE=
      Content-Length: 70
          "message":"Hi, there something wrong."
    • send_xmpp_template will send template with merged variables (using JMESPath) to destination (user or room if type set to chat or groupchat)

XMPP hooks (list)

  • room is the XMPP hook key: an incoming groupchat (or chat) from this room (or this user) will trigger corresponding action
  • action among enumeration:
    • outgoing_webhook will execute a request to corresponding webhook with args as webhook code


  • XMPP server is using a self signed certificate, how can i run service? You can allow insecure TLS connections and HTTPS requests by adding Environment=NODE_TLS_REJECT_UNAUTHORIZED=0 in /usr/lib/systemd/system/xmpp-bot.service.


  • Nioc - Initial work

See also the list of contributors to this project.

This project is powered by the following components:


This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details