| 1 | # Matterbridge API |
| 2 | |
| 3 | If you'd like to develop your bridge in a different language than go, or if you |
| 4 | need to interface with a system which can only perform outgoing connections, |
| 5 | the matterbridge API is here. |
| 6 | |
| 7 | > [!TIP] |
| 8 | > For detailed information about API settings, see [settings.md](settings.md) |
| 9 | |
| 10 | ## OpenAPI specification |
| 11 | |
| 12 | Matterbridge API spec can be found on https://app.swaggerhub.com/apis-docs/matterbridge/matterbridge-api/0.1.0-oas3 |
| 13 | |
| 14 | ## Example discord/api gateway |
| 15 | |
| 16 | This example creates a gateway containing 2 bridges: discord, and api. |
| 17 | The API will listen on localhost port 4242. |
| 18 | |
| 19 | ### Configure matterbridge.toml |
| 20 | |
| 21 | This is based on the example in https://github.com/42wim/matterbridge/wiki/How-to-create-your-config |
| 22 | |
| 23 | 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}". |
| 24 | |
| 25 | ```toml |
| 26 | [api.myapi] |
| 27 | BindAddress="127.0.0.1:4242" |
| 28 | Buffer=1000 |
| 29 | RemoteNickFormat="{NICK}" |
| 30 | ``` |
| 31 | |
| 32 | Next we add the API gateway configuration, this make sure that we receive the messages from the other bridges and we can sent them. |
| 33 | |
| 34 | ```toml |
| 35 | [[gateway.inout]] |
| 36 | account="api.myapi" |
| 37 | channel="api" |
| 38 | ``` |
| 39 | |
| 40 | The full example |
| 41 | |
| 42 | ```toml |
| 43 | [discord.mydiscord] |
| 44 | Token="MTk4NjIyNDgzNDcdOTI1MjQ4.Cl2FMZ.ZnCjm1XVW7vRze4b7Cq4se7kKWs-abD" |
| 45 | Server="myserver" |
| 46 | |
| 47 | [api.myapi] |
| 48 | BindAddress="127.0.0.1:4242" |
| 49 | Buffer=1000 |
| 50 | RemoteNickFormat="{NICK}" |
| 51 | |
| 52 | [[gateway]] |
| 53 | name="gateway1" |
| 54 | enable=true |
| 55 | |
| 56 | [[gateway.inout]] |
| 57 | account="discord.mydiscord" |
| 58 | channel="general" |
| 59 | |
| 60 | [[gateway.inout]] |
| 61 | account="api.myapi" |
| 62 | channel="api" |
| 63 | ``` |
| 64 | |
| 65 | ### Get the messages from the buffer (GET /api/messages) |
| 66 | |
| 67 | If we now type a "test" message in our "general" channel on discord, we get the following result |
| 68 | |
| 69 | ```bash |
| 70 | $ curl http://localhost:4242/api/messages |
| 71 | ``` |
| 72 | |
| 73 | |
| 74 | ```json |
| 75 | [ |
| 76 | { |
| 77 | "text": "test", |
| 78 | "channel": "general", |
| 79 | "username": "wim", |
| 80 | "userid": "227183123686215680", |
| 81 | "avatar": "https://cdn.discordapp.com/avatars/227183947686215680/bd0e6c7fe63274597a4684884891b79d.jpg", |
| 82 | "account": "discord.mydiscord", |
| 83 | "event": "", |
| 84 | "protocol": "", |
| 85 | "gateway": "gateway1", |
| 86 | "parent_id": "", |
| 87 | "timestamp": "2019-01-09T22:37:18.647108348+01:00", |
| 88 | "id": "", |
| 89 | "Extra": null |
| 90 | } |
| 91 | ] |
| 92 | ``` |
| 93 | |
| 94 | 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 |
| 95 | |
| 96 | ```bash |
| 97 | $ curl http://localhost:4242/api/messages |
| 98 | ``` |
| 99 | |
| 100 | ```json |
| 101 | [] |
| 102 | ``` |
| 103 | |
| 104 | ### Stream messages (GET /api/stream) |
| 105 | |
| 106 | If we now type a "test" message in our "general" channel on discord, we get the following result |
| 107 | |
| 108 | ```bash |
| 109 | $ curl http://localhost:4242/api/stream |
| 110 | ``` |
| 111 | |
| 112 | ```json |
| 113 | {"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} |
| 114 | {"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} |
| 115 | ``` |
| 116 | |
| 117 | At connect you first get a `api_connected` event, then you'll get a http stream of json messages |
| 118 | |
| 119 | ### Send message (POST /api/message) |
| 120 | |
| 121 | We now post a `test` message from `randomuser` to the gateway `gateway1` |
| 122 | |
| 123 | The discord bridge will now receive this message. |
| 124 | |
| 125 | ```bash |
| 126 | curl -XPOST -H 'Content-Type: application/json' -d '{"text":"test","username":"randomuser","gateway":"gateway1"}' http://localhost:4242/api/message |
| 127 | ``` |
| 128 | |
| 129 | ```json |
| 130 | {"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} |
| 131 | ``` |
| 132 | |
| 133 | ## Security |
| 134 | You can also protect the API with a token by adding a `token` option to your api account configuration. |
| 135 | |
| 136 | ```toml |
| 137 | [api.myapi] |
| 138 | BindAddress="127.0.0.1:4242" |
| 139 | Buffer=1000 |
| 140 | RemoteNickFormat="{NICK}" |
| 141 | Token="verys3cret" |
| 142 | ``` |
| 143 | If you now want to sent a message with curl you'll have to add a `Authorization: Bearer <token>` header |
| 144 | |
| 145 | ```bash |
| 146 | curl -H "Authorization: Bearer verys3cret" http://localhost:4242/api/stream |
| 147 | ``` |
| 148 | |
| 149 | ## Projects using the API |
| 150 | |
| 151 | * [MatterLink](https://github.com/elytra/MatterLink) (Matterbridge link for Minecraft Server chat) |
| 152 | * [pyCord](https://github.com/NikkyAI/pyCord) (crossplatform chatbot) |
| 153 | * [Mattereddit](https://github.com/bonehurtingjuice/mattereddit) (Reddit chat support) |
| 154 | |
