Tutorial: Programatically Post a Status Update to Your Facebook Page

In my last post, To OAuth or Not to OAuth, I said I would write a complete tutorial on how to use the Facebook API to post status updates to your own Facebook page. This is that tutorial. Get ready, it’s a doozy.

Definitions

Before we begin there are some definitions I have to set down.

Facebook Account

The actual Facebook account you use to talk to friends and family.

Facebook Page

A separate page you have setup for your brand or online community.

Facebook Application

An application you create which is basically just an set of IDs you need to connect to the Facebook API.

Setup

Before we begin you have to create your facebook account, page and application. I’ll assume you already have an account, or know how to create one. That’s clearly outside the scope of this tutorial. Make sure you remain logged into your Facebook account throughout this entire process.

If you don’t already have one, you need to create a Facebook page. Go to https://www.facebook.com/pages/create.php, and follow the instructions. When you are all done you will end up looking at your new page. It will have a URL that will have the following format.

https://www.facebook.com/pages/PAGE_NAME/PAGE_ID_NUMBER

Save the PAGE_NAME and PAGE_ID_NUMBER. If you already have a page, visit it and look at the URL for the name and/or id number. Make sure that your Facebook account has permission to post status updates on that page. I’ve only tested this on pages where my account is the page administrator. Your mileage may vary otherwise, but I see no reason it wouldn’t work as long as you have the necessary permissions.

The next step is to create a Facebook application. To do that go to https://www.facebook.com/developers/createapp.php and follow the instructions. You will go through a configuration process. You can leave all settings as the defaults. Just save the Application ID and Application Secret, and you will be good to go.

Get the Access Tokens Through OAuth

Now it’s time for the tricky parts. You have to give the application permission to access your account. Take the URL below and replace both instances of APP_ID with the ID of the application you just made.

https://www.facebook.com/dialog/oauth?client_id=APP_ID&
redirect_uri=http://www.facebook.com/appcenter/APP_ID&scope=manage_pages,offline_access,publish_stream

Visit this URL in your browser and you will get a dialog box that will ask you whether to allow or deny granting permissions on your account to the application. The page needs to redirect somewhere after you click allow, and it will only allow you to redirect to a page your application owns. That’s why we put the URL of your application’s profile page as the redirect_uri.

The three permissions we are granting are manage_pages, offline_access, and publish_stream. Manage_pages grants the application access to pages which your account has access to. Offline_access means that the application will get an access token that never expires so we never have to do this complicated process ever again. Publish_stream allows the application to post new updates to your account, or any other place your account is able to post updates to, including the page we just created.

Click the allow button. Immediately go to the location bar of your browser and copy and paste the URL to a text editor. Do not lose it. You will see that the URL looks something like this.

https://www.facebook.com/apps/application.php?id=APP_ID
&code=CRAZY_LONG_CODE

That crazy long code is the magic we need. Take that code and use it to create yet another URL in the format that follows. Replace APP_ID with the Application ID as usual. Replace APP_SECRET with the Application Secret. Lastly, put that CRAZY_LONG_CODE where it belongs. Paste the resulting gigantic URL into the location bar of your browser and visit it.

https://graph.facebook.com/oauth/access_token?client_id=APP_ID
&redirect_uri=https://www.facebook.com/apps/application.php?
id=APP_ID&client_secret=APP_SECRET&code=CRAZY_LONG_CODE

If you did everything right you should now be looking at a big beautiful access_token. We will call this the account access token. It gives your facebook application permission to access your account. If you just want to post status updates to your personal account, you can take this access token to the next section. Otherwise, proceed to get the page access token.

In order to get the page access token, we need to visit yet another URL, it looks like this.

https://graph.facebook.com/USER_ID/accounts/?
access_token=ACCOUNT_ACCESS_TOKEN

The USER_ID is the user id of your Facebook account. Mine is apreche because my Facebook profile can be found at https://www.facebook.com/apreche. You might not have a profile URL, in which case you can use a numerical ID instead. If your personal profile is at a URL such as https://www.facebook.com/profile.php?id=NUMBERS then use the NUMBERS as your USER_ID. Take the account access token we got from the previous step and put it in place of ACCOUNT_ACCESS_TOKEN.

Now visit this URL in your browser. You are going to see some slightly complicated text that is in a format known as JSON. It should look something like this.

{
   "data": [
      {
         "name": "PAGE_NAME",
         "access_token": "PAGE_ACCESS_TOKEN",
         "category": "Website",
         "id": "PAGE_ID"
      },
      {
         "name": "APPLICATION_NAME",
         "access_token": "APPLICATION_ACCESS_TOKEN",
         "category": "Application",
         "id": "APPLICATION_ID"
      }
   ]
}

Depending on how many different pages and applications you have on your Facebook account, you may see more than this. Regardless, you are only interested in one thing. Find the section with the PAGE_NAME of the page you want to post to and extract the PAGE_ACCESS_TOKEN from that section. This is the token we have been looking for. Save it and keep it safe.

Making the Post

Now that we have the page access token, we can finally do the actual status update. I will use curl in my examples since that is language agnostic. All you really need to do is make an HTTP POST. In Python you could use urllib. You could also use an appropriate Facebook library for your language, such as the Facebook PHP SDK. It’s up to you to learn how to get this done in your programming language of choice.

Here is what a complete POST looks like using curl in the shell. Remember to put the PAGE_NAME and PAGE_ACCESS_TOKEN where they belong.

$ curl -F access_token="PAGE_ACCESS_TOKEN" \
-F message="testing" \
-F picture="http://i.imgur.com/2uLkT.jpg" \
-F link="http://frontrowcrew.com" \
-F name="Front Row Crew.com" \
-F caption="FRC In the house!" \
-F description="Homepage of GeekNights and other fine free entertainment." \
-F source="http://www.youtube.com/e/NKWpGJ4Xhw8?autoplay=1" \
https://graph.facebook.com/PAGE_NAME/feed

You don’t actually have to include all of that information with every post. Just include the information that is relevant. I have simply included all of the possible information to demonstrate a complete example. Here is what the post above will look like on your Facebook page.

The avatar and the username on the posting are going to be the avatar and username of the page itself. You can’t change those from post to post.

The word “testing” that you see there is the message of the post. Most of the time I imagine you are going to be posting just messages without any other information.

After that is a separate section with the link, picture, video, and everything else. Depending on which combination of information you post, that section will work differently. You only get one of these sections per post, so depending on what you want to do, you might need to stretch it out over multiple postings. If your post only contains a message, this section won’t exist at all.

The link field controls the URL where the user will be sent if they click on the blue text at the top of the section. The name field controls the blue text itself. If you don’t specify a name then Facebook will visit the link and figure out a name to use. In this example the link is http://frontrowcrew.com and the name is “Front Row Crew.com”. If you know HTML you can think of it like a basic “A” tag, since that is what it is.

<a href="LINK_GOES_HERE">NAME_GOES_HERE</a>

The caption controls that light gray text directly beneath the link. The description controls the block of text that is one space beneath the caption. If you leave either of these blank then Facebook will visit the link in question and try to figure out a caption and description on its own.

The picture is where things start to get a little bit complicated. First of all, if you specify a link without a picture, then Facebook will actually pick an appropriate picture based on the link, just like it does with the name, caption, and description. Since it will probably pick a bad picture, I suggest you set the picture manually whenever specifying a link. The picture is just a link to any image on the web. Clicking on the picture thumbnail will take the user to the URL of the link.

You can actually specify a picture all on its own without any link at all. In that case clicking on the picture will take the user to see the picture in its full size. The caption, and description will be extremely barebones unless you manually specify them.

Source may as well be called video instead of source. It needs to be a URL directly linking to a video file, usually a flash video. I’m pretty confident other HTML5 video formats will work, but I haven’t tested them myself. Don’t make the mistake of setting the source to a video’s page like this.

http://www.youtube.com/watch?v=NKWpGJ4Xhw8

That won’t work. You have to set the source to be the actual video file as in the example.

http://www.youtube.com/e/NKWpGJ4Xhw8?autoplay=1

You are on your own on how to structure these links on other video sites besides YouTube. I think I can safely assume the vast majority of people are using YouTube.

If a source is set without a picture, you may get an error if Facebook can’t figure out a video thumbnail on its own. In this case, you must specify a picture to successfully make the post. The picture will be used as the thumbnail. Clicking on the picture will cause the video to play. For YouTube the player is embedded within Facebook itself. As always, your mileage may vary with other video formats and sites.

Now, Facebook is actually pretty smart. Let’s say you specify just a link, and that link goes directly to a YouTube page. Facebook will automatically figure out the source and picture on its own, assuming you do not manually override them.

Lastly, what if you specify absolutely everything as in the example above? Obviously you will have complete manual control over all of the text appearing in the post as well as the picture. Clicking on the picture will play the source video. Clicking the blue text link will always go to the specified link. In this way you can actually link to two different things. Clicking on the picture will play a video, but clicking the link can take people to your blogpost about the video or other related place on the web.

Also, it should be noted that there is nothing forcing the picture and video to match. You can post a thumbnail for a video that is not related to the video at all. Users might be very confused if you abuse it, but there are legitimate reasons for doing so. You might just a brand logo as a thumbnail on a video which does not include that logo.

One last thing. The post will always return some information formatted in JSON. If it fails there will be an error for you to read. If it success there will be an ID that is the ID of the status update you just posted. You can save and use that ID for later if you want to edit or delete the post.

Conclusion

Figuring this out cost me many hours. If this saves even one person from that struggle, then it was worth it.

I hope this can also serve as an example to other people who write technical tutorials or howtos. You can’t just skip over details. You need to include every step and explain the what, why, and how of all those steps. Otherwise readers have to go to ten different sites to piece together the complete picture like I did. Even worse, users might blindly copy and paste without understanding what they are doing.

And of course, I hope this shows just how much of a pain OAuth can be when it is used unnecessarily. With my suggestion of every account also being an application, many of the OAuth steps would be eliminated without sacrificing any security or privacy.