> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Mattermost

> Client-mode REST API connector for a curated Mattermost API v4 slice: create posts, execute incoming webhooks, plus users/me smoke, system ping, and get channel

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Mattermost API v4](https://docs.mattermost.com/api/):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST posts | `POST /api/v4/posts` | Bearer PAT; body `channel_id` + `message` |
| POST webhook URL | `POST /hooks/{hook_id}` | Incoming webhook; path credentials; JSON `text` |
| GET users/me (smoke) | `GET /api/v4/users/me` | PAT credential check |
| GET system/ping | `GET /api/v4/system/ping` | Liveness (often unauthenticated) |
| GET channels/\{id} | `GET /api/v4/channels/{channel_id}` | Channel lookup |

Default `BASE_ADDRESS` is `https://YOUR_MATTERMOST_HOST` (site origin — **not** including `/api/v4`). Topics use `messaging/mattermost/<object>/<verb>`.

Outgoing webhooks and slash commands that Mattermost POSTs to your infrastructure need a companion `ENABLE_SERVER` connector (document only here).

> [!NOTE]
>
> REST v4 methods send `Authorization: Bearer {token}` (personal access token). Incoming webhook execute uses **only** the hook id in the path — do not send a Bearer header on that event. Prefer Hub secrets (`MATTERMOST_TOKEN`, and site origin via `MATTERMOST_BASE_URL` / `MATTERMOST_HOST`). Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Mattermost API v4
# Auth: Bearer {value.json.token} on REST; webhook path credentials on Executeincomingwebhook
# BASE_ADDRESS: https://YOUR_MATTERMOST_HOST

DEFINE ROUTE MattermostRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_MATTERMOST_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getusersme
        WITH SOURCE_TOPIC "messaging/mattermost/user/get-me"
        WITH DESTINATION_TOPIC "messaging/mattermost/user/get-me/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT Systemping
        WITH SOURCE_TOPIC "messaging/mattermost/system/ping"
        WITH DESTINATION_TOPIC "messaging/mattermost/system/ping/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/system/ping"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Createpost
        WITH SOURCE_TOPIC "messaging/mattermost/post/create"
        WITH DESTINATION_TOPIC "messaging/mattermost/post/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v4/posts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Executeincomingwebhook
        WITH SOURCE_TOPIC "messaging/mattermost/webhook/incoming"
        WITH DESTINATION_TOPIC "messaging/mattermost/webhook/incoming/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/hooks/{value.json.hook_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Getchannel
        WITH SOURCE_TOPIC "messaging/mattermost/channel/get"
        WITH DESTINATION_TOPIC "messaging/mattermost/channel/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/channels/{value.json.channel_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getusersme | GET | `/api/v4/users/me` | `messaging/mattermost/user/get-me` | `messaging/mattermost/user/get-me/response` |
| Systemping | GET | `/api/v4/system/ping` | `messaging/mattermost/system/ping` | `messaging/mattermost/system/ping/response` |
| Createpost | POST | `/api/v4/posts` | `messaging/mattermost/post/create` | `messaging/mattermost/post/create/response` |
| Executeincomingwebhook | POST | `/hooks/{hook_id}` | `messaging/mattermost/webhook/incoming` | `messaging/mattermost/webhook/incoming/response` |
| Getchannel | GET | `/api/v4/channels/{channel_id}` | `messaging/mattermost/channel/get` | `messaging/mattermost/channel/get/response` |

## Auth

1. On your Mattermost server, create a **personal access token** for a lab user with `create_post` (and related) permissions. Copy the token once.
2. Set connector `BASE_ADDRESS` to the **site origin** (e.g. `https://mattermost.example.com`) — do **not** append `/api/v4`.
3. For REST events, pass `token` on the MQTT payload so `Authorization: Bearer {value.json.token}` resolves.
4. For incoming webhooks, create an Incoming Webhook in Mattermost Integrations and pass `hook_id` (the id segment after `/hooks/`); do **not** send a Bearer header on Executeincomingwebhook.
5. Store secrets in Hub / `GET SECRET "MATTERMOST_TOKEN"`. Optional site URL secrets: `MATTERMOST_BASE_URL` or `MATTERMOST_HOST`. Never commit real credentials.
6. Successful `GET /api/v4/users/me` returns **HTTP 200** with a user JSON object. `POST /api/v4/posts` returns **201**. Incoming webhook execute typically returns **200** with body `ok`.

## Example payloads

**getUsersMe:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_MATTERMOST_PERSONAL_ACCESS_TOKEN"
}
```

**createPost:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_MATTERMOST_PERSONAL_ACCESS_TOKEN",
  "channel_id": "CHANNEL_ID",
  "message": "Coreflux alarm: vibration above threshold — Zone A"
}
```

**executeIncomingWebhook:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "hook_id": "YOUR_INCOMING_WEBHOOK_ID",
  "text": "#### Coreflux smoke\nLine 3 stopped",
  "channel": "town-square",
  "username": "coreflux-bot"
}
```

**systemPing:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{}
```

**getChannel:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_MATTERMOST_PERSONAL_ACCESS_TOKEN",
  "channel_id": "CHANNEL_ID"
}
```

## Deploy notes

* Deployable file: `MattermostRestApi.lot` — **no** `ADD METADATA`.
* Hub sidecar: `hub-metadata.lot` with `WITH STATUS "beta"`, `WITH CATEGORY "REST API Routes"`, and `WITH DOCLINK` to this page.
* Suggested branches: `feat/rest-api-route-mattermost` (broker examples) and `feat/docs-rest-api-mattermost` (Mintlify). Hugo owns GitHub pushes.

## References

* [Mattermost API](https://docs.mattermost.com/api/)
* [API reference / authentication](https://docs.mattermost.com/api/reference/mattermost-api)
* [Incoming webhooks](https://docs.mattermost.com/developers/integrate/webhooks/incoming/)
* [OpenAPI source](https://github.com/mattermost/mattermost/tree/master/api/v4/source)
* [REST API Connectors (base)](/latest/lot-language/routes/rest-api-routes)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.