FAQ｜グループチャットにボットを追加する方法は？

一、機能紹介

ボット（bot）とは、メッセージを自動的にプッシュするか、もしくは簡単な対話のやり取りができるオートメーションプログラムです。グループチャットにボットを追加することで、メンバーとリアルタイムで情報を共有でき、効率的なコラボレーションを実現できます。たとえば、Lark のリマインダーボットを使用して、メンバーにリマインダーを送信できます。

この文章では、特殊なボットの一つとして、カスタムボットの使い方についてご説明します。

カスタムボット（custom bot）

カスタムボットは、ニーズに応じて自由に構成することができます。Webhook を介して外部システムからメッセージを取得し、そのメッセージをグループチャットにプッシュして、グループメンバーと共有することができます。カスタムボットは自動的に通知を送信するために使用され、メッセージに応答することはできません。カスタムボットは、グループチャットでのみ追加および使用できます。

注意：1 つのグループに最大 15 個のボットを追加できます。

二、操作方法

1.グループチャットでボットを使用する

グループチャットを開き、設定 - ボット にて、ボットを追加 をクリックします。追加したいボットを選択し、グループに追加します。追加後、グループメンバーがボットの機能を使用できます。

チャットボットをグループチャットで利用するには、追加設定が必要なボットと、ボットを @メンションして利用できるボットがあり、具体的な使い方はボットによって異なります。

以下では、主にカスタムボットの設定と使用方法についてご紹介します。

1.1 グループチャットでカスタムボットを使用する

カスタムボットが外部システムからのメッセージをリアルタイムにプッシュするには、webhook の形式でグループチャットにメッセージを送信する必要があります。カスタムボットを追加したいグループを開き、設定- ボット にて、ボットを追加 をクリックし、カスタムボット（Custom Bot）を選択します。

ステップ 1：ボットをグループに追加します。ボット名と説明を入力して、次へをクリックします。

ステップ 2：webhook を設定します。次の形式のボットの webhook URL を取得します。

https://open.larksuite.com/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx

この URL をコピーし、連携したい外部システムにて、グループにメッセージを送信するように設定します。webhook URL が漏洩した場合、他者への迷惑メッセージの発信に悪用される恐れがあるため、大切に保管してください。

注意：古いバージョンの webhook（https://open.larksuite.com/open-apis/bot/hook/xxxxxxxxxxxxxxxxxx ，URLに v2 を含まない）をご利用の場合、記事の最後にある追記を参照してください。

1.1.1 セキュリティ設定

webhook URL が漏洩した場合、他者への迷惑メッセージの発信に悪用される恐れがあるため、セキュリティ設定を行うことを強くおすすめします。

現在、セキュリティ設定には 3 つの方法があり、必要に応じて 1 つ以上の方法を選択できます。

•方法一、キーワードによる認証

最大 10 個のキーワードを設定できます。設定後、少なくとも 1 つのキーワードを含むメッセージのみが送信されます。

たとえば、キーワード「エラー通知」と「プロジェクト更新」を設定した後、これらの単語の少なくとも 1 つが含まれるメッセージのみ、カスタムボットによってグループチャットに送信されます。

リクエストの送信後、キーワード認証に失敗した場合、次のメッセージが返されます。


// キーワード認証に失敗しました
{
        "code": 19024,
        "msg": "Key Words Not Found"
}

•方法二、IP ホワイトリストによる認証

最大 10 個の IP アドレスまたはアドレスセグメントを設定できます。設定後は、設定した IP アドレスからのリクエストのみ処理します。123.12.1.* または 123.1.1.1/24 など、セグメント入力をサポートしています。

リクエストの送信後、IP 認証に失敗した場合、次のメッセージが返されます。


// IP 認証に失敗しました
{
        "code": 19022,
        "msg": "Ip Not Allowed"
}

•方式三、デジタル署名による認証

設定後、送信されたリクエストには、信憑性を保証するためのデジタル署名による認証が必要です。

署名アルゴリズム：タイムスタンプ + "\n" + キーを署名文字列として生成し、HmacSHA256 関数使用して署名を計算してから、Base64 エンコードを実行します。

•timestamp は、現在の時刻から 1 時間（3600）以内のタイムスタンプです。

•キーは自動的に生成され、画面から直接コピーできます。

func GenSign(secret string, timestamp int64) (string, error) {
   // タイムスタンプ + "\n" + キー を署名文字列として生成し、HmacSHA256 関数使用して署名を計算してから、Base64 エンコードを実行します。
   stringToSign := fmt.Sprintf("%v", timestamp) + "\n" + secret

   var data []byte
   h := hmac.New(sha256.New, []byte(stringToSign))
   _, err := h.Write(data)
   if err != nil {
      return "", err
   }

   signature := base64.StdEncoding.EncodeToString(h.Sum(nil))
   return signature, nil
}

署名を取得した後、リクエストを送信するときに timstamp と sign （取得した署名）フィールドを追加する必要があります。例えば、テキストメッセージの送信をリクエストするコードは次のとおりです。

// デジタル署名による認証が有効な場合のテキストメッセージ送信のリクエスト
{
        "timestamp": "1599360473",
        "sign": "xxxxxxxxxxxxxxxxxxxxx",
        "msg_type": "text",
        "content": {
                "text": "request example"
        }
}

その他のメッセージタイプの形式については、下記を参照してください。

リクエストを送信した後、デジタル署名の認証に失敗した場合は、次のトラブルシューティングを行ってください。

1.タイムスタンプは、送信時から 1 時間以上経過しており、有効期限が切れています。

2.署名が一致せず、認証できません。

この場合、次のメッセージが返されます。

// デジタル署名の認証に失敗しました
{
        "code": 19021,
        "msg": "sign match fail or timestamp is not within one hour from current time"
}

カスタムボットを追加した後、POST リクエストを webhook URL に送信して、グループチャットでメッセージをプッシュできます。サポートされているメッセージ形式は、テキスト、リッチテキスト、画像、グループカードとメッセージカードなどです。

パラメータ msg_type はプッシュするメッセージタイプを表します。指定できる値：text（テキスト）/ post（リッチテキスト）/ image（画像）/ share_chat（グループカード）/ interactive（メッセージカード）

1.1.2 テキストメッセージを送信する

リクエスト例：

{
    "msg_type": "text",
    "content": {
        "text": "アップデートリマインダー"
    }
}

1.1.3 リッチテキストメッセージを送信する

リクエスト例：

{
    "msg_type": "post",
    "content": {
        "post": {
            "zh_cn": {
                "title": "プロジェクト更新",
                "content": [
                    [
                        {
                            "tag": "text",
                            "text": "プロジェクトが更新されました。"
                        },
                        {
                            "tag": "a",
                            "text": "確認してください",
                            "href": "http://www.example.com/"
                        }
                    ]
                ]
            }
        }
    }
}

リッチテキストメッセージの送信に関連するパラメーター（メンバーを @メンションするなど）については、オープンプラットフォームの API ドキュメントを参照してください。

1.1.4 グループカードを送信する

リクエスト例：

{
    "msg_type": "share_chat",
    "content":{
        "share_chat_id": "oc_f5b1a7eb27ae2c7b6adc2a74faf339ff"
    }
}

グループカードの共有に関連するパラメーターについては、オープンプラットフォームの API ドキュメントを参照してください。

1.1.5 画像を送信する

リクエスト例：


{
    "msg_type":"image",
    "content":{
        "image_key": "img_ecffc3b9-8f14-400f-a014-05eca1a4310g"
    }
}

画像の送信に関連するパラメーターについては、オープンプラットフォームの API ドキュメントを参照してください。

1.1.6 メッセージカードを送信する

メッセージカードは、ユーザーと複数回インターラクトできるメッセージタイプであり、ボタン、日付セレクター、画像などの複数のコンポーネントから構成できます。メッセージカードの仕様とフォーマットについては、オープンプラットフォームの API ドキュメント「メッセージカード」を参照してください。

リクエスト例：

{
    "msg_type": "interactive",
    "card": {
        "config": {
                "wide_screen_mode": true,
                "enable_forward": true
        },
        "elements": [{
                "tag": "div",
                "text": {
                        "content": "**西湖（せいこ）**，中国浙江省杭州市西湖区に位置する、世界遺産（文化遺産）として登録されている観光スポット。観光エリアの面積は 49 平方km、水深は平均 1.8m、水域面積 6.38 平方km。",
                        "tag": "lark_md"
                }
        }, {
                "actions": [{
                        "tag": "button",
                        "text": {
                                "content": "ほかの観光地紹介を見る :バラ:",
                                "tag": "lark_md"
                        },
                        "url": "https://www.example.com",
                        "type": "default",
                        "value": {}
                }],
                "tag": "action"
        }],
        "header": {
                "title": {
                        "content": "おすすめの観光スポット",
                        "tag": "plain_text"
                }
        }
    }
}

メッセージカードの仕様とフォーマットについては、オープンプラットフォームの API ドキュメント「メッセージカード」を参照してください。

メッセージカードのインタラクションモジュール（API ドキュメント「インタラクションモジュール」）を設計する場合は、次の点に注意してください：メッセージカードのコールバックアドレスはアプリにバインドされているため、オープンプラットフォーム API 経由で送信されるメッセージカードとは異なります。カスタムボットが送信するメッセージカードは、リダイレクトメソッド（Redirection method）のみがサポートされており、パスバックメソッド（Passback method）はサポートされていません。

メッセージカードでユーザーを @メンションする機能を利用する場合は、現在 open_id パラメータのみサポートされており、email、user_id などはサポートされいません。

2.ボットを削除する

設定 - ボット にて、追加したボットの右側にある ボットを削除 ボタンをクリックします。

三、よくあるご質問

Q：チャットボットをグループに追加しましたが、使い方がわかりません。

A：チャットボットがどのように使用できるかは、ボットの開発者の設計によって異なります。使い方がわからない場合は、以下の 2 つの方法を試してください。

チャットでボットを @メンションすると、ボットが応答することがあります。ボットが送信したガイドメッセージに基づき、使用を開始することができます。

この方法が無効な場合は、ボットのプロフィール写真をクリックして、表示するボットカード（Lark モバイル版 V2.8.0 以降、デスクトップ版 V2.9.0 以降が必要）にて開発者情報を見つけ、開発者に問い合わせてください。開発者に連絡できない場合は、管理者に問い合わせてください。

追記：古いバージョンの webhook （カスタムボット）使用方法

使用するカスタムボットの webhook URL が以下の場合：

https://open.larksuite.com/open-apis/bot/hook/xxxxxxxxxxxxxxxxxx

この webhook はプレーンテキストメッセージの送信のみをサポートします。この場合、メッセージのタイトル title とテキスト text を構成できます。

任意の方法で webhook への HTTP POST リクエストを送信することで、プレーンテキストメッセージをグループに送信できます。リクエストの形式は次のとおりです（JSON 形式）。

{
"title": "Hello Lark",  # オプション
"text": "Good Lark"  # 必須
}

リクエスト例：

curl -X POST -H "Content-Type: application/json" -d '{"title": "Hello Lark",
 "text": "Good Lark"}' https://open.larksuite.com/open-apis/bot/hook/xxxxxxxxxxxxxxxx

表示するメッセージ