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

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 を使用して、会話内のユーザーにメッセージを送信します。

その他のリソース

• メッセージの作成
• Bot Framework のアクティビティ スキーマ