New Opportunities for Inbox and Notification Integration
Today at 2:03pm
Published by Ben Hiller
We're continuously looking for ways to open core Facebook experiences to developers for innovation. Today we set our focus on two communication channels: notifications and the Facebook Inbox. We're excited to release two new APIs that will let your applications access your users' mailboxes and notifications in a structured manner. In addition, you can make your stream applications available as attachments for Facebook messages so that users can more easily share application content with friends.
Mailbox 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 Mailbox 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 Mailbox 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 mailbox, 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.
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 mailbox API to display notifications and new message alerts alongside the application window.
As always, we're looking forward to see what you do with these features, and we welcome your feedback below.
Offline
$facebook->api_client->fql_multiquery('{"query1":"SELECT notification_id, sender_id, title_html, body_html, href FROM notification WHERE recipient_id=1;"}');responds with
<error_code>3</error_code>
<error_msg>Unknown method</error_msg>
As well as other ways of attempting to access the notification table. Is this just a case of "it'll take a while to roll out to facebook.com"?
Offline
Just wanted to confirm that I'm having the same problem with the notification table.
edit: forgot to say thank you for this
Inbox and notifications are two most requested features by users of my application. Is Chat API coming up next? ![]()
Last edited by BabblerForAndroid (2009-08-11 20:01:54)
Offline
Facebook Platform Team wrote:
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.
Few weeks is not acceptable prior notice for deprecating any major current communication channel such as attachments. Hope you understand this.
Normal attachment callback url is already marked as "deprecated", before the new one is at all available.
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.
As always, we're looking forward to see what you do with these features, and we welcome your feedback below.
And what then? It is not clear. Any docs?
Please give more info regarding attachments.
Offline
According to wiki:
http://wiki.developers.facebook.com/index.php/Publisher
Important! Until the new Inbox launches to all users in the next few weeks (after August 11, 2009), you can test your attachments today only with your test accounts on www.beta.facebook.com.
It turns out new attachments will not work at all and when they will work - old ttachments will be deprecated...
We need some reasonable period when both APIs are working live and available and it sounds that it is not the case here.
Offline
Querying the notification table now works for me. The inbox feature (thread table) still returns error 3 however. Thanks for the new stuff in any case, it's really nice!
Offline
Facebook Platform Team wrote:
New Opportunities for Inbox and Notification Integration
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.
I'm not clear on how to use this -- the old publisher API made two types of requests - publisher_getInterface and publish_getFeedStory. This way you could present UI allowing the user to customize their attachment in getInterface and then after submit return the actual story data in getFeedStory.
When I try this new attachment API I'm not seeing any type of two step process -- only one request that seems to expect a complete feed story. What's the deal, am I missing something obvious here?
Offline
mikeb wrote:
Facebook Platform Team wrote:
New Opportunities for Inbox and Notification Integration
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.I'm not clear on how to use this -- the old publisher API made two types of requests - publisher_getInterface and publish_getFeedStory. This way you could present UI allowing the user to customize their attachment in getInterface and then after submit return the actual story data in getFeedStory.
When I try this new attachment API I'm not seeing any type of two step process -- only one request that seems to expect a complete feed story. What's the deal, am I missing something obvious here?
What paramters does facebook post to your page?
Offline
anatolyl wrote:
What paramters does facebook post to your page?
Parameters: {"__a"=>"1", "fb_sig_time"=>"1250726827.1852", "post_form_id_source"=>"AsyncRequest", "fb_sig"=>"XXX", "fb_sig_app_id"=>"XXX", "fb_sig_in_new_facebook"=>"1", "fb_sig_locale"=>"en_US", "action"=>"attachment", "fb_sig_session_key"=>"XX", "fb_sig_expires"=>"1250733600", "fb_sig_added"=>"1", "fb_sig_api_key"=>"XXX", "fb_sig_ext_perms"=>"auto_publish_recent_activity", "fb_sig_user"=>"XXX", "fb_sig_profile_update_time"=>"1250620475" }
Doesn't seem very useful. Has anyone got this to work?
Last edited by mikeb (2009-08-19 17:11:13)
Offline
Any word on how to get the Inbox Attachments to work? They show up fine, but don't post. Keep getting "There was an application error. Please try again later."
Offline
Manakki wrote:
Any word on how to get the Inbox Attachments to work? They show up fine, but don't post. Keep getting "There was an application error. Please try again later."
Well, I sure couldn't find any answers on this discussion forum. I solved the biggest battle and could still use help with a smaller issue.
This code works for returning data in the correct format to the publisher to process the attachment. Notice that the media and content is buried deeper-level arrays.
$media = array('type' => 'image',
'src' => $image_url,
'href' => $image_url);
$attachment = array('name' => $attachment_name,
'href' => $image_url,
'media' => array('media' => $media),
'caption' => $action_text);
$data = array('content' => array('attachment' => $attachment),
'method' => 'publisher_getFeedStory');What doesn't work is the error handling. The Facebook documentation for the new attachment function shows the error handling should be done the same way it always has with the publisher interface like this, but it doesn't work. It does show a red error message box if the error is triggered, but the error message itself doesn't show so users have no idea what the problem is!
$data = array('errorCode'=> 1,
'errorTitle'=> 'No <whatever> selected',
'errorMessage'=>'Please select a <whatever> to send.');Offline
You need to implement 2 interfaces, attachment is the second interface: publisher_getFeedStory
You need to implement publisher_getInterface as well.
Search for "publisher" on the wiki for details/examples.
Regarding JSON for error - can you file a bug to bugzilla nad post the link here?
thanks
Offline
As a follow-up, three more issues with the new attachment interface:
1. The app that was used to add the attachment is no longer shown and Facebook won't render html. All you can do is put something like this in the description: "... via http://apps.facebook.com/whatever". Notice that you can't use HTML, but it will make the link clickable. I guess you could add another "media" item with a small pic of your app and a link, but I wish we just had the automatic pic/name/link that FB placed on attachments before.
2. The "Share" button doesn't show the person sharing it what's actually being shared. Normally, the Share button lets you preview what you are sharing and even select which image you want to share if there is more than one.
3. fb_sig_profile_user is *supposed* to be the person to whom you are sending the message, but its empty. This means you can't access any information about the person being emailed to be able to personalize the message attachment. This stinks. For now I'm just saying "so and so sent whatever to YOU", but then that looks really stupid if the recipient shares this message on his profile or with another user. We really need to be able to use <fb:name> like we could with templates.
Last edited by timnicholson (2009-09-19 15:10:02)
Offline
timnicholson wrote:
3. fb_sig_profile_user is *supposed* to be the person to whom you are sending the message, but its empty. This means you can't access any information about the person being emailed to be able to personalize the message attachment. This stinks. For now I'm just saying "so and so sent whatever to YOU", but then that looks really stupid if the recipient shares this message on his profile or with another user. We really need to be able to use <fb:name> like we could with templates.
This is not correct - fb_sig_profile_user used on publisher when the current user is on somebody elses profile and is not relevant for inbox since it is not a profile. In addition there may be multiple recipients and different people participating on the thread.
Offline
anatolyl wrote:
This is not correct - fb_sig_profile_user used on publisher when the current user is on somebody elses profile and is not relevant for inbox since it is not a profile. In addition there may be multiple recipients and different people participating on the thread.
Good point on the multiple mail recipients. So do we have an array of "to" ID's that we can pass on a template as target_ids or if using the new attachment interface, process the array on our own?
Offline
anatolyl wrote:
You need to implement 2 interfaces, attachment is the second interface: publisher_getFeedStory
You need to implement publisher_getInterface as well. Search for "publisher" on the wiki for details/examples. Regarding JSON for error - can you file a bug to bugzilla nad post the link here? thanks
Thanks for your response. I do understand this. I have working publisher forms. I just posted a code snippet from the last response to publish the attachment. The issue is with the error message not being displayed. I will submit a bugzilla report for that.
Offline
Hi all,
I'm developing an application into Android and I'm using FQL Language. When I get the response, appears the next error:
yyyyyyyyyy is not permitted to requested mailbox permissions from zzzzzzzzz
I added the "read_mailbox" permission in my facebook preferences configuration, but doesn't work.
Could you help me anyone?
Thanks a lot.
Last edited by pakkk (2009-10-14 08:29:29)
Offline
pakkk wrote:
Hi all,
I'm developing an application into Android and I'm using FQL Language. When I get the response, appears the next error:
yyyyyyyyyy is not permitted to requested mailbox permissions from zzzzzzzzz
I added the "read_mailbox" permission in my facebook preferences configuration, but doesn't work.
Could you help me anyone?
Thanks a lot.
AFAIK, your app has to be whitelisted by facebook.
You do it from app settings. If not whitelisted it will work only for developers of the app.
In addition you need extended permission from the user to read mailbox.
Offline
I have been doing some tests tonight (pulling my hair out)
It seems that when attaching via the inbox the $_POST['fb_sig_profile_user'] is not passed. Can anyone confirm this?
My script was failing because I used this paramter to update the recipients profile etc. (works fine when publishing to the wall)
It didn't seem to matter that the recipient had my app installed either, it still wouldn't pass their id when attaching to a message.
This may save some people some time.
Offline
User-to-user notification is a MUST. There is no other "real-time" one-to-one communication. Inbox definitely cant be real time(application counter can be one??).
- app-to-user may be blocked, fine
- user-to-user can be restricted only between friends, fine
- restrict max no. of notifs, fine
- always require login to send notifs. offline notifications can be disabled.
But we NEED user-to-user notification, very badly
Last edited by tichwhack (2009-11-03 19:51:13)
Offline
Inbox mouseover dropdown in facebook title bar should show unread update and invite counts. That currently shows only "view inbox" and "compose message". Currently unread update count is not visible unless you go to inbox. It should have 2 more items in dropdown menu with unread count, that is:
view message inbox (2)
compose new message
view updates (5)
view invites (3)
Offline