送信 Webhook を作成する

送信 Webhook はボットとして機能し、@メンションを使用してチャネル内のメッセージを検索します。 外部 Web サービスに通知を送信し、カードや画像を含むリッチ メッセージで応答します。 Microsoft Bot Framework を使用してボットを作成するプロセスをスキップすることができます。

送信 Webhook を作成する方法については、次のビデオを参照してください。

送信 Webhook の主な機能

次の表には、送信 Webhook の機能と説明があります。

機能	説明
スコープ構成	Webhook はチームのレベルでスコープが設定されます。 各必須のセットアップ プロセスでは、送信 Webhook が追加されます。
反応性のあるメッセージング	Webhook がメッセージを受信するには、ユーザーが @メンション を使用する必要があります。 現在ユーザーが送信 Webhook でメッセージを送信できるのは公開チャネルのみです。個人またはプライベートのスコープ内では行えません。
標準の HTTP メッセージ交換	応答は元の要求メッセージと同じチェーンに表示され、Bot Framework メッセージの内容を含めることができます。 たとえば、リッチ テキスト、画像、カード、絵文字などです。 送信 Webhook はカードを使用することができますが、openURL のカード アクションしか使用することができません。
Teams API メソッドのサポート	送信 Webhook は HTTP POST を Web サービスに送信し、応答を取得します。 チーム内の参加者一覧やチャネルのリストの取得など、他の API にはアクセスすることはできません。

送信 Webhook を作成する

送信 Webhook を作成し、カスタム ボットを Teams に追加します。 送信 Webhook を作成するには、次の手順を実行します。

1. 左側のウィンドウから Teams を選択します。

   

2. [Teams] ページで、送信 Webhook を作成するために必要なチームを選択し、[••] を選択します。

3. ドロップダウン メニューから [ チームの管理 ] を選択します。

   

4. チャネル ページで [ アプリ ] を選択します。

   

5. [ 送信 Webhook の作成] を選択します。

   

6. [ 送信 Webhook の作成 ] ページに次の詳細を入力します。

   • 名前: webhook タイトルと @メンション タブ。
   • コールバック URL: JSON ペイロードを受け入れ、Teams からの POST 要求を受信する HTTPS エンドポイントです。
   • 説明: プロファイル カードとチーム レベルのアプリ ダッシュボードに表示される詳細な文字列。
   • プロファイル画像: Webhook のアプリ アイコン (省略可能)。

7. [作成] を選択します。 送信 Webhook は、現在のチームのチャネルに追加されます。

   

ハッシュ ベースのメッセージ認証コード (HMAC) ダイアログが表示されます。 これはセキュリティ トークンで、Teams と指定された外部サービス間の呼び出しを認証するために使用されます。 HMAC セキュリティ トークンは有効期限がなく、構成ごとに一意です。

注:

URL が有効で、サーバーとクライアントの認証トークンが等しい場合、チームのユーザーは送信 Webhook を使用できるようになります。 たとえば、HMAC ハンドシェイクなどです。

次のシナリオは、送信 Webhook を追加するための詳細です。

• シナリオ: Teams のチャネル データベース サーバーの変更状況通知をアプリにプッシュします。
• 例: すべての CRUD (作成、読み取り、更新、削除) 操作を追跡する組織 (LOB アプリ) 用に構築されたカスタム アプリがあります。 これらの操作は、Microsoft 365 テナント全体の Teams チャネル人事ユーザーによって従業員レコードに対して行われます。

URL JSON ペイロード

アプリのサーバー上で URL を作成し、JSON ペイロードを使用して POST 要求を受け入れて処理する

サービスは、標準の Azure Bot Service のメッセージング スキーマでメッセージを受信します。 Bot Framework Connector は、Azure Bot Service API で文書化されているように、サービスが HTTPS プロトコルを使用して JSON 形式のメッセージ交換を処理できるようにする RESTful サービスです。 Microsoft Bot Framework SDK を使用して、メッセージの処理と解析を行うこともできます。 詳細については、Azure Bot Service の概要 を参照してください。

送信 Webhook は、team レベルにスコープが設定され、チームのすべてのメンバーに表示されます。 ユーザーがチャネルで呼び出すには、送信 Webhook の名前を @メンションする必要があります。

HMAC トークンを確認する

送信 Webhook HMAC トークンを確認するメソッドを作成する

受信メッセージと ID の例: {"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hKKk/N2bOmlM31zaA=" } という SigningKeyDictionary の "contoso"。

要求ヘッダーの認証には、"HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs + mO41mPL + R1e1U =" という値を使用します。

サービスが受け取る呼び出しが本物の Teams クライアントからの呼び出しのみになるよう、HTTP hmac 認証ヘッダーの HMAC コードが Teams によって提供されます。 常に認証プロトコルにコードを含めます。

次のように、コードで要求に含まれる HMAC 署名を常に検証する必要があります。

• メッセージの要求本文から HMAC トークンを生成します。 ほとんどのプラットフォームでこれを行うための標準ライブラリがあります。たとえば、Node.js の Crypto 、C# 用 の Teams Webhook サンプル などです。 Microsoft Teams では、標準の SHA256 HMAC 暗号化を使用します。 本文を UTF8 でバイト配列に変換する必要があります。
• Teams クライアントで送信 Webhook を登録したときに Teams によって提供されたセキュリティ トークンのバイト配列からハッシュを計算します。 「送信 Webhook を作成する」を参照してください。
• UTF-8 エンコーディングを使用してハッシュを文字列に変換します。
• 生成されたハッシュの文字列の値と、HTTP 要求で指定された値を比較します。

サンプル コード リファレンス

public static AuthResponse Validate(AuthenticationHeaderValue authenticationHeaderValue, string messageContent, string claimedSenderId)
{
    //...
    string providedHmacValue = authenticationHeaderValue.Parameter;
    string calculatedHmacValue = null;
    try
    {
        byte[] serializedPayloadBytes = Encoding.UTF8.GetBytes(messageContent);
 
        byte[] keyBytes = Convert.FromBase64String(signingKey);
        using (HMACSHA256 hmacSHA256 = new HMACSHA256(keyBytes))
        {
            byte[] hashBytes = hmacSHA256.ComputeHash(serializedPayloadBytes);
            calculatedHmacValue = Convert.ToBase64String(hashBytes);
        }
 
        if (string.Equals(providedHmacValue, calculatedHmacValue))
        {
            return new AuthResponse(true, null);
        }
        else
        {
            string errorMessage = string.Format(
                "AuthHeaderValueMismatch. Expected:'{0}' Provided:'{1}'",
                calculatedHmacValue,
                providedHmacValue);
 
            return new AuthResponse(false, errorMessage);
        }
    }
    catch (Exception ex)
    {
        Trace.TraceError("Exception occcured while verifying HMAC on the incoming request. Exception: {0}", ex);
        return new AuthResponse(false, "Exception thrown while verifying MAC on incoming request.");
    }
}

応答するメソッド

成功または失敗の応答を送信するメソッドを作成する

送信 Webhook からの応答は、元のメッセージと同じ返信チェーンに表示されます。 ユーザーがクエリを実行すると、Teams はサービスに対して同期 HTTP 要求を発行し、コードには、メッセージに応答するための 5 秒間が与えられます。この時間を過ぎると、接続がタイムアウトして終了します。

応答の例

{
    "type": "message",
    "text": "This is a reply!"
}

送信 Webhook でアダプティブ カードを使用する

アダプティブ カード、ヒーロー カード、テキスト メッセージは、送信 Webhook で添付ファイルとして送信できます。 カードは書式設定をサポートしています。 詳細については、「 Markdown を使用してカードを書式設定する」を参照してください。 送信 Webhook のアダプティブ カードでは、カードアクションのみがopenURLサポートされます。

以下のコードは、アダプティブ カードの応答例です。

C#/.NET

サンプル コード リファレンス

// This method is to read the request body content
string content;
using (var reader = new StreamReader(Request.Body))
    {
        content = await reader.ReadToEndAsync();
    }

var Card = new AdaptiveCard(new AdaptiveSchemaVersion("1.4"))
{
    Body = new List<AdaptiveElement>()
    {
        new AdaptiveTextBlock(){Text= $"Request sent by: {incomingActivity.From.Name}"},
        new AdaptiveImage(){Url=new Uri("https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6")},
        new AdaptiveTextBlock(){Text="Sample image for Adaptive Card.."}
    }
};

var attachment = new Attachment()
{
    ContentType = AdaptiveCard.ContentType,
    Content = Card
};

var sampleResponseActivity = new Activity
{
    Attachments = new [] { attachment }
};

return sampleResponseActivity;

JavaScript/Node.js

サンプル コード リファレンス

var receivedMsg = JSON.parse(payload);
var responseMsg = JSON.stringify({
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": {
                "type": "AdaptiveCard",
                "version": "1.4",
                "body": [
                    {
                        "type": "TextBlock",
                        "text": "Request sent by: " + receivedMsg.from.name
                    },
                    {
                        "type": "Image",
                        "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
                    },
                    {
                        "type": "TextBlock",
                        "text": "Sample image for Adaptive Card."
                    }
                ]
            },
            "name": null,
            "thumbnailUrl": null
        }
    ]
});

JSON

{
 "type": "message",
 "attachments": [
  {
   "contentType": "application/vnd.microsoft.card.adaptive",
   "content": {
    "type": "AdaptiveCard",
    "version": "1.4",
    "body": [
     {
      "type": "TextBlock",
      "text": "Request sent by: Megan"
     },
     {
      "type": "Image",
      "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
     },
     {
      "type": "TextBlock",
      "text": "Sample image for Adaptive Card.."
     }
    ]
   }
  }
 ]
}

コード サンプル

サンプルの名前	説明	.NET	Node.js
Webhookの送信	このサンプルでは、送信 Webhook を実装して使用する方法を示します。	表示	表示

ステップ バイ ステップのガイド

「ステップ バイ ステップ ガイド」に従って、Teams で送信 Webhook を作成します。

関連項目

• Webhook とコネクタ
• メッセージを作成して送信する
• 受信 Webhook を作成する
• Microsoft 365 グループのコネクタを作成する
• アダプティブ カード