node-red-contrib-matrixbot/docs

Visual bot creation using Node-RED

It's very easy to create simple interactions with a Matrix chatroom without programming. Discover Node-RED, a visual tool to wire together APIs. We have extended Node-RED with nodes to listen and talk in Matrix chatrooms.

How to install Node-RED

Node-RED is an open-source web application that is easy to deploy as a Docker container. You can deploy it locally on your computer using Docker. Or you can use any of the available online Docker hosting offers, such as sloppy.io or hyper_.

The custom Docker image which includes Node-RED plus additional nodes is available on our DockerHub repository

Install Node-RED on your local machine

First, install Docker if you haven't done it yet.

Then you just need to run:

    docker run -it -p 1880:1880 --name mynodered maski/node-red-docker

Let's dissect that command...

    docker run      - run this container... and build locally if necessary first.
    -it             - attach a terminal session so we can see what is going on
    -p 1880:1880    - connect local port 1880 to the exposed internal port 1880
    --name mynodered - give this machine a friendly local name
    maski/node-red-docker - the image to base it on

Running that command should give a terminal window with a running instance of Node-RED

    Welcome to Node-RED
    ===================
    8 Apr 12:13:44 - [info] Node-RED version: v0.14.5
    8 Apr 12:13:44 - [info] Node.js  version: v4.4.7
    .... etc

You can then browse to http://{host-ip}:1880 to get the familiar Node-RED desktop.

Install Node-RED on an online Docker hosting

A quick and easy way to host it online is to use Sloppy.io's 1-month free trial. Once you have created an account, go to the Dashboard and create a new project, a new service inside it, and an app within it using maski/node-red-docker as image path and pick a domain URI, such as my-node-red.sloppy.zone. Deploy the project, and you will have your own Node-RED server up and running at the selected URI.

How to use Node-RED

You can learn how to use Node-RED by following the Node-RED getting started guide. You can find additional tutorials here.

How to use the Matrix nodes in Node-RED

The package node-red-contrib-matrixbot, included in the abovementioned Docker image, adds 3 node types to the Node-RED palette (Matrix section, at the bottom):

• Matrix sender: sends messages from your Node-RED flow to the chatroom
• Matrix receiver: listens to messages in a chatroom and sends them to your Node-RED flow
• Matrix command: listens only to messages starting with a specific command and sends them to your Node-RED flow

All of these nodes require a Matrix Configuration with the following settings:

• User ID: the user ID in the matrix server, for instance @mybot:matrix.org
• Access token: the access token of the user in the matrix server
• Server URL: URL of the Matrix homeserver, e.g. https://matrix.org
• Room ID: ID of the chatroom to join when starting. If no room is specified, it will automatically join any room where it is invited

A simple application

We will create a simple application that will send messages to a chatroom whenever a RSS feed gets updated:

• First, invite the bot to the chatroom where it will be speaking and note the room ID.
• In Node-RED, pick the Feedparse node from the palette (you can filter by typing the first letters at the top) and drop it on the canvas
• Double-click on it to configure it and then enter a RSS feed, for instance http://rss.nytimes.com/services/xml/rss/nyt/World.xml. Give the node a name if you want and then click Done.
• Pick the Matrix sender node and drop it on the canvas. Link the output of the previous node to its input.
• Now double click on it and click on the pencil next to Connection to configure the Matrix settings. Follow the instructions described in the previous section.
• Once you're done, click the Deploy button at the top right corner and you're done!
• If you want to show also the link in the resulting message, try adding a function node in the middle with the following code:

var title = msg.article.title;
var link = msg.topic;
msg.payload = title + " \n" + link;
return msg;