Developer news
Steps Toward the New Messaging System

In November 2010 Facebook introduced a new messaging product which unified conversations sent via chat, e-mail and regular Facebook messages. Today we are beginning the transition of our old mailbox APIs to this new product. This transition will enable clients to have the same view of users' mailboxes as found on the Facebook webpage and in Facebook Messenger. The following APIs are affected:

  • The 'thread', 'message' and 'mailbox_folder' FQL tables
  • The message.getThreadsInFolder REST API call
  • The /me/inbox, /me/outbox and /me/updates Graph API calls


p> Please note that not all of the new features of the new messaging system are available using the APIs mentioned above.

Overview of the Changes

The new messaging product has a few significant differences from the previous product:

  • All conversations between people are stored in a single conversation thread, regardless of whether they were sent via chat, e-mail, SMS or a regular message. This means that threads are typically much longer than in the previous system. You can use the offset and limit parameters of the affected APIs to control the number of threads and messages returned from the call.
  • The new messaging system supports the ability for a user to delete individual messages and it is also possible for messages to arrive out of order. This means that one should not rely on message identifiers to remain unchanged between calls. Therefore, we recommend using queries based on timestamps to retrieve new messages in a thread rather than providing an offset parameter.
  • The 'updates' folder is no longer present in the new product. Queries accessing this folder will not return any results.

Transitioning to the new Messaging System

To assist with this transition we are offering the following migration path:

  1. Existing apps using the affected APIs will continue to use the old back end until November 30, 2011. After that apps will automatically be switched over to the new messaging back end. The existing APIs will continue to work with the exception of the possible side effects described above.
  2. We are providing a migration that allows an app to try the new messaging back end on the affected APIs. This migration will be available until November 30th, 2011. This migration is set by enabling or disabling the 'New mailbox back end' migration in the Advanced settings tab of your apps. You can also control it for individual calls by passing '{mailbox_transition:true}' as the value for the 'migrations_override' parameter for your request.
  3. After November 30th, 2011, the old messaging FQL tables and APIs will only return data from the new messaging back end.
  4. Apps should move to the new messaging Graph API endpoints and messaging FQL tables ('unified_message' and 'unified_thread'). We will be formally deprecating the old messaging REST APIs, Graph APIs and messaging FQL tables at a date to be announced in the future.