Facebook Stories API from Meta

Tài liệu này cho bạn biết cách sử dụng Facebook Stories API để đăng Tin trên Trang Facebook.

Để đăng tin, bạn sẽ thực hiện các bước sau đây:

1. Tải file phương tiện của bạn lên máy chủ của Meta
2. Đăng file phương tiện đó lên Trang của bạn dưới dạng Tin

Trước khi bạn bắt đầu

Hướng dẫn này giả định rằng bạn đã đọc phần Tổng quan về API Trang và triển khai các thành phần cần thiết, đồng thời đã hoàn tất thành công hướng dẫn Bắt đầu.

• Bạn sẽ cần triển khai phương thức Đăng nhập bằng Facebook hoặc Đăng nhập bằng Facebook cho doanh nghiệp để yêu cầu người dùng ứng dụng cấp các quyền cần thiết, nhằm truy cập vào Trang Facebook của người dùng và nhận mã truy cập Trang.

• Người dùng ứng dụng sẽ cần có khả năng thực hiện tác vụ CREATE_CONTENT trên Trang được biểu thị bằng mã truy cập Trang và cấp cho ứng dụng của bạn các quyền sau đây:

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

Nếu sử dụng người dùng hệ thống của doanh nghiệp trong yêu cầu API, bạn sẽ cần có cả quyền business_management.

Yêu cầu về file phương tiện

Bạn phải cung cấp ảnh hoặc video phù hợp với quy cách dưới đây.

Quy cách ảnh

Quy cách video

Giới hạn

• Ảnh hoặc video mà bạn tải lên cho tin không được phép sử dụng trong bài viết đã đăng trước đây
• Tin video không được vượt quá 60 giây
• Để đưa tin đã lưu trữ vào yêu cầu GET nhằm xem danh sách tin, bạn phải bật kho lưu trữ tin trên Facebook

Cách làm tốt nhất

Mã mẫu trong tài liệu này được định dạng để dễ đọc. Hãy thay thế các giá trị in đậm, in nghiêng như page_id bằng các giá trị của bạn.

Tin video

Để đăng tin video trên Trang Facebook, bạn sẽ khởi tạo một phiên tải video lên với máy chủ của Meta, tải video lên máy chủ của Meta rồi đăng tin video đó.

Bước 1: Khởi tạo phiên

Để khởi tạo một phiên tải lên, hãy gửi yêu cầu POST đến điểm cuối /page_id/video_stories, trong đó page_id là ID Trang Facebook của bạn và đặt thông số upload_phase là start.

Yêu cầu mẫu

curl -X POST "https://graph.facebook.com/v21.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

Khi thành công, ứng dụng của bạn sẽ nhận được phản hồi JSON có chứa ID video và URL Facebook mà bạn sẽ tải video lên.

Phản hồi mẫu

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v21.0/video_id",
}  

Bước 2: Tải video lên

Lúc này khi đã khởi tạo một phiên tải lên và nhận được URL tải lên, bạn có thể tải video của mình lên. Bạn có thể tải lên 1 trong 2 loại file sau đây:

• file video được lưu trữ trên một máy chủ http/https hiển thị công khai, chẳng hạn như CDN
• file video trên máy từ thiết bị của bạn

Tải file được lưu trữ lên

Để tải một file được lưu trữ lên, hãy gửi yêu cầu POST đến điểm cuối upload_url mà bạn nhận được ở bước khởi tạo với các thông số sau đây:

• file_url được đặt là URL cho file video của bạn

Yêu cầu mẫu

curl -X POST "https://rupload.facebook.com/video-upload/v21.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

Tải file trên máy lên

Để tải một file trên máy lên, hãy gửi yêu cầu POST đến điểm cuối upload_url mà bạn nhận được ở bước khởi tạo với các thông số sau đây:

• offset được đặt là 0
• file_size được đặt là tổng kích thước tính bằng byte của video đang được tải lên

Yêu cầu mẫu

curl -X POST "https://rupload.facebook.com/video-upload/v21.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

Khi tải lên thành công, ứng dụng của bạn sẽ nhận được phản hồi JSON với success được đặt là true.

Phản hồi mẫu khi tải lên

{
    "success": true
}  

Quá trình tải lên bị gián đoạn

Nếu quá trình tải video lên bị gián đoạn, bạn có thể bắt đầu lại hoặc tiếp tục quá trình tải lên.

• Để bắt đầu lại quá trình tải lên, hãy gửi lại yêu cầu POST và đặt offset là 0.
• Để tiếp tục quá trình tải lên, hãy gửi lại yêu cầu POST và đặt offset là giá trị bytes_transfered khi kiểm tra trạng thái.

Lấy trạng thái tải lên

Để kiểm tra trạng thái video xem là đang trong quá trình tải lên hay đăng, hãy gửi yêu cầu GET đến điểm cuối /video_id với thông số sau đây:

• fields được đặt là status

Yêu cầu mẫu

curl -X GET "https://graph.facebook.com/v21.0/video_id" \
	-d "fields=status"

Khi thành công, ứng dụng của bạn sẽ nhận được phản hồi JSON có chứa:

• Đối tượng status có chứa:

  • video_status có giá trị là ready, processing, expired hoặc error
  • Đối tượng uploading_phase có các cặp khóa-giá trị sau đây:

    • status được đặt là in_progress, not_started, complete hoặc error
    • bytes_transfered được đặt là số byte đã tải lên, có thể được dùng làm giá trị cho offset nếu quá trình tải lên bị gián đoạn.
  • Đối tượng processing_phase có các cặp khóa-giá trị sau đây:

    • status được đặt là in_progress, not_started, complete hoặc error
  • Đối tượng processing_phase có các cặp khóa-giá trị sau đây:

    • status được đặt là in_progress, not_started, complete hoặc error
    • publish_status được đặt là published hoặc not_published
    • publish_time được đặt là nhãn thời gian UNIX của thời gian thực tế hoặc thời gian đăng

Phản hồi mẫu

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

Bước 3. Đăng tin video

Để đăng tin video lên Trang của mình, bạn cần gửi yêu cầu POST đến điểm cuối /page_id/video_stories với các thông số sau đây:

• video_id được đặt là ID của video bạn đã tải lên
• upload_phase được đặt là finish

Yêu cầu mẫu

curl -X POST "https://graph.facebook.com/v21.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

Khi thành công, ứng dụng của bạn sẽ nhận được phản hồi JSON có chứa các cặp khóa-giá trị sau đây:

• success được đặt là true
• post_id được đặt là ID bài viết có tin của bạn

Phản hồi mẫu

{
  "success": true,
  "post_id": 1234
}

Tin ảnh

Bước 1. Tải ảnh lên

Truy cập vào Tài liệu tham khảo về bài viết trên Trang để tìm hiểu cách tải ảnh lên máy chủ của Meta bằng điểm cuối /page_id/photos. Đừng quên thêm thông số published và đặt thông số này là false.

Bước 2. Đăng tin ảnh

Để đăng tin ảnh lên Trang của mình, bạn sẽ gửi yêu cầu POST đến điểm cuối /page_id/photo_stories với các thông số sau đây:

• photo_id được đặt là ID của ảnh bạn đã tải lên

Yêu cầu mẫu

curl -X POST "https://graph.facebook.com/v21.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

Khi thành công, ứng dụng của bạn sẽ nhận được phản hồi JSON có chứa các cặp khóa-giá trị sau đây:

• success được đặt là true
• post_id được đặt là ID bài viết có tin của bạn

Phản hồi mẫu

{
  "success": true,
  "post_id": 1234
}

Lấy tin

Để lấy danh sách tất cả tin của một Trang và dữ liệu về từng tin, hãy gửi yêu cầu GET đến điểm cuối /page_id/stories, trong đó page_id là ID của Trang bạn muốn xem.

Yêu cầu mẫu

    
curl -i -X GET "https://graph.facebook.com/v21.0/page_id/stories"

Khi thành công, ứng dụng của bạn sẽ nhận được phản hồi JSON có chứa một mảng các đối tượng, trong đó mỗi đối tượng chứa thông tin về một tin được đăng trên Trang. Mỗi đối tượng sẽ chứa các cặp khóa-giá trị sau đây:

• post_id được đặt là ID của bài viết có tin đã đăng
• status được đặt là PUBLISHED, ARCHIVED
• creation_time được đặt là nhãn thời gian UNIX của thời điểm đăng tin
• media_type được đặt là video hoặc photo
• media_id được đặt là ID của video hoặc ảnh trong bài viết có tin
• url được đặt là URL Facebook của bài viết có tin, chẳng hạn như https://facebook.com/stories/8283482737484972

Phản hồi mẫu

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

Bạn có thể lọc tin theo trạng thái (đã đăng hoặc đã lưu trữ) và ngày bằng cách sử dụng các thông số since và until.

Xem thêm

Tìm hiểu thêm về các điểm cuối và khái niệm được thảo luận trong hướng dẫn này.

Hướng dẫn liên quan

• Người dùng hệ thống của doanh nghiệp
• Đăng nhập bằng Facebook
• Đăng nhập bằng Facebook cho doanh nghiệp
• API Đồ thị - Kết quả được phân trang theo thông số since và until

Tài liệu tham khảo về điểm cuối

• Tài liệu tham khảo về Trang
• Tài liệu tham khảo về tin video trên Trang
• Tài liệu tham khảo về tin ảnh trên Trang
• Tài liệu tham khảo về video
• Tài liệu tham khảo về thông tin chi tiết về tin