MessengerプラットフォームのスレッドAPI

このドキュメントでは、MessengerとInstagramメッセージのスレッドについての情報を取得する方法について説明します。次のものを取得できます。

• FacebookページまたはInstagramプロアカウントのスレッドのリスト
• 各スレッド内のメッセージのリスト
• メッセージの送信日時や送信元など、各メッセージに関する詳細情報

開始する前に

このチュートリアルは、Messengerプラットフォームの概要とInstagramメッセージの概要を読んでいること、および必要なコンポーネントが実装されていることを前提としています。

以下が必要です。

• 該当ビジネスのFacebookページのID、またはInstagramプロアカウントにリンクされているFacebookページのページID
• ページでMESSAGINGタスクまたはMODERATEタスクを実行できる利用者からリクエストされた、ページアクセストークン
• ビジネスと、メッセージアプリの権限を持たない利用者、Instagramプロアカウント、Facebookページ、ビジネスとの間のスレッドにアクセスするにはアドバンスアクセスが必要です

利用者とページの間のMessengerスレッドについては、アプリに次のものが必要です。

• ページでMESSAGINGタスクやMODERATEタスクを実行できる利用者がリクエストしたページアクセストークン
• pages_manage_metadata、pages_read_engagement、pages_messagingのアクセス許可

利用者とInstagramプロアカウントの間のInstagramメッセージスレッドについては、アプリに次のものが必要です。

• InstagramビジネスアカウントにリンクされているページでMESSAGINGタスクを実行できる利用者がリクエストしたページアクセストークン
• instagram_basic、instagram_manage_messages、pages_manage_metadataのアクセス許可
• アプリは、認定されたビジネスが所有するものでなければなりません

制限

• API呼び出しで返されるデータやWebhooks通知には、シェアする画像または動画URLだけしか含まれません。
• メールアドレスや電話番号などのプライベートキーを使ってアカウントがリンクされている場合、これらのアカウント間のスレッドは取得できません。1人のFacebookユーザーと1つのInstagramアカウントの間のスレッドのみ取得できます。この問題は、アプリでアドバンスアクセスが承認されると解決します。Instagramアプリのアカウントセンターで複数のアカウントがリンクされている場合、すべてのリンク済みアカウント間のスレッドを取得できます。
• リクエストフォルダー内にある、30日間アクティブになっていないスレッドは、API呼び出しで返されません。

このAPIを利用すると、アプリにInstagramビジネスアカウントが新たにリンクされたときに、過去のスレッドについて受信箱を同期することができます。

スレッドのリストの取得

スレッドのリストを取得するには、instagramまたはmessengerに設定したplatformパラメーターを指定したGETリクエストを/PAGE-ID/conversationsエンドポイントに送信します。

リクエストの例

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

成功した場合、アプリは、利用者との間のスレッドのIDのリストとメッセージ送信最終日時を含むJSONオブジェクトを受け取ります。

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
} 

特定のユーザーとのスレッドを検索する

InstagramプロアカウントまたはFacebookページと特定の顧客との間のスレッドを取得するには、platformパラメーターと、当該顧客のInstagramスコープIDまたはページスコープIDに設定したuser_idパラメーターを指定して、GETリクエストを/PAGE-ID/conversationsエンドポイントに送信します。

リクエストの例

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

成功すると、アプリはスレッドのIDを受け取ります。

{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
} 

スレッド内のメッセージのリストを取得する

スレッド内のメッセージのリストを取得するには、messagesフィールドを指定したGETリクエストを/CONVERSATION-IDエンドポイントに送信します。

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

成功すると、アプリは、メッセージIDと各メッセージの作成時刻のリストを受け取ります。

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

メッセージに関する情報を入手する

メッセージに関する情報(送信者、受信者、メッセージの内容など)を取得するには、関心のあるフィールドを指定して、GETリクエストを/MESSAGE-IDエンドポイントに送信します。

デフォルトのフィールドはidとcreated_timeです。

注:/CONVERSATION-IDエンドポイントへのクエリは、スレッド内のすべてのメッセージIDを返します。ただし、スレッド内の最新のメッセージ20件の詳細しか取得できません。最新の20件より前のメッセージをクエリした場合は、メッセージが削除されていることを示すエラーが表示されます。

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

成功すると、アプリは次のJSON応答を受け取ります。この例では、顧客はプレーンテキストメッセージをInstagramプロアカウントに送信します。

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

詳しくはこちら

以下のリファレンスをご覧ください。

• スレッドエンドポイント
• スレッドエンドポイント
• メッセージエンドポイント