Bài viết trên Threads

Bạn có thể sử dụng API Threads để đăng bài viết có hình ảnh, bài viết có video, bài viết có văn bản hoặc bài viết quay vòng.

Tài liệu này bao gồm các nội dung sau:

Bài viết một thread

Quy trình đăng một bài viết có hình ảnh/video/văn bản gồm 2 bước:

Dùng điểm cuối POST /{threads-user-id}/threads để tạo một vùng chứa file phương tiện sử dụng hình ảnh hoặc video được lưu trữ trên máy chủ công khai của bạn và văn bản không bắt buộc. Ngoài ra, hãy dùng điểm cuối này để tạo một vùng chứa file phương tiện chỉ có văn bản.
Dùng điểm cuối POST /{threads-user-id}/threads_publish để đăng vùng chứa đó.

Giới hạn

Bài viết có văn bản chỉ được dài tối đa 500 ký tự.

Bước 1: Tạo vùng chứa file phương tiện trên Threads

Dùng điểm cuối POST /{threads-user-id}/threads để tạo một vùng chứa file phương tiện trên Threads.

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 /{threads-user-id}/threads để biết thêm các thông số được hỗ trợ.

is_carousel_item - Giá trị mặc định là false đối với bài viết một thread. Cho biết hình ảnh hoặc video sẽ xuất hiện trong thẻ quay vòng.
image_url - (Chỉ áp dụng cho 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 được cung cấp. Vì thế, hình ảnh đó phải nằm trên máy chủ công khai.
media_type - Đặt là TEXT, IMAGE hoặc VIDEO. Cho biết loại file phương tiện hiện tại. Lưu ý: Loại CAROUSEL không áp dụng cho bài viết một thread.
video_url - (Chỉ áp dụng cho 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 được cung cấp. Vì thế, video đó phải nằm trên máy chủ công khai.
text - Văn bản liên kết với bài viết. URL đầu tiên mà bạn thêm vào trường text sẽ được dùng làm bản xem trước liên kết cho bài viết. Đối với bài viết chỉ có văn bản, thông số này là bắt buộc.

Yêu cầu mẫu

curl -i -X POST \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads?media_type=IMAGE&image_url=https://www.example.com/images/bronz-fonz.jpg&text=#BronzFonz&access_token=<ACCESS_TOKEN>"

Phản hồi mẫu

{
  "id": "1234567" // Threads Media Container ID
}

Bước 2: Đăng vùng chứa file phương tiện trên Threads

Dùng điểm cuối POST /{threads-user-id}/threads_publish để đăng ID vùng chứa được trả về ở bước trước. Bạn nên chờ trung bình 30 giây rồi mới đăng vùng chứa file phương tiện trên Threads để máy chủ của chúng tôi có đủ thời gian xử lý xong quá trình tải lên. Hãy xem phần điểm cuối trạng thái vùng chứa file phương tiện để biết thêm chi tiết.

Thông số

creation_id - Thông tin nhận dạng của vùng chứa file phương tiện trên Threads được tạo từ điểm cuối /threads.

Yêu cầu mẫu

curl -i -X POST \ 
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads_publish?creation_id=<MEDIA_CONTAINER_ID>&access_token=<ACCESS_TOKEN>"

Phản hồi mẫu

{
  "id": "1234567" // Threads Media ID
}

Bài viết quay vòng

Bạn có thể đăng tối đa 20 hình ảnh, video hoặc kết hợp cả hai trong mộ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 /{threads-user-id}/threads để tạo các vùng chứa mục riêng lẻ 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 /{threads-user-id}/threads 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 /{threads-user-id}/threads_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 trang cá nhân.

Giới hạn

Thẻ quay vòng chỉ được chứa tối đa 20 hình ảnh, video hoặc kết hợp cả hai.
Thẻ quay vòng phải có tối thiểu 2 bài viết con.

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

Dùng điểm cuối POST /{threads-user-id}/threads để 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ô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 /{threads-user-id}/threads để biết thêm các thông số được hỗ trợ.

is_carousel_item - Đặt là true. Cho biết rằng hình ảnh hoặc video sẽ xuất hiện trong thẻ quay vòng.
image_url - (Chỉ áp dụng cho 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 - Đặt là IMAGE hoặc VIDEO. Cho biết rằng file phương tiện là một hình ảnh hoặc video.
video_url - (Chỉ áp dụng cho 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.

Lưu ý: Dù text là trường không bắt buộc đối với bài viết quay vòng, URL đầu tiên mà bạn thêm vào trường text sẽ được dùng làm bản xem trước liên kết cho bài viết.

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.threads.net/v1.0/<THREADS_USER_ID>/threads?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=<ACCESS_TOKEN>"

Phản hồi mẫu

{
  "id": "1234567"
}

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

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

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 /{threads-user-id}/threads để biết thêm các thông số được hỗ trợ.

media_type - Đặt là CAROUSEL. Cho biết rằng vùng chứa là dành cho thẻ quay vòng.
children - Danh sách được phân tách bằng dấu phẩy gồm tối đa 20 ID vùng chứa của mỗi hình ảnh và/hoặc 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 thiểu 2 và tối đa 20 hình ảnh/video hoặc kết hợp cả hai.
text - (Không bắt buộc.) Văn bản liên kết với bài viết.

Yêu cầu mẫu

curl -i -X POST \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads?media_type=CAROUSEL&children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>&access_token=<ACCESS_TOKEN>"

Phản hồi mẫu

{
  "id": "1234567"
}

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

Dùng điểm cuối POST /{threads-user-id}/threads_publish để đăng một bài viết quay vòng. Mỗi trang cá nhân chỉ có thể đăng tối đa 250 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.

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 Threads của một album quay vòng.

Yêu cầu mẫu

curl -i -X POST \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads_publish?creation_id=<MEDIA_CONTAINER_ID>&access_token=<ACCESS_TOKEN>"

Phản hồi mẫu

{
  "id": "1234567" // Threads Media ID
}

Thẻ chủ đề và liên kết trong bài viết

Chủ đề và liên kết xuất hiện trong bài viết theo cách giúp khuyến khích tương tác.

Thẻ chủ đề

Chủ đề giúp bài viết mang tính xã hội hơn bằng cách tạo ra các chủ đề thảo luận tập trung. Bạn có thể thêm chủ đề vào bài viết bằng cách sử dụng thông số topic_tag hoặc thêm thẻ trong văn bản của bài viết.

Sử dụng thông số `topic_tag`

Lưu ý: Những ký tự sau đây không được phép xuất hiện trong thẻ chủ đề:

Dấu chấm (.)
Dấu và (&)

curl -i -X POST \  
  "https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads?media_type=TEXT&text=Text&access_token=<ACCESS_TOKEN>"
  -d topic_tag=TAG

Sử dụng thẻ chủ đề trong văn bản

Lưu ý: Phương thức này không được ưu tiên, nhưng được giữ lại để đem lại khả năng tương thích ngược.

Bạn cũng có thể đính kèm một chủ đề vào bài viết bằng cách chèn trực tiếp vào văn bản của bài viết. Chỉ cho phép một thẻ chủ đề trên mỗi bài viết. Vì thế, thẻ hợp lệ đầu tiên mà bạn thêm vào một bài viết thuộc loại bất kỳ (chỉ có văn bản, có hình ảnh, có video, quay vòng) qua API sẽ được xem là thẻ của bài viết đó.

Thông tin cần lưu ý khi thêm thẻ chủ đề vào bài viết bằng cách sử dụng thẻ trong văn bản:

Thẻ hợp lệ bắt đầu bằng dấu thăng (#).
Bạn cũng có thể đặt cấu hình văn bản trong ứng dụng mà không cần dấu thăng.
Dấu thăng mà có số nguyên đứng sau (ví dụ: #1) sẽ không được chuyển thành thẻ. Vì trong trường hợp này, hệ thống giả định rằng # biểu thị một dấu số.
Bạn không được phép sử dụng các ký tự dưới đây khi dùng thẻ trong văn bản với API Threads. Vì vậy, bất kỳ thẻ trong văn bản nào bắt đầu bằng dấu thăng đều sẽ kết thúc trước những ký tự này:
- Khoảng trắng, tab và ký tự xuống dòng
- Dấu chấm (.)
- Dấu và (&)
- Dấu a còng (@)
- Dấu chấm than (!)
- Dấu hỏi chấm (?)
- Dấu phẩy (,)
- Dấu chấm phẩy (;)
- Dấu hai chấm (:)

Liên kết

Để đính kèm liên kết vào bài viết của bạn, hãy sử dụng thông số link_attachment khi tạo đối tượng file phương tiện. Nếu không cung cấp thông số link_attachment, liên kết đầu tiên mà bạn tạo trong bài viết chỉ có văn bản qua API sẽ được đặt cấu hình làm file đính kèm liên kết (hiển thị dưới dạng thẻ xem trước) giúp tương tác và nhấp vào dễ dàng hơn.

Giới hạn

Tính năng này chỉ áp dụng cho bài viết chỉ có văn bản. Tính năng này không áp dụng cho bài viết có hình ảnh, bài viết có video và bài viết quay vòng.

Đăng

Bạn có thể đính kèm liên kết khi gửi yêu cầu đến điểm cuối POST /threads để tạo đối tượng file phương tiện. Nhớ thêm thông số sau đây vào yêu cầu API:

link_attachment - (Chỉ áp dụng cho bài viết có văn bản.) URL sẽ được đính kèm vào bài viết trên Threads và hiển thị dưới dạng bản xem trước liên kết. URL phải hợp lệ và có thể truy cập công khai.

Yêu cầu mẫu

curl -i -X POST \  
  "https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads?media_type=TEXT&text=Link&access_token=<ACCESS_TOKEN>" 
  -d link_attachment=https://developers.facebook.com/

Phản hồi mẫu

{
  "id": "1234567" // Threads Media Container ID
}

Yêu cầu ở trên sẽ tạo một vùng chứa bài viết trên Threads. Sau khi được đăng, vùng chứa này sẽ đính kèm bản xem trước liên kết vào file phương tiện của bạn.

Truy xuất file phương tiện

Bạn có thể truy xuất giá trị của URL file đính kèm liên kết khi gửi yêu cầu đến điểm cuối GET /threads hoặc GET /{threads_media_id} để truy xuất (các) đối tượng file phương tiện. Nhớ thêm thông số sau đây vào yêu cầu API:

link_attachment_url - URL được đính kèm vào bài viết trên Threads.

Yêu cầu mẫu

curl -s -X GET \ "https://graph.threads.net/v1.0/<THREADS_MEDIA_ID>?fields=id,link_attachment_url&access_token=<ACCESS_TOKEN>"

Phản hồi mẫu

{
   "id": "12312312312123",
   "link_attachment_url": "https://developers.facebook.com/",
}

Quy cách file phương tiện

Quy cách hình ảnh

Định dạng: Loại hình ảnh JPEG và PNG là định dạng được hỗ trợ chính thức cho bài viết có hình ảnh.
Kích thước file: Tối đa 8MB.
Giới hạn tỷ lệ khung hình: 10:1
Chiều rộng tối thiểu: 320 (sẽ được tăng tỷ lệ lên mức tối thiểu nếu cần)
Chiều rộng tối đa: 1440 (sẽ được giảm tỷ lệ xuống mức tối đa nếu cần)
Chiều cao: Thay đổi (tùy theo chiều rộng và tỷ lệ khung hình)
Không gian màu: sRGB. Các hình ảnh sử dụng không gian màu khác sẽ được chuyển đổi sang không gian màu sRGB.

Quy cách video

Vùng chứa: MOV hoặc MP4 (MPEG-4 Phần 14), không có danh sách chỉnh sửa, phần moov atom nằm ở đầu file.
Codec âm thanh: AAC, tần số mẫu tối đa 48khz, 1 hoặc 2 kênh (đơn âm hoặc âm thanh nổi).
Codec video: HEVC hoặc H264, quét lũy tiến, GOP (nhóm ảnh) kín, lấy mẫu phụ sắc độ 4:2:0.
Tốc độ khung hình: 23-60 khung hình/giây
Kích thước ảnh:
- Số cột tối đa (điểm ảnh ngang): 1.920
- Tỷ lệ khung hình bắt buộc nằm trong khoảng từ 0,01:1 đến 10:1. Tuy nhiên, bạn nên sử dụng tỷ lệ 9:16 để tránh bị cắt hoặc có khoảng trống.
Tốc độ bit của video: VBR, tối đa 100 Mb/giây.
Tốc độ bit của âm thanh: 128 kb/giây.
Thời lượng: Tối đa 300 giây (5 phút), tối thiểu dài hơn 0 giây.
Kích thước file: Tối đa 1GB.

Bài viết trên Threads

Bài viết một thread

Giới hạn

Bước 1: Tạo vùng chứa file phương tiện trên Threads

Thông số

Yêu cầu mẫu

Phản hồi mẫu

Bước 2: Đăng vùng chứa file phương tiện trên Threads

Thông số

Yêu cầu mẫu

Phản hồi mẫu

Bài viết quay vòng

Giới hạn

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

Thông số

Yêu cầu mẫu

Phản hồi mẫu

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

Thông số

Yêu cầu mẫu

Phản hồi mẫu

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

Thông số

Yêu cầu mẫu

Phản hồi mẫu

Thẻ chủ đề và liên kết trong bài viết

Thẻ chủ đề

Sử dụng thông số topic_tag

Sử dụng thẻ chủ đề trong văn bản

Liên kết

Giới hạn

Đăng

Yêu cầu mẫu

Phản hồi mẫu

Truy xuất file phương tiện

Yêu cầu mẫu

Phản hồi mẫu

Quy cách file phương tiện

Quy cách hình ảnh

Quy cách video

Sử dụng thông số `topic_tag`