Client

class fbchat.Client(*, session)[source]

A client for Facebook Messenger.

This contains methods that are generally needed to interact with Facebook.

Example

Create a new client instance.

>>> client = fbchat.Client(session=session)
session

The session to use when making requests.

fetch_users()[source]

Fetch users the client is currently chatting with.

This is very close to your friend list, with the follow differences:

It differs by including users that you’re not friends with, but have chatted with before, and by including accounts that are “Messenger Only”.

But does not include deactivated, deleted or memorialized users (logically, since you can’t chat with those).

The order these are returned is arbitrary.

Example

Get the name of an arbitrary user that you’re currently chatting with.

>>> users = client.fetch_users()
>>> users[0].name
"A user"
Return type

Sequence[UserData]

search_for_users(name, limit)[source]

Find and get users by their name.

The returned users are ordered by relevance.

Parameters
  • name (str) – Name of the user

  • limit (int) – The max. amount of users to fetch

Example

Get the full name of the first found user.

>>> (user,) = client.search_for_users("user", limit=1)
>>> user.name
"A user"
Return type

Iterable[UserData]

search_for_pages(name, limit)[source]

Find and get pages by their name.

The returned pages are ordered by relevance.

Parameters
  • name (str) – Name of the page

  • limit (int) – The max. amount of pages to fetch

Example

Get the full name of the first found page.

>>> (page,) = client.search_for_pages("page", limit=1)
>>> page.name
"A page"
Return type

Iterable[PageData]

search_for_groups(name, limit)[source]

Find and get group threads by their name.

The returned groups are ordered by relevance.

Parameters
  • name (str) – Name of the group thread

  • limit (int) – The max. amount of groups to fetch

Example

Get the full name of the first found group.

>>> (group,) = client.search_for_groups("group", limit=1)
>>> group.name
"A group"
Return type

Iterable[GroupData]

search_for_threads(name, limit)[source]

Find and get threads by their name.

The returned threads are ordered by relevance.

Parameters
  • name (str) – Name of the thread

  • limit (int) – The max. amount of threads to fetch

Example

Search for a user, and get the full name of the first found result.

>>> (user,) = client.search_for_threads("user", limit=1)
>>> assert isinstance(user, fbchat.User)
>>> user.name
"A user"
Return type

Iterable[ThreadABC]

search_messages(query, limit)[source]

Search for messages in all threads.

Intended to be used alongside ThreadABC.search_messages.

Warning! If someone send a message to a thread that matches the query, while we’re searching, some snippets will get returned twice, and some will be lost.

This is fundamentally not fixable, it’s just how the endpoint is implemented.

Parameters
  • query (str) – Text to search for

  • limit (Optional[int]) – Max. number of items to retrieve. If None, all will be retrieved

Example

Search for messages, and print the amount of snippets in each thread.

>>> for thread, count in client.search_messages("abc", limit=3):
...     print(f"{thread.id} matched the search {count} time(s)")
...
1234 matched the search 2 time(s)
2345 matched the search 1 time(s)
3456 matched the search 100 time(s)
Return type

Iterable[Tuple[ThreadABC, int]]

Returns

Iterable with tuples of threads, and the total amount of matches.

fetch_thread_info(ids)[source]

Fetch threads’ info from IDs, unordered.

Warning

Sends two requests if users or pages are present, to fetch all available info!

Parameters

ids (Iterable[str]) – Thread ids to query

Example

Get data about the user with id “4”.

>>> (user,) = client.fetch_thread_info(["4"])
>>> user.name
"Mark Zuckerberg"
Return type

Iterable[ThreadABC]

fetch_threads(limit, location=<ThreadLocation.INBOX: 'INBOX'>)[source]

Fetch the client’s thread list.

The returned threads are ordered by last active first.

Parameters
  • limit (Optional[int]) – Max. number of threads to retrieve. If None, all threads will be retrieved.

  • location (ThreadLocation) – INBOX, PENDING, ARCHIVED or OTHER

Example

Fetch the last three threads that the user chatted with.

>>> for thread in client.fetch_threads(limit=3):
...     print(f"{thread.id}: {thread.name}")
...
1234: A user
2345: A group
3456: A page
Return type

Iterable[ThreadABC]

fetch_unread()[source]

Fetch unread threads.

Warning

This is not finished, and the API may change at any point!

Return type

Sequence[ThreadABC]

fetch_unseen()[source]

Fetch unseen / new threads.

Warning

This is not finished, and the API may change at any point!

Return type

Sequence[ThreadABC]

fetch_image_url(image_id)[source]

Fetch URL to download the original image from an image attachment ID.

Parameters

image_id (str) – The image you want to fetch

Example

>>> client.fetch_image_url("1234")
"https://scontent-arn1-1.xx.fbcdn.net/v/t1.123-4/1_23_45_n.png?..."
Return type

str

Returns

An URL where you can download the original image

get_phone_numbers()[source]

Fetch the user’s phone numbers.

Return type

Sequence[str]

get_emails()[source]

Fetch the user’s emails.

Return type

Sequence[str]

upload(files, voice_clip=False)[source]

Upload files to Facebook.

Distribution files should be a list of files that requests can upload, see requests.request.

Example

>>> with open("file.txt", "rb") as f:
...     (file,) = client.upload([("file.txt", f, "text/plain")])
...
>>> file
("1234", "text/plain")
Return type

Sequence[Tuple[str, str]]

Returns

Tuples with a file’s ID and mimetype. This result can be passed straight on to ThreadABC.send_files, or used in Group.set_image.

mark_as_delivered(message)[source]

Mark a message as delivered.

Warning

This is not finished, and the API may change at any point!

Parameters

message (Message) – The message to set as delivered

mark_as_read(threads, at)[source]

Mark threads as read.

All messages inside the specified threads will be marked as read.

Parameters
  • threads (Iterable[ThreadABC]) – Threads to set as read

  • at (datetime) – Timestamp to signal the read cursor at

mark_as_unread(threads, at)[source]

Mark threads as unread.

All messages inside the specified threads will be marked as unread.

Parameters
  • threads (Iterable[ThreadABC]) – Threads to set as unread

  • at (datetime) – Timestamp to signal the read cursor at

move_threads(location, threads)[source]

Move threads to specified location.

Parameters
  • location (ThreadLocation) – INBOX, PENDING, ARCHIVED or OTHER

  • threads (Iterable[ThreadABC]) – Threads to move

delete_threads(threads)[source]

Bulk delete threads.

Parameters

threads (Iterable[ThreadABC]) – Threads to delete

Example

>>> group = fbchat.Group(session=session, id="1234")
>>> client.delete_threads([group])
delete_messages(messages)[source]

Bulk delete specified messages.

Parameters

messages (Iterable[Message]) – Messages to delete

Example

>>> message1 = fbchat.Message(thread=thread, id="1234")
>>> message2 = fbchat.Message(thread=thread, id="2345")
>>> client.delete_threads([message1, message2])