Bot Connector API を使用してメッセージを送受信する

[アーティクル]
03/08/2023

Bot Connector サービスを使用すると、ボットで電子メールや Slack などの複数のチャネル間で通信できます。これにより、ボットからチャネルへ、またチャネルからボットへとアクティビティをリレーすることで、ボットとユーザー間の通信が容易になります。すべてのアクティビティに、メッセージを作成したユーザーに関する情報、メッセージのコンテキスト、メッセージの受信者と共に、適切な送信先にメッセージをルーティングするために使用される情報が含まれます。この記事では、Bot Connector サービスを使用して、チャネル上のボットとユーザーの間で message アクティビティを交換する方法について説明します。

メッセージに応答する

応答を作成する

ユーザーがボットにメッセージを送信すると、ボットは message 型の Activity オブジェクトとしてメッセージを受け取ります。ユーザーのメッセージへの応答を作成するには、新しい Activity オブジェクトを作成し、まず次のプロパティを設定します。

プロパティ	値
conversation	ユーザーのメッセージの `conversation` プロパティのコンテンツにこのプロパティを設定します。
from	ユーザーのメッセージの `recipient` プロパティのコンテンツにこのプロパティを設定します。
locale	指定した場合、ユーザーのメッセージの `locale` プロパティのコンテンツにこのプロパティを設定します。
recipient	ユーザーのメッセージの `from` プロパティのコンテンツにこのプロパティを設定します。
replyToId	ユーザーのメッセージの `id` プロパティのコンテンツにこのプロパティを設定します。
type	このプロパティは message に設定します

次に、ユーザーに伝える情報を指定するプロパティを設定します。たとえば、メッセージに表示するテキストを指定するには text プロパティを設定します。ボットが話すテキストを指定するには speak プロパティを設定します。メディアの添付ファイルや、メッセージに含めるリッチカードを指定するには attachments プロパティを設定します。一般的に使用されるメッセージのプロパティについては、「Create messages」(メッセージの作成) を参照してください。

応答を送信する

受信アクティビティの serviceUrl プロパティを使用して、ボットがその応答の発行に使用するベース URI を指定します。

応答を送信するには、次の要求を発行します。

POST /v3/conversations/{conversationId}/activities/{activityId}

この要求 URI の {conversationId} を (応答) Activity 内の conversation オブジェクトの idプロパティの値で置き換え、 {activityId} を (応答) Activity 内の replyToId プロパティの値で置き換えます。応答を表すために作成した Activity オブジェクトに要求の本文を設定します。

次の例は、単純なテキストのみの応答をユーザーのメッセージに送信する要求を示しています。この要求の例で、https://smba.trafficmanager.net/teams はベース URI を示しています。ご利用のボットによって発行される要求に対するベース URI は、これとは異なる場合があります。ベース URI の設定の詳細については、API リファレンスに関する記事をご覧ください。

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723 
Authorization: Bearer ACCESS_TOKEN 
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "Pepper's News Feed"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "Convo1"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "SteveW"
    },
    "text": "My bot's reply",
    "replyToId": "5d5cdc723"
}

(非応答) メッセージを送信する

ボットが送信するメッセージの多くは、ユーザーから受信したメッセージへの応答に含まれます。ただし、ボットが、ユーザーからのメッセージに対する直接の返信ではないメッセージを会話に送信する必要がある場合があります。たとえば、ボットから新しいトピックの会話を開始する場合や、会話の最後にさようならのメッセージを送信する場合があります。

ユーザーからのメッセージへの直接の返信ではないメッセージを会話に送信するには、次の要求を発行します。

POST /v3/conversations/{conversationId}/activities

この要求 URI では、 {conversationId} を会話の ID で置き換えます。

応答を表すために作成する Activity オブジェクトに要求の本文を設定します。

Note

Bot Framework では、ボットが送信できるメッセージの数に制限はありません。しかし、ほとんどのチャネルでは、ボットが短時間で多数のメッセージを送信しないように、調整制限を強制します。さらに、ボットで立て続けに複数のメッセージを送信する場合は、チャネルでは適切な順序でメッセージがレンダリングされない可能性があります。

会話の開始

ボットで 1 人または複数のユーザーと会話を開始する必要がある場合があります。チャネル上でユーザーとの会話を開始するには、ボットがそのアカウント情報と、そのチャネル上のユーザーのアカウント情報を知っている必要があります。

ヒント

ボットが今後ユーザーとの会話を開始する必要がある場合は、ユーザーのアカウント情報、ユーザーの設定やロケールなどの関連情報、サービス URL をキャッシュします (そして会話の開始要求のベース URI として使用します)。

会話を開始するには、次の要求を発行します。

POST /v3/conversations

ボットのアカウント情報と、会話に含めるユーザーのアカウント情報を指定する ConversationParameters オブジェクトに、要求の本文を設定します。

Note

すべてのチャネルが、グループ会話をサポートするわけではありません。チャネルがグループの会話をサポートしているかどうかを判断し、チャネルが会話で許可している参加者の最大数を特定するには、チャネルのドキュメントを参照してください。

次の例は、会話を開始する要求を示しています。この要求の例で、https://smba.trafficmanager.net/teams はベース URI を示しています。ご利用のボットによって発行される要求に対するベース URI は、これとは異なる場合があります。ベース URI の設定の詳細については、API リファレンスに関する記事をご覧ください。

POST https://smba.trafficmanager.net/teams/v3/conversations 
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "bot": {
        "id": "12345678",
        "name": "bot's name"
    },
    "isGroup": false,
    "members": [
        {
            "id": "1234abcd",
            "name": "recipient's name"
        }
    ],
    "topicName": "News Alert"
}

指定されたユーザーとの会話が確立されている場合、応答には会話を識別する ID が含まれます。

{
    "id": "abcd1234"
}

ボットはその会話 ID を使用して、会話内のユーザーにメッセージを送信します。

次の方法で共有