InstagramメッセージのWebhooks

Webhooksを使うと、Metaソーシャルグラフの特定のオブジェクトに加えられた変更のHTTP通知をリアルタイムで受け取ることができます。例えば、カスタマーからお持ちのInstagramプロアカウントにメッセージが送信されたときに通知を受け取ることができます。Webhooksの通知機能により、メッセージの変更をトラッキングできます。また、変更をトラッキングするためにMessengerプラットフォームのエンドポイントをクエリすると発生してしまうレート制限を回避できます。

要件

InstagramメッセージのWebhooks通知を受け取るには、以下の要件を満たす必要があります。

• instagram_basic、instagram_manage_messages、pages_manage_metadataのアクセス許可
• アプリに対する権限を持たない人が所有または管理するデータが含まれるWebhooks通知を取得するには、アプリにAdvanced Accessが必要

注: 自分のビジネスのすべてのメッセージアプリで、メッセージWebhooksをサブスクリプション登録する必要があります。

アプリモード

• 開発モード – Webhooksが送信されるのは、アプリにアドバンスアクセスがある場合でも、アプリのユーザーにアプリの権限がある場合のみです。自分が所有または管理しているデータにのみアクセスできます。
• ライブモード – アクセスレベルに応じてWebhooksが送信されます。

  • スタンダードアクセス – Webhooksが送信されるのは、アプリのユーザーがアプリに対して権限を持っている場合のみです。自分が所有または管理しているデータにのみアクセスできます。
  • アドバンスアクセス – 前提条件となるアクセス許可が付与されていれば、どのユーザーがアプリを使用していてもWebhooksが送信されます。

詳しくは、アクセスレベル、アプリモード、アプリにおける権限をご覧ください。

制限

• カスタマーがInstagram投稿でカルーセルの画像に対してリアクションしたか、カルーセルの画像を転送した場合、通知に含まれるのはカルーセルの最初の画像であり、カスタマーがリアクションまたは転送した画像とは異なる場合があります。
• シェアがあるメッセージをカスタマーが送信したときの通知に含まれるのは、シェアされたメディアまたは投稿のURLだけです。
• GIFとスタンプ付きのメッセージはサポートされていません。人がGIFやスタンプ付きのメッセージを送信した場合、Webhookはトリガーされず、Webhook通知も送信されません。

Webhookイベント

通知の例

受け取る可能性のあるWebhooks通知のタイプの例を以下に示します。

メッセージ

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID of your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1569262485349,
          "message": {
            "mid": "MESSAGE-ID",   // ID of the message sent to your business
      
            "text": "MESSAGE-TEXT"     // Included when a customer sends a message containing text
      
            "attachments": [           // Included when a customer sends multiple media attachments or a URL for a story mention or share
              {
                "type":"image",             // Can be audio, file, image (image or sticker), share, story_mention, or video
                "payload":{ "url":"LINK" }  
              },
              {
                "type":"video",
                "payload":{ "url":"LINK" }
              }
            ]
      
            "is_deleted": true         // Included when a customer deletes a message
      
            "is_echo": true            // Included when your business sends a message to the customer

            "is_unsupported": true,    // Included when a customer sends a message with unsupported media
      
            "quick_reply": {           // Included when a customer clicks a quick reply
              "payload": "CUSTOMER-RESPONSE-PAYLOAD"   // The payload with the option selected by the customer
            },      
      
            "referral": {              // Included when a customer clicks an Instagram Shop product
              "product": {
                "id": "PRODUCT-ID"
            }      
      
            "referral": {                   // Included when a customer clicks an CTD ad
              "ref": "REF-DATA-IN-AD-IF-SPECIFIED"
              "ad_id": AD-ID,
              "source": "ADS",
              "type": "OPEN_THREAD",
              "ads_context_data": {
                "ad_title": TITLE-FOR-THE-AD,
                "photo_url": IMAGE-URL-THAT-WAS-CLICKED,
                "video_url": THUMBNAIL-URL-FOR-THE-AD-VIDEO,
              }
            }

            "reply_to":{               // Included when a customer sends an inline reply
              "mid":"MESSAGE-ID"
            } 
      
            "reply_to": {               // Included when a customer replies to a story
              "story": {
                "url":"CDN-URL",
                "id":"STORY-ID"       
              }
            }
          }
        }
      ]
    }
  ]
}

メッセージリアクション

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID for your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID for your Instagram Professional account
          },
          "timestamp": 1569262485349,
          "reaction" :{
            "mid" : "MESSAGE-ID",
            "action": "react",    // or unreact
            "reaction": "love", // optional, to unreact if there is no reaction field
            "emoji": "\u{2764}\u{FE0F}" // optional, to unreact if there is no emoji field
          } 
        }
      ]
    }
  ]
}  

メッセージポストバック

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account
      "time": 1502905976963,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1502905976377,
          "postback": {
            "mid":"MESSAGE-ID",           // ID for the message sent to your business
            "title": "SELECTED-ICEBREAKER-REPLY-OR-CTA-BUTTON",
            "payload": "CUSTOMER-RESPONSE-PAYLOAD",  // The payload with the option selected by the customer
          }
        }
      ]
    }
  ]
}

メッセージリファーラル

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account  
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID of your Instagram Professional account
          },
          "timestamp": 1502905976377,
          "referral": {
                 "ref": "INFORMATION-INCLUDED-IN-REF-PARAMETER-OF-IGME-LINK"
                 "source": "IGME-SOURCE-LINK"  
                 "type":  "OPEN_THREAD"  // Only supported for existing conversations 
          }
        }
      ]
    }
  ]
}
  

メッセージ閲覧

{
   "object":"instagram",
   "entry":[
      {
         "id":"IGID",  // ID for your Instagram Professional account
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"IGSID"  // Instagram-scoped ID for the customer who sent the message
               },
               "recipient":{
                  "id":"IGID"  // ID for your Instagram Professional account
               },
               "timestamp":1569262485349,
               "read":{
                  "mid":"MESSAGE-ID"
               }
            }
         ]
      }
   ]
}

参考情報

• Messengerハンドオーバープロトコル – メッセージを処理する複数のアプリがある(例えば、1つのアプリが自動応答を処理し、もう1つのアプリがヒューマンエージェントへのエスカレーションを処理する)場合、1つのアプリから別のアプリにスレッドを渡すハンドオーバープロトコルを実装する必要があります。
• Direct誘導、CTD – Instagram Direct誘導広告の作成について詳しくは、ビジネスヘルプセンターをご覧ください。