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
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}”.
Next we add the API gateway configuration, this make sure that we receive the messages from the other bridges and we can sent them.
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
[
{
"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
Stream messages (GET /api/stream)
If we now type a “test” message in our “general” channel on discord, we get the following result
{"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.
If you now want to sent a message with curl you’ll have to add a
Authorization: Bearer <token>
header
Projects using the API
- MatterLink (Matterbridge link for Minecraft Server chat)
- pyCord (crossplatform chatbot)
- Mattereddit (Reddit chat support)
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