Mattermost 記事まとめ: https://blog.kaakaa.dev/tags/mattermost/

本記事について

Mattermost の統合機能アドベントカレンダーの第 9 日目の記事です。

本記事では、Mattermost の統合機能から投稿を作成する際に、視覚的にリッチな投稿を作成することができる Message Attachments の機能について紹介します。

https://docs.mattermost.com/developer/message-**attachments.html

Message Attachments の概要

Message Attachments は Mattermost 上に下記のような投稿を作成するための機能です。（画像は公式ドキュメントより）

message attachment

Mattermost ではデフォルトで Markdown 記法(設定によっては katex 記法も)をサポートしているため、簡単な見出しやリンクなどは普通の投稿で表すことができますが、多くの情報を通知したい場合、Markdown だと情報量の分だけ投稿が縦に伸びていってしまうため視認性が悪いという問題があります。 そのような場合に Message Attachments を使うことで、より構造化された情報を Mattermost 上に投稿できるようになります。

Message Attachments は、今まで紹介してきた Incoming WebHook や Slash Command、今後紹介予定の REST API やプラグインなど、Mattermost へ投稿を作成する多くの場合で使用することができます。今回は、Incoming WebHook を利用して Message Attachments を作成する例を紹介していきます。

Message Attachments の作成

まず、Incoming WebHook(内向きのウェブフック)のおさらいです。 Incoming WebHook では、ウェブフックのエンドポイントに下記のような JSON データを送信することで、Mattermost に投稿を作成することができました。

BODY='{
  "text": "Hello, Mattermost"
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

Message Attachments を使う場合、送信する JSON データにattachmentというフィールドを追加します

BODY='{
  "text": "Hello, Mattermost",
  "attachments": [{
    "color": "#FF6600",
    "text": "message attachments",
    "title": "This is title",
    "title_link": "https://github.com/mattermost"
  },{
    "color": "#0066FF",
    "text": "message attachments2",
    "title": "This is title",
    "title_link": "https://github.com/mattermost"
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

上記のコマンドを実行することで、通常のメッセージの下に Message Attachments のメッセージが表示されます。

example

attachmentsは複数指定することができ、複数指定した場合は上記のように縦に並んで表示されます。

以降は、attachmenstに指定できるオプションと、その効果を紹介していきます。

Attachments Options

fallback

メッセージが作成された際の通知メッセージを指定します。

use fallback

BODY='{
  "attachments": [{
    "fallback": "This is fallback"
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

何も指定しない場合はシステムデフォルトのメッセージが表示されます。

default fallback

color

Message Attachments の左側に表示されるラインの色を指定します。

use color

BODY='{
  "attachments": [{
    "color": "#FF6600"
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

pretext

Message Attachments 領域の上に表示されるテキストを指定します。Markdown や絵文字も使用できます。

use pretext

BODY='{
  "attachments": [{
    "pretext": "This is `pretext`"
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

attachmentsと同時にtextフィールドを指定した場合、両方のテキストが表示されます。 また、attachmentsを複数指定していた場合、pretextは Message Attachments の前にそれぞれ表示されます。

BODY='{
  "text": "This is `text`",
  "attachments": [{
    "pretext": "This is first `pretext`"
  },{
    "pretext": "This is second `pretext`"
  }]
}'

use pretext

text

Message Attachments 領域内に表示されるテキストです。こちらも Markdown や絵文字を利用可能です。

use text

BODY='{
  "attachments": [{
    "text": "## This is `text` :smiley: \n**Markdown** can be used."
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

Author Details

author_name / author_link / author_icon

Message Attachments の作成者情報を指定します。

use author

BODY='{
  "attachments": [{
    "author_name": "kaakaa",
    "author_link": "https://github.com/kaakaa",
    "author_icon": "https://blog.kaakaa.dev/images/avatar.png",
    "text": "Author Details"
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

Titles

title / title_link

use title

BODY='{
  "attachments": [{
    "title": "Attachment Title",
    "title_link": "https://github.com/kaakaa",
    "text": "Titles"
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

Author Details と同時に指定した場合は、下記のような見た目になります。

use title

Fields

title / value / short

Message Attachments の内容を指定します。

use fields

BODY='{
  "attachments": [{
    "text": "Fields"
    "fields": [{
      "title": "Short Field :one:",
      "value": "This is first **short** field. This is first **short** field. This is first **short** field. This is first **short** field. This is first **short** field. ",
      "short": true
    }, {
      "title": "Short Field :two:",
      "value": "This is second **short** field. This is second **short** field. This is second **short** field. This is second **short** field. This is second **short** field. ",
      "short": true
    }, {
      "title": "Long Field :one:",
      "value": "This is first **long** field. This is first **long** field. This is first **long** field. This is first **long** field. This is first **long** field. ",
      "short": false
    }, {
      "title": "Long Field :two:",
      "value": "This is second **long** field. This is second **long** field. This is second **long** field. This is second **long** field. This is second **long** field. ",
      "short": false
    }],
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

Images

image_url / thumb_url

Message Attachment に表示される画像の URL を指定します.

use images

BODY='{
  "attachments": [{
    "text": "Images",
    "fields": [
      {"title": "Long Field", "value": "This is a long field", "short": false},
      {"title": "Short Field", "value": "This is a short field", "short": true},
      {"title": "Short Field", "value": "This is a short field", "short": true},
      {"title": "Short Field", "value": "This is a short field", "short": true}
    ],
    "image_url": "https://blog.kaakaa.dev/images/avatar.png",
    "thumb_url": "https://blog.kaakaa.dev/images/avatar.png"
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

footer / footer_link

Message Attachments のフッター情報を指定します。

use footer

BODY='{
  "attachments": [{
    "text": "Footer",
    "footer": "sample footer",
    "footer_icon": "https://blog.kaakaa.dev/images/avatar.png"
  }]
}'

curl \
  -H "Content-Type: application/json" \
  -d "$BODY"  \
  http://localhost:8065/hooks/ucw5qjw86jgeum77o1uw8197jr

既知の問題

2020/11 月時点では、下記の制限があります。

さいごに

Message Attachments の基本的な使い方について紹介しました。 明日は、Mattermost の REST API について紹介します。

comments powered by Disqus