FQL:unified_message

Please note: Facebook is in the process of making the new messages system available to all users, at which point this table will replace the message table. Facebook is providing early access to this API for registered developer accounts only until the new messaging system is broadly available. You should use the message table for production applications at the current time.

Access to this table requires the user to grant the read_mailbox extended permission to the application and has a number of query restrictions. See the Notes section below for more details.

Columns

Highlighted rows are indexable / searchable and one is usually required in the WHERE portion of the query.

Name	Type	Description
message_id	string	Unique identifier of the message.
thread_id	string	Unique identifier of the thread.
subject	string	Subject of the message.
body	string	Body of the message.
unread	bool	Flag indicating whether the message is unread.
timestamp	string	Last update time of the thread (Unix-type timestamp with millisecond resolution).
tags	array	Message tags.
sender	object	Sender of the message. This field is an object with properties name (string), email (string) and user_id (string).
recipients	array	List of message recipients. Each element of the list is an object with properties name (string), email (string) and user_id (string).
object_sender	object	Sender of the message in the case that it is a Facebook page, group or event. This field is an object with properties object_address_type (int) and id (string).
html_body	string	HTML representation of the message body.
attachments	array	List of attachment identifiers. Attachments correspond to any attached file.
attachment_map	array	Map from attachment identifiers to objects containing information about the attachment (file size, type, etc.). Each object has the following properties: id (string), type (int), mime_type (string), filename (string) and file_size (int).
shares	array	List of share identifiers. Shared items include links, videos, and photos as were supported in the old messaging system.
share_map	array	Map from share identifiers to objects containing information about the shared objects. Each object has the following properties: share_id (string), type (int), href (string), title (string), summary (string) and image (string).

Examples

Get messages in a thread

SELECT ... FROM unified_message WHERE thread_id=...

Get a message by its identifier

SELECT ... FROM unified_message WHERE message_id=...

Get messages in a thread sent since the beginning of 2010

SELECT ... FROM unified_message WHERE thread_id=... AND timestamp >= 1262332800000

Notes

Not all syntactically valid queries are supported. The constraints are:

• the WHERE clause must specify a value for thread_id or message_id
• the WHERE clause must be a conjunction (boolean AND) of constraints on the fields marked as indexable (e.g. you cannot specify constraints based on the subject, etc.)
• the results can only be ordered by timestamp (ascending or descending)
• you should always specify a limit. If unspecified the default is to return at most 20 results

Notes/Bugs/Gotchas

The official docs don't mention it, but perhaps this table also supports the has_tags() and CONTAINS keywords mentioned on FQL:unified_thread --Wong 15:22, 18 February 2011 (UTC)