Thiết lập Webhooks cho Instagram

Với Webhooks cho Instagram, bạn có thể nhận được thông báo trong thời gian thực mỗi khi có người bình luận về đối tượng File phương tiện của người dùng ứng dụng; @nhắc đến người dùng ứng dụng; hoặc khi Tin của người dùng ứng dụng hết hạn.

Nhận thông báo webhook trực tiếp

Để nhận được thông báo webhook trực tiếp, bạn phải đáp ứng các điều kiện sau:

Ứng dụng của bạn phải từng đặt cấu hình webhooks cho Instagram và đăng ký các trường thích hợp trong Bảng điều khiển ứng dụng.
Ứng dụng dành cho Người tiêu dùng phải ở Chế độ chính thức.
Ứng dụng kinh doanh phải có các quyền ở cấp độ Quyền truy cập nâng cao. Bạn có thể yêu cầu Quyền truy cập nâng cao cho các quyền như minh họa bên dưới:

Nếu quyền của ứng dụng không có cấp độ truy cập là Quyền truy cập nâng cao thì ứng dụng đó sẽ không nhận được thông báo webhook.

Người dùng ứng dụng phải từng cấp cho ứng dụng của bạn các quyền thích hợp (instagram_manage_insights đối với Tin, instagram_manage_comments đối với Bình luận và Lượt @nhắc đến).
Trang đã kết nối với tài khoản của người dùng ứng dụng phải từng bật hoạt động đăng ký Trang.
Doanh nghiệp đã kết nối với Trang của người dùng ứng dụng phải được xác minh.
Đối tượng File phương tiện có bình luận hoặc lượt @nhắc đến phải thuộc về chủ sở hữu có tài khoản không ở chế độ riêng tư.

Các giới hạn

Thông báo webhook cho Bình luận về album sẽ không có ID album. Để lấy ID album, hãy truy vấn ID bình luận trong webhook và yêu cầu trường media.
Các ứng dụng sẽ không nhận được thông báo webhook nếu File phương tiện có bình luận hoặc lượt @nhắc đến là do tài khoản riêng tư tạo.
Số liệu thông tin chi tiết về tin có số lượng dưới 5 sẽ được trả về là -1.
Các ứng dụng chỉ nhận được thông báo webhook khi có bình luận về File phương tiện trên Instagram trong buổi phát trực tiếp nếu file phương tiện đó đang được phát.
Reels không được hỗ trợ.
Ứng dụng của bạn phải hoàn tất thành công quy trình Xét duyệt ứng dụng (quyền truy cập nâng cao) để nhận được thông báo webhooks cho các trường webhooks comments và live_comments.

Bước 1: Tạo điểm cuối

Tạo một điểm cuối có thể chấp nhận và xử lý webhook. Khi đặt cấu hình, hãy chọn đối tượng API Đồ thị trên Instagram, nhấp vào Thiết lập rồi đăng ký một hoặc nhiều trường trên Instagram.

Trường trên Instagram

Trường	Mô tả	Các quyền cần có
`comments`	Bình luận về File phương tiện trên Instagram do người dùng Instagram trong ứng dụng của bạn sở hữu. Hệ thống sẽ trả về `ad_id` và `ad_title` trong đối tượng file phương tiện khi người dùng bình luận về bài viết được quảng cáo trên Instagram hoặc bài viết quảng cáo trên Instagram. Việc này có thể dẫn đến thông báo webhook trùng lặp.	instagram_manage_comments pages_manage_metadata pages_read_engagementhoặc pages_show_list
`live_comments`	Bình luận về File phương tiện trên Instagram trong buổi phát trực tiếp do người dùng Instagram trong ứng dụng của bạn sở hữu.	instagram_manage_comments pages_manage_metadata pages_read_engagementhoặc pages_show_list
`mentions`	Lượt @nhắc đến người dùng Instagram trong ứng dụng của bạn trong một bình luận.	instagram_manage_comments pages_manage_metadata pages_read_engagementhoặc pages_show_list
`story_insights`	Số liệu mô tả lượt tương tác với tin. Được gửi 1 giờ sau khi tin hết hạn.	instagram_manage_insights pages_manage_metadata pages_read_engagementhoặc pages_show_list

Bước 2: Bật hoạt động đăng ký Trang

Ứng dụng của bạn phải bật hoạt động đăng ký Trang trên Trang đã kết nối với tài khoản của người dùng ứng dụng bằng cách gửi yêu cầu POST đến cạnh Ứng dụng đã đăng ký trên Trang và đăng ký bất kỳ trường nào trên Trang.

Các yêu cầu đối với điểm cuối

Mã truy cập Trang của người dùng ứng dụng
pages_manage_metadata

Cú pháp yêu cầu

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

Thông số yêu cầu

Phần giữ chỗ giá trị	Mô tả giá trị
`{page_id}`	ID của Trang đã kết nối với tài khoản của người dùng ứng dụng.
`{access_token}`	Mã truy cập Trang của người dùng ứng dụng.
`{fields}`	Một trường trên Trang (ví dụ: `feed`).

Ứng dụng của bạn sẽ không nhận được thông báo về những thay đổi đối với trường, trừ khi bạn đặt cấu hình hoạt động đăng ký Trang trong Bảng điều khiển ứng dụng và đăng ký trường đó.

Yêu cầu mẫu

curl -i -X POST \
  "https://graph.facebook.com/v19.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."

Phản hồi mẫu

{
  "success": true
}

Cách dùng phổ biến

Thu thập thông tin chi tiết về Tin

Nếu bạn đăng ký trường story_insights, chúng tôi sẽ gửi cho điểm cuối của bạn một thông báo webhook chứa số liệu tương tác của người dùng với tin sau khi tin hết hạn.

Phần tải dữ liệu mẫu cho thông tin chi tiết về Tin

[
  {
    "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"
  }
]

Trả lời lượt @nhắc đến trong bình luận

Nếu bạn đăng ký trường mentions, chúng tôi sẽ gửi cho điểm cuối của bạn một thông báo webhook mỗi khi người dùng Instagram @nhắc đến Tài khoản kinh doanh hoặc Tài khoản người sáng tạo nội dung trên Instagram trong bình luận hoặc chú thích.

Ví dụ: dưới đây là phần tải dữ liệu mẫu cho thông báo webhook về bình luận được gửi cho một Tài khoản kinh doanh trên Instagram (17841405726653026):

Phần tải dữ liệu mẫu cho lượt @nhắc đến trong bình luận

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

Lấy nội dung bình luận

Để lấy nội dung bình luận, hãy sử dụng thuộc tính comment_id để truy vấn cạnh GET /{ig-user-id}/mentioned_comment:

Truy vấn mẫu

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

Phản hồi mẫu

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

Phân tích cú pháp phần tải dữ liệu và phản hồi

Khi bạn lấy được phản hồi, hãy phân tích cú pháp phần tải dữ liệu cho thuộc tính text để xác định xem bạn có muốn phản hồi bình luận hay không. Nếu bạn muốn phản hồi, hãy sử dụng các giá trị thuộc tính caption_id và media_id của phần tải dữ liệu thông báo webhook để truy vấn điểm cuối POST /{ig-user-id}/mentions:

Truy vấn mẫu

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"

Phản hồi mẫu

{
  "id": "17911496353086895"
}

Trả lời lượt @nhắc đến trong chú thích

Nếu bạn đăng ký trường mentions, chúng tôi sẽ gửi cho điểm cuối của bạn một thông báo webhook mỗi khi người dùng @nhắc đến Tài khoản kinh doanh hoặc Tài khoản người sáng tạo nội dung trên Instagram trong bình luận hoặc chú thích trên đối tượng file phương tiện không thuộc sở hữu của Doanh nghiệp hoặc Người sáng tạo nội dung đó.

Ví dụ: dưới đây là thông báo webhook mẫu về lượt @nhắc đến trong chú thích được gửi cho một Tài khoản kinh doanh trên Instagram (17841405726653026):

Thông báo webhook mẫu về lượt @nhắc đến trong chú thích

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

Lấy nội dung chú thích

Để lấy nội dung chú thích, hãy sử dụng thuộc tính media_id để truy vấn cạnh GET /{ig-user-id}/mentioned_media:

Truy vấn mẫu

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

Phản hồi mẫu

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

Phân tích cú pháp phần tải dữ liệu và phản hồi

Khi bạn lấy được phản hồi, hãy phân tích cú pháp phần tải dữ liệu cho thuộc tính caption để xác định xem bạn có muốn phản hồi bình luận hay không. Nếu bạn muốn phản hồi, hãy sử dụng thuộc tính media_id của webhook để truy vấn cạnh POST /{ig-user-id}/mentions:

Truy vấn mẫu

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

Phản hồi mẫu

{
  "id": "17911496353086895"
}