Inbox API

Last week we announced an update to the Open Stream API to allow integration of Page streams with applications. Today we are releasing the Inbox API so you can provide users with even more opportunities to interact with rich Facebook features within your applications. For example, a desktop application geared toward small business owners could enable users to check their company’s Page stream, as well as read messages and receive notifications, all from their desktop.

The Inbox API allows you to access your users’ messages, once they grant your application the new read_mailbox extended permission. This lets your applications provide an interface for users to view their messages. For example, your application could pop up an alert when the user receives a new message.

To access information about a user’s Inbox, you’ll query any of three new FQL tables:

• mailbox_folder: This table gives you information about a user’s folders; currently all users have three folders: Messages (inbox), Sent (outbox), and Updates.
• thread: This table gives you information about specific threads. For example, you can get information about recipients of a thread, whether a group or event sent the thread, when it was last updated, the subject, whether it is currently unread, and more.
• message: This table allows you to get information about each message in a thread. You can get information about who wrote the message, the content of the message and also information about the attachment to the message, if it exists, in the same format as attachments are returned in the stream.

While we currently don’t allow applications to send messages through this API, we’re always thinking about new functionality to offer through Facebook Platform.

To get started, as a developer you can access the Inbox APIs via the read_mailbox permission in order to develop and test your application. To launch your application to all users, please apply to the Inbox API whitelist here.

Application Attachments for Facebook Messages

We’ve simplified the way you can create application attachments that users can share with their friends through Facebook messages. This feature works only with the new Inbox, which a number of users have been testing. The updated Inbox will launch to all users in the coming weeks.

The new Inbox incorporates the same Publisher used to publish to the streams on the home page and profiles. We’ve enhanced the Publisher so it no longer requires you to create template bundles — you can now use the simplified attachment model that stream.publish uses. As we roll out the new Inbox over the next few weeks, we’ll deprecate the old message attachment process.

To integrate your applications into the new Inbox:

1. Create a Publisher endpoint and enter its URL as the Attachment v2 Callback URL you specify on the Advanced tab in your application settings.
2. In your Publisher integration, specify “attachment” for the content parameter, instead of “feed”.
3. Test your attachments today with your test accounts on www.beta.facebook.com.

We’re still supporting existing Publisher integrations that use the “feed” content type, but you should find the flexibility of stream attachments easier to use, as they’re more universal throughout Facebook.

Notifications API

The notifications API lets your applications retrieve your users’ notifications to use within your application. We’ve created a notification FQL table and two new API methods, notifications.getList and notifications.markRead, that let you retrieve structured information about notifications and mark them as read.

The new FQL table contains the same information used to generate the instant notifications you see on the Facebook website. We’ve opened up that data so now you can create better experiences for your users. For example, you can now create new desktop experiences integrating notifications, letting your users stay in touch with their friends and other connections. For example, Facebook for Adobe AIR now uses the notifications API and Inbox API to display notifications and new message alerts alongside the application window.