API 2.0 Botへのアップグレードガイド

    アップグレードとは、現在稼働中のBotで使用しているAPIをAPI 1.0からAPI 2.0に切り替える作業を意味します。
    このアップグレードにより、最適化された最新のAPIを使用したBot開発や、今後提供されるAPIの追加機能を利用することができます。

    注意

    2022年4月1日以降、新規登録されるBotは既定でAPI 2.0が選択されます。(API 1.0も選択可能)

    BotをAPI 2.0にアップグレードしてもRichMenuなどの既存のBotに登録された情報は、そのまま維持されます。
    アップグレード後もAPI 1.0でメッセージを送信することはできますが、アップグレードの際にメッセージCallbackで受信するHeaderおよびRequestBodyの形式はAPI 2.0の形式に変更されます。
    そのため、メッセージCallbackで対話型コミュニケーションを行なう際は、アップグレードする前にメッセージCallbackの受信サーバー側のアプリケーションを修正する必要があります。

    注意

    外部ソリューションを利用するなど、Bot callback受信サーバーの利用権限がない場合、アップグレードする前に外部ソリューションを提供する開発会社にお問い合わせください。

    アップグレードの事前準備

    BotをAPI 2.0にアップグレードする事前準備手順は以下の通りです。

    1. アプリの追加

    API 2.0を利用するためには管理者がDeveloper Consoleでアプリを追加する際に、OAuth Scopesで「bot」を選択する必要があります。

    詳細はアプリを参照してください。

    2. Service Account認証の利用

    Botアプリでは、Service Account認証を使用するため、Developer Consoleでアプリを追加する際に、Service Accountを発行します。
    発行したService AccountをもとにAccess Tokenを取得し、API 2.0のBot APIを利用します。

    詳細はService Account認証(JWT)を参照してください。

    注意

    • API 1.0の認可機能で取得したAccess TokenでAPI 2.0のBot APIを利用することはできません。必ず、API 2.0の認可機能で取得したAccess Tokenを利用してください。
    • API 2.0ではAccess Token自動延長を提供しません。Access Tokenと同時に取得したRefresh Tokenを用いて、Access Tokenの再取得を行なってください。

    3. メッセージ送信APIの変更

    API 1.0で呼び出しているッセージ送信APIの実装箇所をAPI 2.0に変更します。 API endpoint、Request、Responseをすべて変更する必要があります。

    3.1 API endpoint

    例えば、トークルームを指定してメッセージを送信するAPIのendpointは、以下になります。

    API 1.0

    POST https://apis.worksmobile.com/r/{API_ID}/message/v1/bot/{botNo}/message/push

    API 2.0

    POST https://www.worksapis.com/v1.0/bots/{botId}/channels/{channelId}/messages

    参考

    • API 1.0の「botNo」はAPI 2.0の「botId」に相当します。同じBotであれば「botNo」と「botId」は同じです。
    • API 2.0ではAPI IDは使用しません。
    • API 2.0のメッセージ送信APIは送信先であるユーザーとトークルームでPathが異なります。
      • ユーザー : /bots/{botId}/users/{userId}/messages
      • トークルーム : /bots/{botId}/channels/{channelId}/messages

    3.2 Request / Response

    API 2.0のBot APIのRequest / Response形式に変更します。

    詳細はAPI 2.0のBot APIのトーク共通プロパティをを参照してください。

    3.3 コンテンツファイルのアップロード

    参考

    コンテンツファイルを利用しない場合、この手順をスキップしてください。

    Botのコンテンツをアップロードする際の実装を修正します。

    詳細はファイルアップロード / ダウンロードを参照してください。

    4. メッセージCallbackの変更

    参考

    Callbackを利用しない場合、この手順をスキップしてください。

    callback URLに指定されるAPI 1.0でメッセージ受信している実装箇所をAPI 2.0に変更します。
    メッセージの改ざんチェックには、X-WORKS-SignatureヘッダーとBot secretを利用します。
    Bot secretの値は Developer Console > Bot の詳細情報画面で確認することができます。

    詳細はメッセージ(Callback) 受信を参照してください。

    アップグレードの実施

    稼働中のBotを停止してアップグレードを実施する場合の手順

    1. 「アップグレードの事前準備」を行います。
    2. Developer Console > BotでアップグレードするBotを選択します。
    3. Bot修正画面でAPI 2.0を選択します。
    4. [保存]をクリックするとアップグレード完了です。

    稼働中のBotを稼働したままアップグレードを実施する場合の手順

    1. 「アップグレードの事前準備」を行います。
    2. Developer Console > BotでAPI 2.0用のBotを新規追加します。
    3. 新規追加したBotを非公開に設定し、既存Botと同じ情報を入力します。
    4. Callbackを利用する場合、API 2.0用のCallback URLを設定します。
    5. API 2.0に対応したBotシステムで使用するbotIdは新規追加したBotのbotIdを指定してテストを行ないます。
    6. テスト完了後、API 2.0に対応したBotシステムで使用するbotIdを既存BotのbotIdを変更します。
    7. Developer Console > Botでアップグレードする既存Botを選択します。
    8. Bot修正画面でAPI 2.0を選択します。
    9. Callbackを利用する場合、API 2.0用のCallback URLを設定します。
    10. [保存]をクリックするとアップグレード完了です。

    付録 : プロパティ名変更一覧

    2.0でプロパティ名が変更されたプロパティ名は以下の通りです。 一部を除く、各プロパティの値は同じです。

    プロパティ名 API1.0 API2.0 備考
    bot識別子 botNo botId
    ユーザーを特定するID accountId userId
    ユーザーリスト accountIds, memberList members
    Bot名 name botName
    担当者 managers administrators
    副担当者 submanagers subadministrators
    複数人のトークルームに招待可否 useGroupJoin enableGroupJoin
    Botの利用ドメイン domainIds allowDomains
    Callback利用有無 useCallback enableCallback
    Bot名(多国語) i18nNames[].name i18nNames[].botName
    Callback発生時刻 createdTime issuedTime YYYY-MM-DDThh:mm:ssTZD形式
    リッチメニュー名 richMenuName richmenuName
    プレビュー画像の URL previewUrl previewImageUrl Image
    元画像のURL resourceUrl originalContentUrl Image
    ファイルアップロードで取得したID resourceId fileId Image
    カバーデータ背景画像のファイルID coverData.fileId coverData.backgroundFileId List Template
    カバーデータ背景画像のURL coverData.backgroundImage coverData.backgroundImageUrl List Template
    アイテム画像のURL elements[].image elements[].originalContentUrl List Template
    多言語のカバーデータ背景画像のURLリスト coverData.i18nBackgroundImages[] coverData.i18nBackgroundImageUrls[] List Template
    カバーデータの言語コード coverData.i18nBackgroundImages[].language coverData.i18nBackgroundImageUrls[].language List Template
    カバーデータ背景画像のURL coverData.i18nBackgroundImages[].backgroundImage coverData.i18nBackgroundImageUrls[].backgroundImageUrl List Template
    多言語のアイテムの画像URLリスト elements[].i18nImages[] elements[].i18nOriginalContentUrls[] List Template
    多国語の言語コード elements[].i18nImages[].language elements[].i18nOriginalContentUrls[].language List Template
    アイテム画像のURL elements[].i18nImages[].image elements[].i18nOriginalContentUrls[].originalContentUrl List Template
    多言語のアイテム画像のリソースIDリスト elements[].resourceIds[] elements[].i18nFileIds[] List Template
    多言語のアイテム画像の言語コード elements[].resourceIds[].language elements[].i18nFileIds[].language List Template
    画像URL columns[].thumbnailImageUrl columns[].originalContentUrl Carousel
    画像のリソースID columns[].thumbnailImageResourceId columns[].fileId Carousel
    多言語の画像URLリスト columns[].i18nThumbnailImageUrls[] columns[].i18nOriginalContentUrls[] Carousel
    多言語の言語コード columns[].i18nThumbnailImageUrls[].language columns[].i18nOriginalContentUrls[].language Carousel
    画像URL columns[].i18nThumbnailImageUrls[].thumbnailImageUrl columns[].i18nOriginalContentUrls[].originalContentUrl Carousel
    多言語の画像のリソースIDリスト columns[].i18nThumbnailImageResourceIds[] columns[].i18nFileIds[] Carousel
    多言語の画像の言語コード columns[].i18nThumbnailImageResourceIds[].language columns[].i18nFileIds[].language Carousel
    画像のリソースID columns[].i18nThumbnailImageResourceIds[].thumbnailImageResourceId columns[].i18nFileIds[].fileId Carousel
    画像URL columns[].imageUrl columns[].originalContentUrl Image Carousel
    画像のリソースID columns[].imageResourceId columns[].fileId Image Carousel
    多言語の画像URLリスト columns[].i18nImageUrls[] columns[].i18nOriginalContentUrls[] Image Carousel
    多言語の言語コード columns[].i18nImageUrls[].language columns[].i18nOriginalContentUrls[].language Image Carousel
    画像URL columns[].i18nImageUrls[].imageUrl columns[].i18nOriginalContentUrls[].originalContentUrl Image Carousel
    多言語の画像のリソースIDリスト columns[].i18nImageResourceIds[] columns[].i18nFileIds[] Image Carousel
    多言語の画像の言語コード columns[].i18nImageResourceIds[].language columns[].i18nFileIds[].language Image Carousel
    画像のリソースID columns[].i18nImageResourceIds[].imageResourceId columns[].i18nFileIds[].fileId Image Carousel
    元ファイルがあるURL resourceUrl originalContentUrl File
    コンテンツアップロード後に取得したリソース ID resourceId fileId File