Bot Connector API を使用してメッセージにメディア添付ファイルを追加するAdd media attachments to messages with the Bot Connector API

通常、ボットとチャネルが交換するのはテキスト文字列ですが、添付ファイルの交換もサポートされる一部のチャネルでは、ボットはよりリッチなメッセージをユーザーに送信できます。Bots and channels typically exchange text strings but some channels also support exchanging attachments, which lets your bot send richer messages to users. たとえば、ボットは、メディア添付ファイル (画像、動画、オーディオ、ファイルなど) とリッチ カードを送信できます。For example, your bot can send media attachments (e.g., images, videos, audio, files) and rich cards. この記事では、Bot Connector サービスを使用してメッセージにメディア添付ファイルを追加する方法について説明します。This article describes how to add media attachments to messages using the Bot Connector service.

ヒント

各チャネルでサポートされる機能を記載した表については、チャネルのリファレンス記事を参照してください。For tables describing which features are supported on each channel, see the channels reference article.

メディア添付ファイルの追加Add a media attachment

メディア添付ファイルをメッセージに追加するには、Attachment オブジェクトを作成し、name プロパティを設定します。さらに、contentUrl プロパティをメディア ファイルの URL に設定し、contentType プロパティを適切なメディアの種類 (たとえば、image/pngaudio/wavvideo/mp4) に設定します。To add a media attachment to a message, create an Attachment object, set the name property, set the contentUrl property to the URL of the media file, and set the contentType property to the appropriate media type (e.g., image/png, audio/wav, video/mp4). 次に、メッセージを表す Activity オブジェクト内で、Attachment オブジェクトを attachments 配列内に指定します。Then within the Activity object that represents your message, specify your Attachment object within the attachments array.

次の例に、テキストと 1 つの画像添付ファイルを含むメッセージを送信する要求を示します。The following example shows a request that sends a message containing text and a single image attachment. この要求の例で、https://smba.trafficmanager.net/apis はベース URI を示しています。ご利用のボットによって発行される要求に対するベース URI は、これとは異なる場合があります。In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. ベース URI の設定の詳細については、API リファレンスに関する記事をご覧ください。For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "text": "Here's a picture of the duck I was telling you about.",
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

画像のインライン バイナリをサポートするチャネルの場合、AttachmentcontentUrl プロパティを画像の base64 バイナリに設定できます (たとえば、data:image/png;base64,iVBORw0KGgo... )。For channels that support inline binaries of an image, you can set the contentUrl property of the Attachment to a base64 binary of the image (for example, data:image/png;base64,iVBORw0KGgo…). このチャネルでは、メッセージのテキスト文字列の横に画像または画像の URL が表示されます。The channel will display the image or the image's URL next to the message's text string.

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "text": "Here's a picture of the duck I was telling you about.",
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "data:image/png;base64,iVBORw0KGgo…",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

上記の画像ファイル用の手順と同じ手順を使用して、動画ファイルまたはオーディオ ファイルをメッセージに添付することができます。You can attach a video file or audio file to a message by using the same process as described above for an image file. チャネルによっては、動画やオーディオがインラインで再生されたり、リンクとして表示されたりすることがあります。Depending on the channel, the video and audio may be played inline or it may be displayed as a link.

注意

ボットがメディア添付ファイルを含むメッセージを受け取ることもあります。Your bot may also receive messages that contain media attachments. たとえば、分析する写真や保存するドキュメントをユーザーがアップロードすることがチャネルによって許可されている場合、ボットが受け取るメッセージに添付ファイルが含まれる場合があります。For example, a message that your bot receives may contain an attachment if the channel enables the user to upload a photo to be analyzed or a document to be stored.

AudioCard 添付ファイルの追加Add an AudioCard attachment

AudioCard または VideoCard 添付ファイルを追加する方法は、メディア添付ファイルを追加する方法と同じです。Adding an AudioCard or VideoCard attachment is the same as adding a media attachment. たとえば、次の JSON は、メディア添付ファイルにオーディオ カードを追加する方法を示しています。For example, the following JSON shows how to add an audio card in the media attachment.

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.audio",
      "content": {
        "title": "Allegro in C Major",
        "subtitle": "Allegro Duet",
        "text": "No Image, No Buttons, Autoloop, Autostart, Sharable",
        "duration": "PT2M55S",
        "media": [
          {
            "url": "https://contoso.com/media/AllegrofromDuetinCMajor.mp3"
          }
        ],
        "shareable": true,
        "autoloop": true,
        "autostart": true,
        "value": {
            // Supplementary parameter for this card
        }
      }
    }],
    "replyToId": "5d5cdc723"
}

チャネルがこの添付ファイルを受け取ると、オーディオ ファイルの再生が開始されます。Once the channel receives this attachment, it will start playing the audio file. たとえば、 [一時停止] ボタンをクリックしてユーザーがオーディオとやりとりすると、チャネルは次のような JSON でコールバックをボットに送信します。If a user interacts with audio by clicking the Pause button, for example, the channel will send a callback to the bot with a JSON that look something like this:

{
    ...
    "type": "event",
    "name": "media/pause",
    "value": {
        "url": // URL for media
        "cardValue": {
            // Supplementary parameter for this card
        }
    }
}

activity.name フィールドにはメディア イベント名 media/pause が表示されます。The media event name media/pause will appear in the activity.name field. すべてのメディア イベント名の一覧については、次の表を参照してください。Reference the below table for a list of all media event names.

EventEvent 説明Description
media/nextmedia/next クライアントが次のメディアまでスキップしましたThe client skipped to the next media
media/pausemedia/pause クライアントがメディアの再生を一時停止しましたThe client paused playing media
media/playmedia/play クライアントがメディアの再生を開始しましたThe client began playing media
media/previousmedia/previous クライアントが前のメディアまでスキップしましたThe client skipped to the previous media
media/resumemedia/resume クライアントがメディアの再生を再開しましたThe client resumed playing media
media/stopmedia/stop クライアントがメディアの再生を停止しましたThe client stopped playing media

その他のリソースAdditional resources