Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nioc/xmpp-bot
XMPP Bot is a tiny little bot making the link between XMPP conversations and webhooks.
https://github.com/nioc/xmpp-bot
chatbot muc webhook webhook-server webhook-service xmpp xmpp-bot
Last synced: 2 months ago
JSON representation
XMPP Bot is a tiny little bot making the link between XMPP conversations and webhooks.
- Host: GitHub
- URL: https://github.com/nioc/xmpp-bot
- Owner: nioc
- License: agpl-3.0
- Created: 2019-10-13T01:46:08.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-09T08:31:35.000Z (almost 2 years ago)
- Last Synced: 2024-10-11T01:45:14.222Z (3 months ago)
- Topics: chatbot, muc, webhook, webhook-server, webhook-service, xmpp, xmpp-bot
- Language: JavaScript
- Size: 313 KB
- Stars: 23
- Watchers: 5
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# XMPP Bot
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://github.com/nioc/xmpp-bot/releases/latest)
[](https://app.travis-ci.com/github/nioc/xmpp-bot)
[](https://coveralls.io/github/nioc/xmpp-bot?branch=master)
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
An [Ansible role](/docs/ansible/xmpp-bot/README.md) is provided, but you can also use following commands:
- Install [Node.js](https://nodejs.org/):
```shell
curl -sL https://deb.nodesource.com/setup_10.x | bash -
apt-get install -y nodejs
```
- Install npm:
```shell
npm install npm@latest -g
```
- Clone repository:
```shell
git clone https://github.com/nioc/xmpp-bot.git /usr/local/bin/xmpp-bot/
```
- Install dependency:
```shell
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](#configuration) in `/lib/config/config.json` (you can copy `config.json.dist`)
- Add systemd service from [model](/docs/xmpp-bot.service):
```shell
cp docs/xmpp-bot.service /etc/systemd/system/xmpp-bot.service
```
- Update systemd:
```shell
systemctl daemon-reload
```
- Start service:
```shell
systemctl start xmpp-bot
```
- Start service at boot:
```shell
systemctl enable xmpp-bot
```
- Add fail2ban filter from [model](/docs/xmpp-bot.conf) (optionnal):
```shell
cp docs/xmpp-bot.conf /etc/fail2ban/filter.d/xmpp-bot.conf
```
Add the jail (`/etc/fail2ban/jail.local`):
```properties
[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](https://log4js-node.github.io/log4js-node/appenders.html))
### 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:
```http
POST /webhooks/w1 HTTP/1.1
Host: domain.ltd:8000
Content-Type: application/json
Authorization: Basic dXNlcjE6cGFzczE=
Content-Length: 70
{
"destination":"[email protected]",
"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
## FAQ
- *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.
## Credits
- **[Nioc](https://github.com/nioc/)** - _Initial work_
See also the list of [contributors](https://github.com/nioc/xmpp-bot/contributors) to this project.
This project is powered by the following components:
- [xmpp.js](https://github.com/simple-xmpp/node-simple-xmpp) (ISC)
- [express](https://github.com/expressjs/express) (MIT)
- [body-parser](https://github.com/expressjs/body-parser) (MIT)
- [express-basic-auth](https://github.com/LionC/express-basic-auth) (MIT)
- [morgan](https://github.com/expressjs/morgan) (MIT)
- [jmespath.js](https://github.com/jmespath/jmespath.js) (Apache-2.0)
- [request](https://github.com/request/request) (Apache-2.0)
- [node-cleanup](https://github.com/jtlapp/node-cleanup) (MIT)
- [log4js-node](https://github.com/log4js-node/log4js-node) (Apache-2.0)
## License
This project is licensed under the GNU Affero General Public License v3.0 - see the [LICENSE](LICENSE.md) file for details