Mattermost

봇 토큰 아웃바운드 및 outgoing webhook 인바운드를 사용하는 셀프 호스팅 Mattermost. 인바운드는 공개 채널만 지원합니다.

🟡 아웃바운드는 즉시 사용 가능하며, 인바운드는 outgoing webhook을 통한 공개 채널만 지원합니다. 가장 간편한 연동 방법입니다. DM 및 비공개 채널을 지원하는 Mattermost WebSocket 봇 모드는 향후 추가될 예정입니다.

제공 기능

아웃바운드 텍스트: 봇 개인 액세스 토큰을 사용해 POST /api/v4/posts로 메시지를 전송합니다. root_id를 통한 스레드 답글도 지원됩니다.
인바운드 outgoing webhook: /webhooks/mattermost 엔드포인트를 제공합니다. 설정된 트리거 단어가 공개 채널에 입력되면 Mattermost가 해당 webhook URL로 POST 요청을 전송합니다.
현재 PR에서는 텍스트만 지원합니다. Mattermost Files API를 통한 파일 업로드 및 첨부 파일 파싱은 이후 버전에서 제공될 예정입니다.
16383자 텍스트 제한 (Mattermost 기본값 PostMessageMaxRunes).

설정

1. 봇 계정 생성

Mattermost에 시스템 관리자로 로그인합니다.
System Console → "Integrations" → "Bot Accounts"로 이동해 "Add Bot Account"를 선택합니다.
사용자 이름(예: minara), 표시 이름, 선택적으로 아바타를 설정합니다. 저장하면 Mattermost가 Bot Personal Access Token을 표시합니다. 이 토큰은 이후 다시 확인할 수 없으므로 반드시 저장해 두십시오.
대상 채널에 봇을 초대합니다. 채널 입력창에서 /invite @minara를 입력하십시오.

2. Outgoing webhook 설정 (인바운드용, 선택 사항)

같은 화면에서 "Integrations" → "Outgoing Webhooks"로 이동해 "Add Outgoing Webhook"을 선택합니다.
다음 항목을 설정합니다.
- Channel: webhook이 수신할 공개 채널
- Trigger words: 예: @bot, !minara (Mattermost는 메시지가 해당 트리거 단어 중 하나로 시작할 때만 webhook을 실행합니다.)
- Callback URLs: https://<your-host>/webhooks/mattermost
저장 후 생성된 Token을 복사합니다. 이 값이 MATTERMOST_OUTGOING_WEBHOOK_TOKEN이 됩니다.

3. Minara 설정

minara auth messaging add
# 목록에서 `mattermost`를 선택합니다.

또는 환경 변수를 직접 설정합니다.

MATTERMOST_URL=https://mattermost.example.com
MATTERMOST_BOT_TOKEN=<personal access token>
MATTERMOST_DEFAULT_CHANNEL_ID=<Channel URL에서 확인한 채널 ID>
MATTERMOST_OUTGOING_WEBHOOK_TOKEN=<outgoing webhook 토큰>

채널 ID는 채널을 열었을 때 URL에서 확인할 수 있습니다. https://mattermost.example.com/team/channels/<id>에서 <id> 슬러그가 채널 ID입니다.

4. 테스트

minara auth messaging test mattermost

인바운드 webhook

Mattermost의 outgoing webhook은 /webhooks/mattermost로 application/x-www-form-urlencoded 형식의 POST 요청을 전송하며, 다음 필드가 포함됩니다.

token=<webhook token>
channel_id=<channel id>
user_id=<user id>
user_name=<username>
text=<the user's message>
post_id=<message id>
trigger_word=<matched trigger>
from_webhook=false

Minara는 token 필드를 MATTERMOST_OUTGOING_WEBHOOK_TOKEN과 상수 시간 비교(constant-time compare)로 검증합니다. from_webhook === "true" 플래그는 봇 자신의 게시물이 트리거를 통해 다시 수신되는 자기 루프를 필터링합니다.

제한 사항 및 주의 사항

Outgoing webhook은 공개 채널에서만 동작합니다. 비공개 채널과 DM은 WebSocket 봇 경로가 필요하며 현재 개발 예정입니다. 활성화가 잦은 채널에서 Agent가 과부하를 받지 않도록 트리거 단어를 신중하게 설정하십시오.
트리거 단어는 메시지 앞부분에서만 매칭됩니다. Mattermost는 메시지의 시작 부분에서만 트리거를 인식합니다. @bot hello는 동작하지만, hello @bot은 동작하지 않습니다.
상수 시간 비교이며 HMAC이 아닙니다. 토큰이 인바운드의 유일한 인증 수단입니다. 비밀 정보로 취급하십시오.
스트리밍 편집을 지원하지 않습니다. Mattermost에는 PUT /posts/<id> API가 있지만 게이트웨이에서 아직 연결되지 않았습니다.

문제 해결

아웃바운드에서 "401 Unauthorized" 오류 발생

MATTERMOST_BOT_TOKEN이 잘못되었거나 만료되었거나 다른 팀에 범위가 지정되어 있습니다. System Console에서 새 토큰을 생성한 후 환경 변수를 업데이트하십시오.

"Outgoing webhook이 실행되지 않음"

채널이 비공개입니다. 공개 채널만 지원됩니다.
메시지가 트리거 단어 중 하나로 시작하지 않았습니다.
Webhook이 다른 채널에 설정되어 있습니다.

"인바운드에서 401 오류 발생"

MATTERMOST_OUTGOING_WEBHOOK_TOKEN이 일치하지 않습니다. Webhook을 재생성하면 토큰이 교체되므로 환경 변수를 동기화하십시오.

참조

환경 변수: MATTERMOST_*
아웃바운드: apps/agent/src/messaging/mattermost.ts
인바운드 스펙: apps/agent/src/messaging/inbound/specs/mattermost.ts
Mattermost 통합 가이드: docs.mattermost.com / Outgoing Webhooks

목차