Đăng nội dung

Bạn có thể sử dụng API Đồ thị trên Instagram để đăng một hình ảnh, video, thước phim (tức là bài viết có một file phương tiện) hoặc bài viết chứa nhiều hình ảnh và video (bài viết quay vòng) lên tài khoản Công việc trên Instagram.

Kể từ ngày 01/07/2023, tất cả video đơn lẻ trên bảng feed được đăng qua API Đăng nội dung lên Instagram sẽ được chia sẻ dưới dạng thước phim.

Yêu cầu

Mã truy cập

Tất cả yêu cầu phải có mã truy cập dành cho Người dùng của người dùng ứng dụng.

Quyền

Dưới đây là những quyền mà bạn cần có để đăng nội dung. Các điểm cuối mà ứng dụng của bạn dùng sẽ quyết định chính xác những quyền bạn cần có. Hãy xem tài liệu tham khảo về điểm cuối của chúng tôi để xác định những quyền mà mỗi điểm cuối yêu cầu.

Nếu người dùng ứng dụng là những người không có vai trò trong ứng dụng hoặc không có vai trò trong Doanh nghiệp đã xác nhận quyền sở hữu ứng dụng, bạn phải yêu cầu phê duyệt từng quyền thông qua quy trình Xét duyệt ứng dụng thì họ mới có thể cấp quyền cho ứng dụng của bạn.

Máy chủ công khai

Chúng tôi sẽ gửi file phương tiện mà bạn dùng cho các lần đăng trong yêu cầu cURL. Vì thế, file phương tiện đó phải nằm trên máy chủ có thể truy cập công khai vào thời điểm đăng.

Ủy quyền đăng trên Trang

Bạn chỉ có thể đăng lên các tài khoản Công việc trên Instagram kết nối với Trang cần Ủy quyền đăng trên Trang (PPA) khi đã hoàn tất quy trình PPA này.

Người dùng ứng dụng có thể thực hiện Tác vụ trên Trang mà ban đầu không cần PPA nhưng sau đó lại cần. Trong trường hợp này, người dùng ứng dụng chỉ có thể đăng nội dung lên tài khoản Công việc trên Instagram của mình khi đã hoàn tất PPA. Vì không có cách nào để bạn xác định xem Trang của người dùng ứng dụng có yêu cầu PPA hay không, bạn nên khuyên người dùng ứng dụng hoàn tất quy trình PPA trước.

Giới hạn

Định dạng hình ảnh duy nhất được hỗ trợ là JPEG. Các định dạng JPEG mở rộng như MPO và JPS không được hỗ trợ.
Thẻ mua sắm không được hỗ trợ.
Thẻ nội dung có thương hiệu không được hỗ trợ.
Bộ lọc không được hỗ trợ.
Tính năng Đăng lên Instagram TV không được hỗ trợ.

Để biết các giới hạn khác, hãy xem tài liệu tham khảo của từng điểm cuối.

Giới hạn tốc độ

Mỗi tài khoản Instagram chỉ có thể đăng 50 bài viết qua API trong vòng 24 giờ liên tục. Thẻ quay vòng được tính là một bài viết. Giới hạn này được thực thi đối với điểm cuối POST /{ig-user-id}/media_publish khi cố đăng vùng chứa file phương tiện. Ứng dụng của bạn cũng nên thực thi giới hạn tốc độ đăng này, đặc biệt nếu ứng dụng đó cho phép người dùng ứng dụng lên lịch đăng bài trong tương lai.

Để kiểm tra mức sử dụng giới hạn tốc độ hiện tại của một tài khoản Công việc trên Instagram, hãy truy vấn điểm cuối GET /{ig-user-id}/content_publishing_limit.

Điểm cuối

API này bao gồm các điểm cuối dưới đây. Hãy xem tài liệu tham khảo của từng điểm cuối để biết các yêu cầu về cách sử dụng.

POST /{ig-user-id}/media - tải file phương tiện lên và tạo vùng chứa file phương tiện.
POST /{ig-user-id}/media_publish - đăng file phương tiện đã tải lên bằng vùng chứa file phương tiện đó.
GET /{ig-container-id}?fields=status_code - kiểm tra điều kiện và trạng thái đăng vùng chứa file phương tiện.
GET /{ig-user-id}/content_publishing_limit - kiểm tra mức sử dụng giới hạn tốc độ đăng hiện tại của người dùng ứng dụng.

Bài viết có một file phương tiện

Quy trình đăng một hình ảnh, video, tin hoặc thước phim gồm 2 bước:

Dùng điểm cuối POST /{ig-user-id}/media để tạo một vùng chứa từ hình ảnh hoặc video được lưu trữ trên máy chủ công khai của bạn.
Dùng điểm cuối POST /{ig-user-id}/media_publish để đăng vùng chứa đó.

Bước 1/2: Tạo vùng chứa

Giả sử bạn muốn đăng một hình ảnh trên...

https://www.example.com/images/bronz-fonz.jpg

... kèm chú thích là hashtag "#BronzFonz". Gửi yêu cầu đến điểm cuối POST /{ig-user-id}/media:

Yêu cầu mẫu

POST https://graph.facebook.com/v19.0/17841400008460056/media
  ?image_url=https://www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

Yêu cầu này sẽ trả về một ID vùng chứa cho hình ảnh.

Phản hồi mẫu

{
  "id": "17889455560051444"  // IG Container ID
}

Bước 2/2: Đăng vùng chứa

Dùng điểm cuối POST /{ig-user-id}/media_publish để đăng ID vùng chứa được trả về ở bước trước.

Yêu cầu mẫu

POST https://graph.facebook.com/v19.0/17841400008460056/media_publish ?creation_id=17889455560051444

Phản hồi mẫu

{
  "id": "17920238422030506" // IG Media ID
}

Bài viết quay vòng

Bạn có thể đăng tối đa 10 hình ảnh, video hoặc kết hợp cả hai trong một bài viết (bài viết quay vòng). Quy trình đăng thẻ quay vòng gồm 3 bước:

Dùng điểm cuối POST /{ig-user-id}/media để tạo vùng chứa mục riêng cho từng hình ảnh và video sẽ xuất hiện trong thẻ quay vòng.
Dùng điểm cuối POST /{ig-user-id}/media một lần nữa để tạo một vùng chứa thẻ quay vòng cho các mục.
Dùng điểm cuối POST /{ig-user-id}/media_publish để đăng vùng chứa thẻ quay vòng đó.

Bài viết quay vòng được tính là một bài viết theo giới hạn tốc độ của tài khoản.

Giới hạn

Không thể quảng cáo thẻ quay vòng.
Thẻ quay vòng chỉ được chứa tối đa 10 hình ảnh, video hoặc kết hợp cả hai.
Hình ảnh quay vòng đều được cắt theo hình ảnh đầu tiên trong thẻ quay vòng, với tỷ lệ khung hình mặc định là 1:1.

Bước 1/3: Tạo vùng chứa mục

Dùng điểm cuối POST /{ig-user-id}/media để tạo một vùng chứa mục cho hình ảnh hoặc video sẽ xuất hiện trong thẻ quay vòng. Thẻ quay vòng có thể chứa tổng cộng tối đa 10 hình ảnh, video hoặc kết hợp cả hai.

POST /{ig-user-id}/media

Thông số

Dưới đây là những thông số bắt buộc. Hãy xem tài liệu tham khảo về điểm cuối POST /{ig-user-id}/media để biết các thông số được hỗ trợ khác.

is_carousel_item - Đặt là true. Cho biết hình ảnh hoặc video sẽ xuất hiện trong thẻ quay vòng.
image_url - (chỉ hình ảnh) Đường dẫn đến hình ảnh. Chúng tôi sẽ gửi hình ảnh của bạn trong yêu cầu cURL bằng URL đã chuyển vào. Vì thế, hình ảnh đó phải nằm trên máy chủ công khai.
media_type - (chỉ video) Đặt là VIDEO. Cho biết file phương tiện là video.
video_url - (chỉ video) Đường dẫn đến video. Chúng tôi sẽ gửi video của bạn trong yêu cầu cURL bằng URL đã chuyển vào. Vì thế, video đó phải nằm trên máy chủ công khai.

Nếu thao tác này thành công, API sẽ trả về một ID vùng chứa mục mà bạn có thể dùng khi tạo vùng chứa thẻ quay vòng.

Lặp lại quy trình này cho từng hình ảnh hoặc video sẽ xuất hiện trong thẻ quay vòng.

Yêu cầu mẫu

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."

Phản hồi mẫu

{
  "id": "17899506308402767"
}

Bước 2/3: Tạo vùng chứa thẻ quay vòng

Dùng điểm cuối POST /{ig-user-id}/media để tạo một vùng chứa thẻ quay vòng.

POST /{ig-user-id}/media

Thông số

Dưới đây là những thông số bắt buộc. Hãy xem tài liệu tham khảo về điểm cuối POST /{ig-user-id}/media để biết thêm các thông số được hỗ trợ.

media_type - Đặt là CAROUSEL. Cho biết vùng chứa dành cho thẻ quay vòng.
children - Mảng gồm tối đa 10 ID vùng chứa của mỗi hình ảnh và video sẽ xuất hiện trong thẻ quay vòng đã đăng. Thẻ quay vòng có thể chứa tổng cộng tối đa 10 hình ảnh, video hoặc kết hợp cả hai.

Yêu cầu mẫu

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."

Phản hồi mẫu

{
  "id": "18000748627392977"
}

Bước 3/3: Đăng vùng chứa thẻ quay vòng

Dùng điểm cuối POST /{ig-user-id}/media_publish để đăng vùng chứa thẻ quay vòng (bài viết quay vòng). Mỗi tài khoản chỉ có thể đăng 50 bài viết trong vòng 24 giờ. Mỗi lần đăng thẻ quay vòng được tính là một bài viết.

POST /{ig-user-id}/media_publish

Thông số

Dưới đây là những thông số bắt buộc.

creation_id - ID vùng chứa thẻ quay vòng.

Nếu thao tác này thành công, API sẽ trả về ID File phương tiện trên Instagram trong album quay vòng.

Yêu cầu mẫu

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."

Phản hồi mẫu

{
  "id": "90010778390276"
}

Bài viết có thước phim

Thước phim là những video ngắn đủ điều kiện hiển trị trong tab Reels của ứng dụng Instagram nếu đáp ứng một số quy cách và được thuật toán của chúng tôi chọn. Nếu bạn muốn đăng một thước phim, hãy làm theo các bước đăng bài viết có một file phương tiện và thêm thông số media_type=REELS cùng với đường dẫn đến video bằng thông số video_url.

Thước phim không phải là một loại file phương tiện mới, ngay cả khi bạn đặt media_type=REELS khi đăng thước phim. Nếu bạn đăng thước phim rồi yêu cầu trường media_type của thước phim đó, giá trị được trả về sẽ là VIDEO. Để xác định xem một video đã đăng có được chỉ định là thước phim hay không, hãy yêu cầu trường media_product_type của video đó.

Bạn có thể sử dụng mã mẫu trên GitHub (insta_reels_publishing_api_sample) để tìm hiểu cách đăng Thước phim lên Instagram.

Để thuận tiện hơn cho nhà phát triển, Meta đã phát hành bộ lệnh gọi API Đồ thị đầy đủ dành cho Instagram Reels trên Nền tảng API Postman. Để biết thêm thông tin, hãy xem bài viết Bộ sưu tập Postman dành cho Facebook Reels và Instagram Reels.

Để biết thêm thông tin về Reels, hãy xem Tài liệu dành cho nhà phát triển Reels.

Bài viết có tin

Hiện tại, chỉ tài khoản kinh doanh mới có thể đăng tin bằng API Đăng nội dung.

Tin là các video và hình ảnh được đăng dưới dạng tin trên Instagram. Nếu bạn muốn đăng tin, hãy làm theo các bước tương tự như khi đăng bài viết có một file phương tiện và thêm thông số media_type=STORIES cùng với đường dẫn đến hình ảnh/video bằng thông số image_url hoặc video_url.

Lưu ý: Tin không phải là một loại file phương tiện mới, kể cả bạn đang đặt media_type=STORIES khi đăng tin. Nếu bạn đăng tin rồi yêu cầu trường media_type của tin đó, giá trị này sẽ được trả về dưới dạng IMAGE/VIDEO. Để xác định xem một hình ảnh/video đã đăng có được chỉ định là tin hay không, hãy yêu cầu trường media_product_type của hình ảnh/video đó.

Thẻ cộng tác viên

Bạn có thể thêm người dùng Instagram công khai vào một hình ảnh, thẻ quay vòng và thước phim với vai trò cộng tác viên. Họ sẽ nhận được lời mời làm cộng tác viên cho file phương tiện cụ thể đó. Để gắn thẻ người dùng trong một hình ảnh, hãy làm theo các bước trong quy trình đăng Bài viết có một file phương tiện ở trên. Tuy nhiên, khi tạo vùng chứa file phương tiện, hãy thêm thông số cộng tác viên và một mảng gồm các chuỗi biểu thị tên người dùng Instagram của những người dùng mà bạn muốn mời làm cộng tác viên trên file phương tiện.

Yêu cầu mẫu

POST graph.facebook.com/17841400008460056/media
?image_url=https://www.example.com/images/bronzed-fonzes.jpg
&caption=#BronzedFonzes!
&collaborators= [‘username1’,’username2’]

Lưu ý

Giá trị cộng tác viên phải là một mảng gồm các chuỗi.
Bạn chỉ có thể gắn thẻ những người dùng có tài khoản Instagram công khai.
Bạn có thể thêm tối đa 3 cộng tác viên vào một file phương tiện.
Bạn không thể thêm cộng tác viên vào file phương tiện của Tin.

Thẻ vị trí

Bạn có thể sử dụng API Tìm kiếm Trang và đừng quên thêm trường "location" vào truy vấn để tìm kiếm những Trang có tên khớp với một chuỗi tìm kiếm. Sau đó, hãy phân tích cú pháp kết quả để xác định bất kỳ Trang nào đã được tạo cho một vị trí thực. Nếu bạn thêm ID của Trang khi đăng hình ảnh hoặc video, hình ảnh hoặc video này sẽ được gắn thẻ thông tin vị trí liên kết với Trang đó.

Giới hạn

Trang phải có dữ liệu vị trí (gồm vĩ độ và kinh độ) thì mới đủ điều kiện gắn thẻ.

Hãy xác minh rằng Trang bạn muốn sử dụng có dữ liệu kinh độ và vĩ độ trong phản hồi. Nếu bạn cố tạo vùng chứa bằng Trang không có dữ liệu vị trí, hệ thống sẽ báo lỗi và trả về ngoại lệ được mã hóa INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID.

Sau khi bạn có ID Trang, hãy chỉ định ID này cho thông số location_id khi đăng vùng chứa mục cho một file phương tiện hoặc thẻ quay vòng.

Thẻ sản phẩm

Bạn có thể đăng cả bài viết có một file phương tiện và bài viết quay vòng được gắn thẻ sản phẩm trong tính năng Mua sắm trên Instagram. Hãy tham khảo hướng dẫn Gắn thẻ sản phẩm để tìm hiểu cách thực hiện.

Thẻ người dùng

Bạn có thể gắn thẻ người dùng Instagram công khai trong hình ảnh và họ sẽ nhận được thông báo rằng họ đã được gắn thẻ.

Để gắn thẻ người dùng trong hình ảnh, hãy làm theo các bước trong quy trình đăng Bài viết có một file phương tiện ở trên. Tuy nhiên, khi tạo vùng chứa file phương tiện, hãy thêm thông số user_tags và mảng đối tượng chỉ ra người dùng Instagram cũng như tọa độ x/y của họ trong hình ảnh.

Yêu cầu mẫu

POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &user_tags= [ { username:'kevinhart4real', x: 0.5, y: 0.8 }, { username:'therock', x: 0.3, y: 0.2 } ]

Yêu cầu này sẽ trả về một ID vùng chứa. Sau đó, bạn có thể đăng ID vùng chứa này thông qua điểm cuối Đăng file phương tiện của người dùng Instagram.

Lưu ý

Giá trị user_tags phải là một mảng đối tượng ở định dạng JSON.
Bạn chỉ có thể gắn thẻ những người dùng có tài khoản Instagram công khai.
Đối với mỗi người dùng, đối tượng phải chứa cả 3 thuộc tính (username, x và y).
Các giá trị x và y phải là số float bắt nguồn từ phía trên cùng bên trái của hình ảnh và nằm trong khoảng 0.0-1.0.
Bạn có thể sử dụng thẻ người dùng cho hình ảnh trong thẻ quay vòng.

Khắc phục sự cố

Nếu bạn có thể tạo vùng chứa cho video nhưng điểm cuối POST /{ig-user-id}/media_publish không trả về ID file phương tiện đã đăng, bạn có thể truy vấn điểm cuối GET /{ig-container-id}?fields=status_code để biết trạng thái đăng của vùng chứa đó. Điểm cuối này sẽ trả về một trong các trạng thái sau:

EXPIRED – Vùng chứa đã hết hạn sau 24 giờ không được đăng.
ERROR - Vùng chứa không thể hoàn tất quá trình đăng.
FINISHED - Vùng chứa và đối tượng file phương tiện của vùng chứa đó đã sẵn sàng đăng.
IN_PROGRESS - Vùng chứa vẫn đang trong quá trình đăng.
PUBLISHED – Đối tượng file phương tiện của vùng chứa đã được đăng.

Bạn nên truy vấn trạng thái của vùng chứa mỗi phút một lần, trong tối đa 5 phút.

Lỗi

Hãy xem tài liệu tham khảo về Mã lỗi.