8. グループの設定 一覧へ
Zulipには、ボットという機能があります。ボットは擬似的なユーザーとして存在し、ボットに話しかけることで、外部のサービスやプログラムと連携して情報のやりとりをすることができるようになります。
また、Zulipのボットは、次の5種類が存在します。
次のような手順で、ボットを作成することができます。
組織の設定のメニューの「ボット」をクリックすると、以下の画面が表示されます。
新しいボットを追加 のリンクをクリックすると、以下の画面が表示されます。
次のような項目を設定できます。
追加 をクリックすることで、ボットを作成することができます。
次のような手順で、ボットの管理を行うことができます。
個人の設定のメニューの「ボット」をクリックすると、以下の画面が表示されます。
上記スクリーンショットの番号に対応する説明は以下の通りです。
１．アクティブなボット
- 現在稼働しているボットを表示することができます
２．非アクティブなボット
- 現在停止中のボットを表示することができます
３．ボットを管理
- ボットの名前・役割・オーナー(管理者)・アバターを変更することができます
４．zuliprcをダウンロード
- zuliprcを端末にダウンロードすることができます
５．zuliprcをコピー
- zuliprcの情報をコピーすることができます
６．ボットを無効化
- ボットを無効化することができます。無効化されたボットは、非アクティブなボットに表示されます
７．登録済みチャンネル
- ボットに登録済みのチャンネルの一覧を表示することができます
８．Generate URL for an integration
- 連携先のサービスを指定し、連携用のURLを生成することができます
受信Webフックには、多くの種類が存在します。例えば次のようなものです。
実際にこれらの機能を利用する場合、まずZulipの管理画面でボットを作成します。 受信Webフックのボットを作成する際、ボット種別でIncoming webhookを選択すると、以下のような画面になります。
以下は、受信Webフック用のボット作成後の画面です。ここに表示されているAPIキーを使用して、外部からZulipにリクエストを送信することができます。なお、メールアドレスは擬似的なものであるため、実際に存在する必要はありません。
受信Webフックには、開発者向けのサンプル受信Webフックである、Hello Worldというフックが含まれています。Zulipのボットの連携は、サービスごとに連携のための設定値や方法が異なるため、ここでは動作検証用にHello Worldを使用した受信Webフックの例を記載します。
Hello World を利用するためには、以下のようなURLフォーマットを使用します。
https://domain/api/v1/external/helloworld?api_key=abcdefgh&stream=stream
また、JSONでメッセージやURLを送ることができます。以下は、curlコマンドでリクエストを送信する例です。
# curl "https://zulip-kensyo.example.com/api/v1/external/helloworld?api_key=t0BWFAQ9HNXfq5iYrJjlO5Yswt9Sof2A&channel=general" \
-d '{ "featured_title":"mytitle", "featured_url":"https://www.designet.co.jp" }'
送信すると以下のように、ボットがgeneralチャンネルに自動的にHello Worldというトピックを作成し、メッセージを投稿することができます。
上記では動作確認目的でcurlを利用しましたが、実際には他のサービスから上記のようなURLにリクエストを送信することになります。そうすることで、外部サービスからの通知をZulipで受け取ることができるようになります。
発信Webフックも、受信Webフックと同様、専用のボットが必要です。
発信Webフックのボットを作成する際、ボット種別でOutgoing webhookを選択すると、以下のような画面になります。
受信Webフックとの違いは、リクエストを送信する先のURLを指定する点です。また、メッセージの形式についてはZulip形式の他に、Slack互換方式(Slack-compatible)を選択することもできます。Slack互換の形式を使うことで、Slack用に作られた外部サービスを利用できるようになります。
発信Webフックの起動トリガーは、以下の2つです。なお、特定のチャンネルや、全てのメッセージを対象にすることはできません。
実際にボットにダイレクトメッセージを送ると、次のようなリクエストが送信されます。
POST /api HTTP/1.1
Host: zulip-kensyo.example.com:8000
User-Agent: ZulipOutgoingWebhook/11.4
Content-Length: 914
Accept: */*
Content-Type: application/json
Accept-Encoding: gzip
{"data": "メッセージ", "message": {"id": 61862, "sender_id": 8, "content": "メッセージ",
"recipient_id": 522, "timestamp": 1696408268, "client": "website", "subject": "", "topic_links": [],
"rendered_content": "<p>メッセージ</p>", "is_me_message": false, "reactions": [],"submessages": [],
"sender_full_name": "\u68ee \u5f70\u543e", "sender_email": "ohkochi@example.com", "sender_realm_str": "",
"display_recipient": [{"id": 514, "email": "out-bot@zulip-kensyo.example.com", "full_name": "out",
"is_mirror_dummy": false}, {"email": "ohkochi@example.com", "full_name": "\u68ee \u5f70\u543e",
"id": 8, "is_mirror_dummy": false}], "type":"private", "avatar_url":
"https://secure.gravatar.com/avatar/bbc74f32162ce65bfe639e349f575aec?d=identicon&version=1",
"content_type": "text/x-markdown"},"bot_email": "out-bot@zulip-kensyo.example.com", "bot_full_name":
"out", "token":"5f74fIArhd5tYGR1PRHqMwJJYcmF76Rz", "trigger": "private_message"}
外部プログラムでこのリクエストを受け取り、適切なレスポンスを返すことで、外部と連携した処理が可能になります。
なお、Zulipデフォルトの設定では、プライベートIPアドレスレンジへのリクエスト送信が拒否されます。Zulip内部サービスとしては、smokescreenというサービスが、Zulipから外に出ていくアクセスの拒否・許可を行っています。
プライベートIPアドレスを許可する場合、管理者権限でサーバにログインし、 /etc/supervisor/conf.d/zulip/smokescreen.conf ファイルに以下のように設定します。
[program:smokescreen]
command=/usr/local/bin/smokescreen-1b618edf4d3dda409ab7a00cdf3f202e143b5289-go-1.24.4 --listen-ip 127.0.0.1 --unsafe-allow-private-ranges
priority=15
autostart=true
autorestart=true
user=zulip
redirect_stderr=true
stdout_logfile=/var/log/zulip/smokescreen.log
上記は「--unsafe-allow-private-ranges」を追加して、プライベートIPアドレスを全許可する例です。他にも「--allow-range」というオプションで、特定のIPアドレスだけを許可することが可能です。
Zulipの機能の性質上、一般のユーザーもボットを作成する可能性があるため、許可するIPアドレスには充分注意が必要です。
