matterbridge

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

OpenAPI specification
Example discord/gitter/api gateway
Security
Projects using the API

OpenAPI specification

Matterbridge API spec can be found on https://app.swaggerhub.com/apis-docs/matterbridge/matterbridge-api/0.1.0-oas3

Example discord/gitter/api gateway

This example creates a gateway containing 3 bridges: discord,gitter and api.
The API will listen on localhost port 4242.

Configure matterbridge.toml

This is based on the example in https://github.com/42wim/matterbridge/wiki/How-to-create-your-config

We first add the API account configuration to this example, this makes the API listen on localhost port 4242 with a buffer of 1000 messages and the nicks we receive will look like “{nick}”.

[api.myapi]
BindAddress="127.0.0.1:4242"
Buffer=1000
RemoteNickFormat="{NICK}"

Next we add the API gateway configuration, this make sure that we receive the messages from the other bridges and we can sent them.

[[gateway.inout]]
account="api.myapi"
channel="api"

The full example

[discord.mydiscord]
Token="MTk4NjIyNDgzNDcdOTI1MjQ4.Cl2FMZ.ZnCjm1XVW7vRze4b7Cq4se7kKWs-abD"
Server="myserver"

[gitter.mygitter]
Token="319fda1761c6875739a489b6772daf2ace4b95d0"

[api.myapi]
BindAddress="127.0.0.1:4242"
Buffer=1000
RemoteNickFormat="{NICK}"

[[gateway]]
name="gateway1"
enable=true

[[gateway.inout]]
account="discord.mydiscord"
channel="general"

[[gateway.inout]]
account="gitter.mygitter"
channel="42wim/mygreatproject"

[[gateway.inout]]
account="api.myapi"
channel="api"

Get the messages from the buffer (GET /api/messages)

If we now type a “test” message in our “general” channel on discord, we get the following result

$ curl http://localhost:4242/api/messages

[
 {
  "text": "test",
  "channel": "general",
  "username": "wim",
  "userid": "227183123686215680",
  "avatar": "https://cdn.discordapp.com/avatars/227183947686215680/bd0e6c7fe63274597a4684884891b79d.jpg",
  "account": "discord.mydiscord",
  "event": "",
  "protocol": "",
  "gateway": "gateway1",
  "parent_id": "",
  "timestamp": "2019-01-09T22:37:18.647108348+01:00",
  "id": "",
  "Extra": null
 }
]

After we got this message (and we didn’t type anything else), the buffer will be empty and doing a curl will now give an empty result

$ curl http://localhost:4242/api/messages

[]

Stream messages (GET /api/stream)

If we now type a “test” message in our “general” channel on discord, we get the following result

$ curl http://localhost:4242/api/stream

{"text":"","channel":"","username":"","userid":"","avatar":"","account":"","event":"api_connected","protocol":"","gateway":"","parent_id":"","timestamp":"2019-01-09T22:48:33.398737344+01:00","id":"","Extra":null}
{"text":"test","channel":"general","username":"wim","userid":"227183123686215680","avatar":"https://cdn.discordapp.com/avatars/227183947686215680/bd0e6c7fe63274597a4684884891b79d.jpg","account":"discord.mydiscord","event":"","protocol":"","gateway":"gateway1","parent_id":"","timestamp":"2019-01-09T22:48:42.506629373+01:00","id":"","Extra":null}

At connect you first get a api_connected event, then you’ll get a http stream of json messages

Send message (POST /api/message)

We now post a test message from randomuser to the gateway gateway1

Every bridge on the gateway (gitter and discord) will now receive this message.

curl -XPOST -H 'Content-Type: application/json'  -d '{"text":"test","username":"randomuser","gateway":"gateway1"}' http://localhost:4242/api/message

{"text":"test","channel":"api","username":"randomuser","userid":"","avatar":"","account":"api.local","event":"","protocol":"api","gateway":"gateway1","parent_id":"","timestamp":"2019-01-09T22:53:51.618575236+01:00","id":"","Extra":null}

Security

You can also protect the API with a token by adding a token option to your api account configuration.

[api.myapi]
BindAddress="127.0.0.1:4242"
Buffer=1000
RemoteNickFormat="{NICK}"
Token="verys3cret"

If you now want to sent a message with curl you’ll have to add a Authorization: Bearer <token> header

curl -H "Authorization: Bearer verys3cret" http://localhost:4242/api/stream

Projects using the API

MatterLink (Matterbridge link for Minecraft Server chat)
pyCord (crossplatform chatbot)
Mattereddit (Reddit chat support)

Home
Features
FAQ
Settings

Getting started
How to create your config
Discord bot setup
Slack bot setup
MS Teams setup

Deploy
DigitalOcean
Azure
Docker
Heroku

Gateways
Config: basic
Config: channel rules
Discord
Gitter
Hipchat
IRC
Keybase
Matrix
Mattermost
Microsoft Teams
Mumble
Nextcloud Talk
RocketChat
Slack
Sshchat
Steam
Telegram
Twitch
VK
WhatsApp
XMPP
Zulip

Advanced
Mediaserver setup
Service files

Developer
API
Tengo scripting
Making gateways