Instagramプラットフォーム

以下のコンテンツは、Webhooks製品ドキュメントの一部です。Webhooksにあまり詳しくない場合は、Webhooksのドキュメントを参照してください。

Instagram用のWebhooksの設定

Instagram用Webhooksを使用すると、誰かがアプリユーザーのメディアオブジェクトにコメントしたり、アプリユーザーを@メンションしたり、アプリユーザーのストーリーズが期限切れになったりした際に、リアルタイムで通知を受け取ることができます。

ライブWebhooksの通知を受け取る

ライブWebhooksの通知を受け取るには、次の条件を満たしていなければなりません。

  • アプリでInstagram Webhooksを設定し、アプリダッシュボードで適切なフィールドをサブスクリプション登録する必要があります。
  • 消費者アプリの場合、ライブモードでなければなりません。
  • ビジネスアプリの場合、Advanced Accessレベルのアクセス許可が必要です。アクセス許可のAdvanced Accessは次に示すようにしてリクエストできます。

アプリアクセス許可にAdvanced Accessのアクセスレベルがない場合、アプリはWebhooks通知を受け取ることができません。

  • アプリユーザーは、アプリに適切なアクセス許可(ストーリーズの場合はinstagram_manage_insights、コメントや@メンションの場合はinstagram_manage_comments)を付与している必要があります。
  • アプリユーザーのアカウントにリンクするページは、ページサブスクリプションが有効になっている必要があります。
  • アプリユーザーのページに接続されているビジネスは認証を受ける必要があります。
  • コメントまたは@mentionが表示されるメディアオブジェクトの所有者のアカウントは、非公開ではない設定になっていなければなりません。

制限

  • アルバムへのコメントに関するWebhooksの通知には、アルバムIDが含まれません。アルバムIDを取得するには、Webhooksに含まれるコメントIDをクエリし、そのmediaフィールドをリクエストします。
  • コメントまたは@メンションが表示されるメディアが非公開アカウントによって作成されている場合、アプリはWebhook通知を受け取りません。
  • 件数が5件未満のストーリーズインサイト指標は、-1として返されます。
  • IGメディアが配信されている場合、アプリはライブIGメディアに対するコメントのWebhooks通知だけを受け取ります。
  • リールはサポートされていません。
  • commentsとlive_commentsのWebhooksフィールドに関するWebhooks通知を受け取るには、アプリがアプリレビュー(アドバンスアクセス)を完了し、合格していなければなりません。
  • メディアがダイナミック広告に使用されている場合、広告IDは返されません。

ステップ1: エンドポイントを作成する

Webhooksを受け入れて処理するエンドポイントを作成します。構成中、InstagramグラフAPIオブジェクトを選択し、[設定]をクリックし、1つ以上のInstagramフィールドをサブスクリプション登録します。

Instagramフィールド

フィールド説明必要なアクセス許可

comments

アプリのInstagramユーザーが所有するIGメディアへのコメント。

宣伝のInstagram投稿やInstagram広告投稿にコメントが付けられると、ad_id、ad_title、およびoriginal_media_idがメディアオブジェクトで返されます。

live_comments

アプリのInstagramユーザーが所有するライブIGメディアに対するコメント。

mentions

コメント内の、アプリのInstagramユーザーへの@メンション。

story_insights

ストーリーズでのインタラクションに関する指標。ストーリーズの期限が切れてから1時間後に送信されます。

ステップ2: ページサブスクリプションを有効にする

アプリは、アプリユーザーのアカウントにリンクされているページで、ページサブスクリプションを有効にする必要があります。そのためには、ページサブスクライブアプリエッジにPOSTリクエストを送信して、任意のページフィールドをサブスクリプション登録します。

エンドポイントの要件

リクエストの構文

POST /{page-id}/subscribed_apps
  ?access_token={access-token}
  &subscribed_fields={fields}

リクエストのパラメーター

値のプレースホルダー 値の説明

{page_id}

アプリユーザーのアカウントにリンクされているページのID。

{access_token}

アプリユーザーのページアクセストークン。

{fields}

ページフィールド(例: feed)。

アプリダッシュボードでページサブスクリプションを構成して、フィールドをサブスクリプション登録しない限り、アプリはそのフィールドの変更の通知を受け取りません。

リクエストの例

curl -i -X POST \
  "https://graph.facebook.com/v21.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."
応答の例
{
  "success": true
}

一般的な用途

ストーリーズインサイトのキャプチャ

story_insightsフィールドをサブスクリプション登録すると、ストーリーズが期限切れになった後に、ストーリーズのユーザーインタラクションの指標を含むWebhooks通知がエンドポイントに送信されます。

ストーリーズインサイトペイロードのサンプル

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "story_insights",
            "value": {
              "media_id": "18023345989012587",
              "exits": 1,
              "replies": 0,
              "reach": 17,
              "taps_forward": 12,
              "taps_back": 0,
              "impressions": 28
            }
          }
        ],
        "id": "17841405309211844",  // Instagram Business or Creator Account ID
        "time": 1547687043
      }
    ],
    "object": "instagram"
  }
]

コメントでの@メンションへの返信

mentionsフィールドをサブスクリプション登録すると、InstagramユーザーがコメントやキャプションでInstagramビジネスアカウントまたはクリエイターアカウントを@メンションするたびに、Webhooks通知がエンドポイントに送信されます。

例えば、以下はInstagramビジネスアカウントに送信されるコメントWebhooks通知ペイロードのサンプルです(17841405726653026)。

コメントでの@メンションのペイロードのサンプル

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "comment_id": "17894227972186120",
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

コメントの内容の取得

コメントの内容を取得するには、comment_idプロパティを使用してGET /{ig-user-id}/mentioned_commentエッジに対してクエリを実行します。

サンプルクエリ

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_comment.comment_id(17894227972186120)

応答の例

{
  "mentioned_comment": {
    "timestamp": "2018-03-20T00:05:29+0000",
    "text": "@bluebottle challenge?",
    "id": "17894227972186120"
  },
  "id": "17841405726653026"
}

ペイロードの解析と返信

応答を取得したら、textプロパティのペイロードを解析して、コメントに返信するかどうかを判断します。返信するには、Webhooks通知ペイロードのcaption_idおよびmedia_idプロパティ値を使用して、POST /{ig-user-id}/mentionsエンドポイントに対してクエリを実行します。

クエリの例

curl -i -X POST \
  -d "comment_id=17894227972186120" \
  -d "media_id=17918195224117851" \
  -d "message=Challenge%20accepted!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

応答の例

{
  "id": "17911496353086895"
}

キャプションでの@メンションへの返信

mentionsフィールドをサブスクリプション登録すると、ビジネスまたはクリエイターが所有していないメディアオブジェクトのコメントやキャプションで、ユーザーがInstagramビジネスアカウントまたはクリエイターアカウントを@メンションするたびに、Webhooks通知がエンドポイントに送信されます。

例えば、以下はInstagramビジネスアカウントに送信されるキャプションでの@メンションWebhooks通知のサンプルです(17841405726653026)。

キャプションでの@メンションのWebhooks通知のサンプル

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

キャプションの内容の取得

キャプションの内容を取得するには、media_idプロパティを使用してGET /{ig-user-id}/mentioned_mediaエッジに対してクエリを実行します。

クエリの例

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_media.media_id(17918195224117851){caption,media_type}

応答の例

{
  "mentioned_media": {
    "caption": "@bluebottle There can be only one!",
    "media_type": "IMAGE",
    "id": "17918195224117851"
  },
  "id": "17841405726653026"
}

ペイロードの解析と返信

応答を取得したら、captionプロパティのペイロードを解析して、コメントに回答するかどうかを判断します。返信するには、Webhooksmedia_idプロパティを使用して、POST /{ig-user-id}/mentionsエッジに対してクエリを実行します。

クエリの例

curl -i -X POST \
  -d "media_id=17918195224117851" \
  -d "message=MacLeod%20agrees!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

応答の例

{
  "id": "17911496353086895"
}