XMPP Bot is a tiny little bot making the link between XMPP conversations and webhooks.
Find a file
2019-11-19 22:53:58 +01:00
docs Structure app by self-contained components 2019-10-18 22:42:04 +02:00
lib Close service when receiving XMPP error 2019-11-19 22:52:28 +01:00
test Close service when receiving XMPP error 2019-11-19 22:52:28 +01: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 Add coveralls CI 2019-10-20 17:58:18 +02:00
LICENSE.md First commit 2019-10-13 03:38:25 +02:00
package-lock.json Update dependencies 2019-11-19 22:53:58 +01:00
package.json Update dependencies 2019-11-19 22:53:58 +01:00
README.md Add coveralls CI 2019-10-20 17:58:18 +02:00

XMPP Bot

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.

Installation

  • 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/lib -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):

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

Configuration

Logger

  • 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

  • host and port define XMPP server
  • jid 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
      
      {
          "destination":"me@domain.ltd",
          "message":"Hi, there something wrong."
      }
      
    • send_xmpp_template will send template with merged variables (using JMESPath) to destination (user or room if sendToGroup set to true)

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

Credits

  • Nioc - Initial work

See also the list of contributors to this project.

This project is powered by the following components:

License

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