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.
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.
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.
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.
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
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)
-
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!
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
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
- Returns
An URL where you can download the original image
-
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
- Returns
Tuples with a file’s ID and mimetype. This result can be passed straight on to
ThreadABC.send_files
, or used inGroup.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.
-
mark_as_unread
(threads, at)[source]¶ Mark threads as unread.
All messages inside the specified threads will be marked as unread.
-
move_threads
(location, threads)[source]¶ Move threads to specified location.
- Parameters
location (
ThreadLocation
) – INBOX, PENDING, ARCHIVED or OTHERthreads (
Iterable
[ThreadABC
]) – Threads to move
-