Posts

Note

You need to be authenticated before you can interact with posts. If you haven't set up authentication yet, check out the authentication guide.

Overview

Posts are the main way to interact with the Meta's Graph API. You can publish four main types of posts to the news feed or your profile, or use the post objects to interact with Meta's API in other ways.

Text posts: Simple status updates with a message
Link posts: Posts that include a URL with automatic preview generation
Media posts: Posts with photos or videos
Scheduled posts: Posts that publish at a future date and time

Through the API, posts can be created, retrieved, edited, and deleted (where Meta's policies allow).

Profile Types

Page Posts

Page posts are the recommended approach for most applications. They require having a page under your account, but in exchange offer the widest breadth of functionality.

If you don't already have a page setup with permissions, you can find out to create one in the authentication guide.

Loading documentation...

The following code is a minimal, reproducible example of how to publish a post to a page.

import Facebook from "bookface";
import type { Config } from "bookface";

const config: Config = { profile: "page", pageIndex: 0 }; // These are built-in defaults, so you don't need to specify them.
const facebook = new Facebook(config);

const post = await facebook.page.posts.publish({
message: "Hello world"
});

User Posts

Important

User profile posting has been heavily restricted by Meta since April of 2018. Most posting operations will throw errors.

You can read more about this in the accompanying blog post and out-of-cycle changelog.

User posts refer to posts on your personal profile. Unlike page posts, user posts can no longer be published, edited, or deleted. The only remaining functionality is reading existing posts.

Loading documentation...

The following is a minimal, reproducible example of how to read posts from your own user profile.

import Facebook from "bookface";
import type { Config } from "bookface";

const config: Config = { profile: "user" };
const facebook = new Facebook(config);

const posts = await facebook.user.posts.read();

Creating Posts

Creating posts is done using the publish method. Depending on what your trying to post, you'll need to pass in the appropriate configuration object and have the right permissions.

Text Posts

The simplest type of post is a text post.

const post = await facebook.page.posts.publish({
  message: "This is a text update."
});

console.log({ post });

Link Posts

Link posts are simply posts that refer to a URL.

Different from text posts, link posts automatically generate rich previews with the your link's title, description, and thumbnail.

const post = await facebook.page.posts.publish({
  message: "This is a link post.",
  link: "https://developers.facebook.com"
});

You can also post links without an additional message by doing the following.

const post = await facebook.page.posts.publish({
  link: "https://github.com"
});

Media Posts

Media posts allow you to attach photos or videos.

Supported formats include JPG, PNG, GIF, BMP, and TIFF.

const post = await facebook.page.posts.publish({
  message: "This is a photo post.",
  media: "/path/to/image.jpg"
});

const galleryPost = await facebook.page.posts.publish({
  message: "This is a gallery post.",
  media: [
    "/path/to/photo1.jpg",
    "/path/to/photo2.png",
    "/path/to/photo3.gif"
  ]
});

You can also upload images with Base64 data by doing the following.

const post = await facebook.page.posts.publish({
  message: "This post attaches a Base64 image.",
  media: {
    data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
    type: "png"
  }
});

Scheduled Posts

Scheduled posts allow you to publish things at a future time and date.

Note

The scheduled time of your post must be at least 10 minutes in the future.

const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(9, 0, 0, 0);

const post = await facebook.page.posts.publish({
  message: "Scheduled announcement",
  schedule: tomorrow
});

console.log("Post scheduled");
console.log({ scheduled: post.scheduled });

You can also schedule other types of posts, like the ones defined above.

const scheduledLink = await facebook.page.posts.publish({
  message: "This is a scheduled link post.",
  link: "https://example.com/newsletter",
  schedule: "2024-01-15T10:00:00Z"
});

const scheduledMedia = await facebook.page.posts.publish({
  message: "This is a scheduled media post.",
  media: "/path/to/announcement.jpg",
  schedule: new Date("2024-01-20 14:30:00")
});

Checking Scheduled Posts

When you schedule a post, you can check if the post has been published yet using the ready() method.

const scheduledPost = await facebook.page.posts.publish({
  message: "Future announcement",
  schedule: new Date("2024-01-15T10:00:00Z")
});

console.log("Checking if post is published");
const isPublished = await scheduledPost.ready();
console.log({ published: isPublished });

Reading Posts

Read All Posts

You can read all posts from a profile using the read method.

const pagePosts = await facebook.page.posts.read();
console.log("Posts retrieved");
console.log({ count: pagePosts.length });
console.log({ posts: pagePosts });

Get Specific Posts

If you only want to read a single post though, you can use the get method instead and specify the post's ID.

While post IDs can be useful, it's better practice to use post objects whenever available, as IDs can be finnicky.

If you want to use a string ID anyways, note that post IDs also usually require the user ID to specified in a "{user ID}_{post ID}" format.

const post = await facebook.page.posts.get({
  id: "123456789_987654321"
});

console.log({ post });

To pass in an existing post object (recommended), pass the object in directly or pass in the id property.

const existingPost = await facebook.page.posts.publish({
  message: "This is a post."
});

const retrievedPost = await facebook.page.posts.get(existingPost);
const idRetrievedPost = await facebook.page.posts.get({ id: existingPost.id });
console.log({ retrievedPost });

Editing Posts

Note

You can only edit text posts. Media, link, and scheduled posts cannot be modified after publishing.

To edit a text post, pass in the post's ID (or better yet, an existing post object) and the new message.

const editedPost = await facebook.page.posts.edit({
  id: "123456789_987654321",
  message: "This post has been edited."
});

console.log("Post updated");
console.log({ success: editedPost.success });

Deleting Posts

To delete a post, pass in the post's ID (or better yet, an existing post object).

const result = await facebook.page.posts.remove({
  id: "123456789_987654321"
});

console.log("Post deleted");
console.log({ success: result.success });

Post Object

When you create, read, or modify posts, you'll automatically get back a Post object. This is useful because it provides direct methods for interacting with your post.

Post objects also contain properties like id, message, created, media, link, success, and scheduled — these are useful for gathering information about a post.

You can find the full list of properties/methods for posts in the API reference.

The following is a minimal, reproducible example of how to use a post object.

const post = await facebook.page.posts.publish({
  message: "Hello world"
});

console.log("Post properties");
console.log({
  id: post.id,
  message: post.message,
  created: post.created,
  scheduled: post.scheduled
});

Direct Post Methods

const post = await facebook.page.posts.publish({
  message: "Original message"
});

await post.edit({
  message: "Edited message"
});

await post.remove({});

Post Dumps (JSON)

If you need to get a raw JSON representation of a post, you can use the dump method.

const post = await facebook.page.posts.publish({
  message: "Original message"
});

const details = post.dump();
console.log({ details });

Post Comments

Post objects can also be used to work with comments. You can do this by accessing the comments method which allows you to to publish or read comments on a post.

More information about comments can be found in the comments guide.

Targeting

If you want to target a post to specific geographic locations, you can do so by passing in a targeting object. This is mostly meant for advanced use cases involving advertising.

const post = await facebook.page.posts.publish({
  message: "Regional announcement",
  targeting: {
    geo_locations: {
      countries: ["US"],
      cities: [
        { key: "123", name: "New York" },
        { key: "456", name: "Los Angeles" }
      ]
    }
  }
});

Error Handling

As with any API, requests can fail. To handle errors gracefully, you can utilize JavaScript's promise system.

The following is a minimal example of how to handle errors with catch blocks, but you can use any error handling method you prefer.

const pagePost = await facebook.page.posts
  .publish({
    message: "This post will err gracefully.",
    schedule: new Date()
  })
  .then(post => {
    console.log({ post });
  })
  .catch(error => {
    console.log("Publishing failed");
    console.log({ error: error.message });
  });

const userPost = await facebook.user.posts
  .publish({
    message: "This post will fail."
  })
  .then(post => {
    console.log({ post });
  })
  .catch(error => {
  console.log("User posting deprecated");
  console.log({ error: error.message });
  });