一、機能紹介
ボット(bot)とは、メッセージを自動的にプッシュするか、もしくは簡単な対話のやり取りができるオートメーションプログラムです。グループチャットにボットを追加することで、メンバーとリアルタイムで情報を共有でき、効率的なコラボレーションを実現できます。たとえば、Lark のリマインダーボットを使用して、メンバーにリマインダーを送信できます。
この文章では、特殊なボットの一つとして、カスタムボットの使い方についてご説明します。
カスタムボット(custom bot)
カスタムボットは、ニーズに応じて自由に構成することができます。Webhook を介して外部システムからメッセージを取得し、そのメッセージをグループチャットにプッシュして、グループメンバーと共有することができます。カスタムボットは自動的に通知を送信するために使用され、メッセージに応答することはできません。カスタムボットは、グループチャットでのみ追加および使用できます。
注意:1 つのグループに最大 15 個のボットを追加できます。
二、操作方法
グループチャットを開き、設定 - ボット にて、ボットを追加 をクリックします。追加したいボットを選択し、グループに追加します。追加後、グループメンバーがボットの機能を使用できます。
チャットボットをグループチャットで利用するには、追加設定が必要なボットと、ボットを @メンションして利用できるボットがあり、具体的な使い方はボットによって異なります。
以下では、主にカスタムボットの設定と使用方法についてご紹介します。
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"
}
最大 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 時間以上経過しており、有効期限が切れています。
この場合、次のメッセージが返されます。
// デジタル署名の認証に失敗しました
{
"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 経由で送信されるメッセージカードとは異なります。カスタムボットが送信するメッセージカードは、リダイレクトメソッド(Redirection method)のみがサポートされており、パスバックメソッド(Passback method)はサポートされていません。 メッセージカードでユーザーを @メンションする機能を利用する場合は、現在 open_id
パラメータのみサポートされており、email
、user_id
などはサポートされいません。
設定 - ボット にて、追加したボットの右側にある ボットを削除 ボタンをクリックします。
三、よくあるご質問
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
表示するメッセージ