Instagram용 Webhooks 설정

Instagram용 Webhooks를 사용하면 앱 사용자의 미디어 개체에 댓글을 달거나, 앱 사용자를 @언급하거나, 앱 사용자의 스토리가 만료될 때마다 실시간 알림을 수신할 수 있습니다.

라이브 Webhooks 알림 수신

라이브 Webhooks 알림을 수신하려면 다음 조건을 충족해야 합니다.

앱은 Instagram Webhooks를 구성하고 앱 대시보드에서 적절한 필드를 구독해야 합니다.
소비자 앱은 라이브 모드여야 합니다.
비즈니스 앱은 Advanced Access 수준의 권한이 있어야 합니다. 다음과 같은 권한에 대한 Advanced Access를 요청할 수 있습니다.

앱 권한의 액세스 수준이 Advanced Access가 아닌 경우 앱에 Webhooks 알림이 수신되지 않습니다.

앱 사용자는 앱에 적절한 권한(스토리에는 instagram_manage_insights, 댓글과 @언급에는 instagram_manage_comments)을 부여해야 합니다.
앱 사용자의 계정에 연결된 페이지는 페이지 구독이 활성화되어 있어야 합니다.
앱 사용자의 페이지에 연결된 비즈니스는 인증되어야 합니다.
댓글 또는 @언급이 표시되는 미디어 개체의 소유자는 계정을 비공개로 설정해서는 안 됩니다.

제한 사항

사진첩의 댓글에 대한 Webhooks 알림에는 사진첩 ID가 포함되어 있지 않습니다. 사진첩 ID를 가져오려면 Webhooks에서 댓글 ID를 쿼리하고 media 필드를 요청하세요.
댓글 또는 @언급이 표시된 미디어가 비공개 계정에서 생성된 경우 앱에서 Webhooks 알림이 수신되지 않습니다.
5개 미만의 스토리 인사이트 지표는 -1로 반환됩니다.
앱은 미디어가 방송 중일 때 라이브 IG 미디어의 댓글에 대한 Webhooks 알림만 수신합니다.
릴스는 지원되지 않습니다.
앱이 앱 검수(Advanced Access)를 성공적으로 완료해야 comments 및 live_comments Webhooks 필드에 대한 Webhooks 알림을 받을 수 있습니다.

1단계: 엔드포인트 만들기

Webhoooks를 수락하고 처리하는 엔드포인트를 만듭니다. 구성 중에 Instagram 그래프 API 개체를 선택하고 설정을 클릭한 다음, 하나 이상의 Instagram 필드를 구독합니다.

Instagram 필드

필드	설명	필요한 권한
`comments`	앱의 Instagram 사용자가 소유한 IG 미디어에 대한 댓글입니다. 사용자가 홍보성 Instagram 게시물이나 Instagram 광고 게시물에 댓글을 남기면 미디어 개체에서 `ad_id` 및 `ad_title`이 반환됩니다. 이로 인해 Webhooks 알림에 중복이 있을 수 있습니다.	instagram_manage_comments pages_manage_metadata pages_read_engagement또는 pages_show_list
`live_comments`	앱의 Instagram 사용자가 소유한 라이브 IG 미디어에 대한 댓글입니다.	instagram_manage_comments pages_manage_metadata pages_read_engagement또는 pages_show_list
`mentions`	댓글에 있는 앱의 Instagram 사용자에 대한 @언급입니다.	instagram_manage_comments pages_manage_metadata pages_read_engagement또는 pages_show_list
`story_insights`	스토리에서의 인터랙션을 설명하는 지표. 스토리가 만료되고 1시간 후에 전송됩니다.	instagram_manage_insights pages_manage_metadata pages_read_engagement또는 pages_show_list

2단계: 페이지 구독 활성화

POST 요청을 페이지 구독 앱 에지로 보내고 페이지 필드를 구독하여 앱에서 앱 사용자 계정에 연결된 페이지에 대한 페이지 구독을 활성화해야 합니다.

엔드포인트 요구 사항

앱 사용자의 페이지 액세스 토큰
pages_manage_metadata

요청 구문

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/v19.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 비즈니스 계정(17841405726653026)에 전송되는 댓글 Webhooks 알림 페이로드 샘플은 다음과 같습니다.

댓글 @언급 페이로드 샘플

[
  {
    "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 비즈니스 계정(17841405726653026)에 전송되는 캡션 @언급 Webhooks 알림 샘플은 다음과 같습니다.

캡션 @언급 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 속성에 대해 페이로드를 구문 분석하여 댓글에 답할지 결정합니다. 응답하려면 Webhooks media_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"
}