https://github.com/morzan1001/mattermost-plugin-opentalk
Mattermost plugin for OpenTalk video conferencing. Start meetings from any channel or DM with Keycloak/OIDC auth and a Calls-style in-app UX. Replaces external tabs with a native conferencing experience – audio, video, screenshare, dial-in.
https://github.com/morzan1001/mattermost-plugin-opentalk
mattermost mattermost-plugin
Last synced: 24 days ago
JSON representation
Mattermost plugin for OpenTalk video conferencing. Start meetings from any channel or DM with Keycloak/OIDC auth and a Calls-style in-app UX. Replaces external tabs with a native conferencing experience – audio, video, screenshare, dial-in.
- Host: GitHub
- URL: https://github.com/morzan1001/mattermost-plugin-opentalk
- Owner: morzan1001
- License: apache-2.0
- Created: 2026-05-05T18:59:07.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-17T13:34:30.000Z (about 1 month ago)
- Last Synced: 2026-05-17T15:46:32.849Z (30 days ago)
- Topics: mattermost, mattermost-plugin
- Language: TypeScript
- Homepage:
- Size: 1.09 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenTalk for Mattermost
A Mattermost server plugin that deeply integrates the OpenTalk video-conferencing platform into the Mattermost web app. Audio, video, and screen sharing from channels and DMs — similar to `mattermost-plugin-calls` — but backed by OpenTalk's stack (Roomserver + LiveKit) instead of a custom WebRTC server.
## Features
- Start a meeting from any channel via header button or `/opentalk start`. Floating widget with mic, camera, screen-share, hand-raise, mini, and leave controls — drag to reposition, resizes to its natural content width.
- Expanded view with three layouts (speaker, grid, screen-focus); choice persists per user.
- DM ringing — incoming-call modal with ringtone, 30-second auto-decline; switch-call prompt when already in a meeting; push notification per recipient (DND respected).
- Mobile handoff — meeting posts carry a Slack-style card with a `[Join]` markdown link, dial-in info, and End / Decline action buttons. Mattermost mobile users tap to open the OpenTalk web client in the system browser.
- Native screen-share in Mattermost Desktop via the platform's `desktopAPI.getDesktopSources()` IPC; standard `getDisplayMedia()` in browsers.
- End-for-all kicks remaining participants (moderation `debrief`) and revokes the OpenTalk invite.
- Channel toast above the thread when a meeting is live in a public/private channel.
- User settings: ringtone toggle, mute-on-join, mic and camera pickers.
- Custom status "In OpenTalk-Meeting" while connected.
- German + English UI, auto-selected from the user's Mattermost locale.
## Architecture
- **Server (Go):** OAuth bridge against Keycloak, calls the OpenTalk Controller REST API on behalf of the user, posts custom posts with a join link and action buttons, sends push notifications for DM ringing, runs a reaper that ends orphaned meetings (heartbeat-based for webapp hosts, 30-minute grace for mobile-only hosts).
- **Webapp (TS + React):** Channel-header button, custom post renderer, floating widget, expanded view, incoming-call modal, signaling client, and LiveKit client for the in-Mattermost conference UI.
- **OpenTalk:** Room creation and auth via the Controller REST API, live signaling over Roomserver WebSocket, media over LiveKit.
- **Auth:** Per-user OIDC authorization-code flow against Keycloak (the same realm that OpenTalk uses).
## Build
Prerequisites:
- Go ≥ 1.25 (version pinned in `.go-version`; recommended: `goenv`)
- Node ≥ 24 (version pinned in `.nvmrc`; recommended: `nvm`)
- GNU Make
```bash
make dist
```
This produces `dist/com.github.morzan1001.mattermost-plugin-opentalk-.tar.gz`. Upload it in the Mattermost System Console under **Plugin Management → Upload Plugin**.
## Keycloak setup
The plugin authenticates each Mattermost user via an **OIDC authorization-code flow** against the same Keycloak instance that OpenTalk uses. You need to create one **OIDC client** in the Keycloak realm of your OpenTalk deployment.
> **Permissions required:** Realm-admin access. If you don't have it, forward this section to your OpenTalk operator.
### What the client does
- Receives user browser redirects from the Mattermost plugin and issues OIDC auth codes.
- Exchanges auth codes for access/refresh tokens (authenticated with a client secret).
- Issues refresh tokens (via the `offline_access` scope) so the plugin can renew tokens without prompting the user again.
### 1. Log in to the Keycloak Admin Console
Open `https://accounts./auth/admin/`. Select the OpenTalk realm from the top-left dropdown (typically `opentalk`).
### 2. Create the client
Left nav: **Clients → Create client**.
**General Settings:** Client type **OpenID Connect**, Client ID `mattermost-plugin-opentalk`, Name `Mattermost OpenTalk Plugin`.
**Capability Config:** Enable **Client authentication** (confidential client with client secret) and **Standard flow** (authorization-code flow). Optionally enable **Service accounts roles** for the bot-model fallback. Leave the rest off.
**Login Settings:**
Replace `MM_URL` with your Mattermost server URL (e.g. `http://localhost:8065` for local dev or `https://chat.example.com` for production):
| Field | Value |
|---|---|
| Root URL | `MM_URL` |
| Home URL | `MM_URL` |
| Valid redirect URIs | `MM_URL/plugins/com.github.morzan1001.mattermost-plugin-opentalk/oauth/callback` |
| Valid post logout redirect URIs | `MM_URL/*` |
| Web origins | `MM_URL` (the exact Mattermost URL — no wildcard `*`) |
Save.
### 3. Copy the client secret
Go to the **Credentials** tab and copy the **Client secret**. You will enter this value in the Mattermost System Console plugin settings (field: _OIDC Client Secret_).
### 4. (Optional) Refresh token lifetime
If your realm enforces strict token lifetimes, check **Realm settings → Tokens** and ensure _SSO Session Idle_ and _Offline Session Idle_ are long enough that refresh tokens do not expire after 30 minutes. The default is usually fine.
### Plugin settings
After creating the client, enter the following in the Mattermost System Console (**System Console → Plugins → OpenTalk**):
| Plugin setting | Value |
|---|---|
| OpenTalk Controller URL | URL of your OpenTalk Controller, e.g. `https://controller.opentalk.example` |
| OpenTalk Frontend URL | URL of the OpenTalk frontend, e.g. `https://opentalk.example` |
| OIDC Authority | Issuer URL, e.g. `https://accounts.opentalk.example/auth/realms/opentalk` |
| OIDC Client ID | `mattermost-plugin-opentalk` |
| OIDC Client Secret | _Value from step 3_ |
| OIDC Scopes | `openid email profile offline_access` (default is fine) |
Activate the plugin. An OpenTalk button should appear in the channel header; the first click starts the OAuth flow.
### Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| `unauthorized_client` during smoke test | Direct access grants not enabled | Enable in Capability Config (step 2) |
| `invalid_grant` + `Account is not fully set up` | Test user has pending required actions (e.g. Verify Email, Update Profile) | User details → clear _Required user actions_, set _Email verified_, fill in first/last/email |
| `invalid_grant` (no account message) | Wrong username or password | Check the user's credentials |
| `invalid_client` | Client authentication is `off` (public client) | Enable in Capability Config (step 2) |
| Browser redirect lands on Keycloak error page | Redirect URI mismatch | Check Login Settings exactly — no trailing slash |
| Plugin settings save fails with `OIDCAuthority must not be empty` | Issuer URL not entered | See plugin settings table above |
| Plugin cannot load OIDC discovery | Issuer URL has wrong subpath (`/auth/` missing or extra) | Use exactly the URL shown in Keycloak's Realm Settings as _Issuer_ |
## Slash commands
| Command | What it does |
|---|---|
| `/opentalk connect` | Link the current Mattermost user to OpenTalk via OIDC. |
| `/opentalk disconnect` | Remove the link. |
| `/opentalk info` | Show the current connection status. |
| `/opentalk start` | Start a meeting in the current channel. |
| `/opentalk join` | Join the active meeting in the current channel. |
| `/opentalk end` | End the meeting (host only). |
| `/opentalk dial-in` | Show the SIP dial-in number and PIN for the active meeting. |
| `/opentalk ring on\|off` | Toggle the ringtone for incoming DM calls. |
| `/opentalk help` | Show the command list. |
## Development
```bash
make deploy
```
Deploys directly to a local Mattermost dev server (endpoint configured via `MM_SERVICESETTINGS_SITEURL` + admin token).
```bash
make test # go test + jest
make lint # golangci-lint + eslint
make watch # webapp in watch mode
```
The webapp suite covers components, store slices, conference signaling, and the LiveKit wrapper; the server suite covers slash-command handlers, the OIDC flow, the OpenTalk client, the post helpers, the reaper, and the store.
## Credits
The incoming-call ringtone is ["Digital Phone Ring" by Perkin](https://freesound.org/people/Perkin/sounds/178377/), released under CC0 1.0.
## License
Three licenses apply, identified per file via SPDX headers; full texts are in [`LICENSES/`](LICENSES/):
- **Apache-2.0** — plugin code authored in this repository (default).
- **EUPL-1.2** — files under `webapp/src/conference/signaling/` ported from the OpenTalk web frontend; each carries an SPDX header crediting OpenTalk GmbH.
- **CC0-1.0** — `webapp/src/sounds/incoming_call.ogg`, declared via the adjacent `.license` sidecar.
The top-level [`LICENSE`](LICENSE) file (Apache-2.0) is preserved at the root so GitHub auto-detection works.