FQL:unified_thread

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 thread 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 thread 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
thread_id	string	Unique identifier of the thread.
unread	bool	Flag indicating whether the thread contains unread messages.
archived	bool	Flag indicating whether the thread is archived.
num_messages	int	Total number of messages in the thread.
num_unread	int	Number of unread messages.
subject	string	Subject of the thread.
snippet	string	Fragment of the thread for use in thread lists.
timestamp	string	Last update time of the thread (Unix-type timestamp with millisecond resolution).
tags	array	Thread tags.
senders	array	List of participants who have sent a message in the thread. Each element of the list is an object with properties name (string), email (string) and user_id (string).
participants	array	List of participants who are currently subscribed to the thread. Each element of the list is an object with properties name (string), email (string) and user_id (string).
former_participants	array	List of former participants who have unsubscribed from the thread. Each element of the list is an object with properties name (string), email (string) and user_id (string).
object_participants	array	List of participants who represent a Facebook page, group or event. Each element of the list is an object with properties object_address_type (int) and id (string).
single_recipient	string	For threads representing a two-person conversation this is the user ID of the other thread participant.
has_attachment	bool	Flag indicating whether the thread contains a message which includes an attachment.

Examples

Get threads from the user's inbox

SELECT ... FROM unified_thread WHERE has_tags('inbox')

Get unread threads from the user's 'other' folder

SELECT ... FROM unified_thread WHERE has_tags('other') AND unread=1

Get threads containing the word 'hey'

SELECT ... FROM unified_thread WHERE CONTAINS('hey')

Get the two person conversation thread with user 1234

SELECT ... FROM unified_thread WHERE single_recipient=1234

Get inbox threads updated since the beginning of 2010

SELECT ... FROM unified_thread WHERE has_tags('inbox') 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 single_recipient or contain a `has_tags` call with one of the folder tags (‘inbox’, ‘other’, ‘spam’) or contain a CONTAINS predicate
• 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

Tags

Each thread has a set of tags which contain information about the thread. Tags can denote a messaging folder (inbox, other, spam), the source of the thread (source:web, source:mobile, source:chat, source:email), whether the thread is archived (archived), whether all of the messages in the thread have been read (read), whether the viewer has sent a message in the thread (sent).

Functions

This table supports the special function has_tags. This function takes one or more parameters and evaluates to true for threads which contain all of the tags specified as parameters. Negated tags can be specified by prepending the ! (exclamation mark) character to the tag name.