Threads

class fbchat.ThreadABC[source]

Implemented by thread-like classes.

This is private to implement.

abstract property session

The session to use when making requests.

Return type

Session

abstract property id

The unique identifier of the thread.

Return type

str

wave(first=True)[source]

Wave hello to the thread.

Parameters

first (bool) – Whether to wave first or wave back

Example

Wave back to the thread.

>>> thread.wave(False)
Return type

str

send_text(text, mentions=None, files=None, reply_to_id=None)[source]

Send a message to the thread.

Parameters

Example

>>> mention = fbchat.Mention(thread_id="1234", offset=5, length=2)
>>> thread.send_text("A message", mentions=[mention])
Return type

str

Returns

The sent message

send_emoji(emoji, size)[source]

Send an emoji to the thread.

Parameters
  • emoji (str) – The emoji to send

  • size (EmojiSize) – The size of the emoji

Example

>>> thread.send_emoji("😀", size=fbchat.EmojiSize.LARGE)
Return type

str

Returns

The sent message

send_sticker(sticker_id)[source]

Send a sticker to the thread.

Parameters

sticker_id (str) – ID of the sticker to send

Example

Send a sticker with the id “1889713947839631”

>>> thread.send_sticker("1889713947839631")
Return type

str

Returns

The sent message

send_location(latitude, longitude)[source]

Send a given location to a thread as the user’s current location.

Parameters
  • latitude (float) – The location latitude

  • longitude (float) – The location longitude

Example

Send a location in London, United Kingdom.

>>> thread.send_location(51.5287718, -0.2416815)
send_pinned_location(latitude, longitude)[source]

Send a given location to a thread as a pinned location.

Parameters
  • latitude (float) – The location latitude

  • longitude (float) – The location longitude

Example

Send a pinned location in Beijing, China.

>>> thread.send_pinned_location(39.9390731, 116.117273)
send_files(files)[source]

Send files from file IDs to a thread.

Distribution files should be a list of tuples, with a file’s ID and mimetype.

Example

Upload and send a video to a thread.

>>> with open("video.mp4", "rb") as f:
...     files = client.upload([("video.mp4", f, "video/mp4")])
>>>
>>> thread.send_files(files)
search_messages(query, limit)[source]

Find and get message IDs by query.

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

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

The returned message snippets are ordered by last sent first.

Parameters
  • query (str) – Text to search for

  • limit (int) – Max. number of message snippets to retrieve

Example

Fetch the latest message in the thread that matches the query.

>>> (message,) = thread.search_messages("abc", limit=1)
>>> message.text
"Some text and abc"
Return type

Iterable[MessageSnippet]

fetch_messages(limit)[source]

Fetch messages in a thread.

The returned messages are ordered by last sent first.

Parameters

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

Example

>>> for message in thread.fetch_messages(limit=5)
...     print(message.text)
...
A message
Another message
None
A fourth message
Return type

Iterable[Message]

fetch_images(limit)[source]

Fetch images/videos posted in the thread.

The returned images are ordered by last sent first.

Parameters

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

Example

>>> for image in thread.fetch_messages(limit=3)
...     print(image.id)
...
1234
2345
Return type

Iterable[Attachment]

set_nickname(user_id, nickname)[source]

Change the nickname of a user in the thread.

Parameters
  • user_id (str) – User that will have their nickname changed

  • nickname (str) – New nickname

Example

>>> thread.set_nickname("1234", "A nickname")
set_color(color)[source]

Change thread color.

The new color must be one of the following:

"#0084ff", "#44bec7", "#ffc300", "#fa3c4c", "#d696bb", "#6699cc",
"#13cf13", "#ff7e29", "#e68585", "#7646ff", "#20cef5", "#67b868",
"#d4a88c", "#ff5ca1", "#a695c7", "#ff7ca8", "#1adb5b", "#f01d6a",
"#ff9c19" or "#0edcde".

This list is subject to change in the future!

The default when creating a new thread is "#0084ff".

Parameters

color (str) – New thread color

Example

Set the thread color to “Coral Pink”.

>>> thread.set_color("#e68585")
set_emoji(emoji)[source]

Change thread emoji.

Parameters

emoji (Optional[str]) – New thread emoji. If None, will be set to the default “LIKE” icon

Example

Set the thread emoji to “😊”.

>>> thread.set_emoji("😊")
forward_attachment(attachment_id)[source]

Forward an attachment.

Parameters

attachment_id (str) – Attachment ID to forward

Example

>>> thread.forward_attachment("1234")
start_typing()[source]

Set the current user to start typing in the thread.

Example

>>> thread.start_typing()
stop_typing()[source]

Set the current user to stop typing in the thread.

Example

>>> thread.stop_typing()
create_plan(name, at, location_name=None, location_id=None)[source]

Create a new plan.

# TODO: Arguments

Parameters
  • name (str) – Name of the new plan

  • at (datetime) – When the plan is for

Example

>>> thread.create_plan(...)
create_poll(question, options)[source]

Create poll in a thread.

Parameters
  • question (str) – The question

  • options (Mapping[str, bool]) – Options and whether you want to select the option

Example

>>> thread.create_poll("Test poll", {"Option 1": True, "Option 2": False})
mute(duration=None)[source]

Mute the thread.

Parameters

duration (Optional[timedelta]) – Time to mute, use None to mute forever

Example

>>> import datetime
>>> thread.mute(datetime.timedelta(days=2))
unmute()[source]

Unmute the thread.

Example

>>> thread.unmute()
mute_reactions()[source]

Mute thread reactions.

unmute_reactions()[source]

Unmute thread reactions.

mute_mentions()[source]

Mute thread mentions.

unmute_mentions()[source]

Unmute thread mentions.

mark_as_spam()[source]

Mark the thread as spam, and delete it.

delete()[source]

Delete the thread.

If you want to delete multiple threads, please use Client.delete_threads.

Example

>>> message.delete()
class fbchat.Thread(*, session, id)[source]

Represents a Facebook thread, where the actual type is unknown.

Implements parts of ThreadABC, call the method to figure out if your use case is supported. Otherwise, you’ll have to use an User/Group/Page object.

Note: This list may change in minor versions!

session

The session to use when making requests.

id

The unique identifier of the thread.

class fbchat.Page(*, session, id)[source]

Represents a Facebook page. Implements ThreadABC.

Example

>>> page = fbchat.Page(session=session, id="1234")
session

The session to use when making requests.

id

The unique identifier of the page.

class fbchat.User(*, session, id)[source]

Represents a Facebook user. Implements ThreadABC.

Example

>>> user = fbchat.User(session=session, id="1234")
session

The session to use when making requests.

id

The user’s unique identifier.

confirm_friend_request()[source]

Confirm a friend request, adding the user to your friend list.

Example

>>> user.confirm_friend_request()
remove_friend()[source]

Remove the user from the client’s friend list.

Example

>>> user.remove_friend()
block()[source]

Block messages from the user.

Example

>>> user.block()
unblock()[source]

Unblock a previously blocked user.

Example

>>> user.unblock()
class fbchat.Group(*, session, id)[source]

Represents a Facebook group. Implements ThreadABC.

Example

>>> group = fbchat.Group(session=session, id="1234")
session

The session to use when making requests.

id

The group’s unique identifier.

add_participants(user_ids)[source]

Add users to the group.

Parameters

user_ids (Iterable[str]) – One or more user IDs to add

Example

>>> group.add_participants(["1234", "2345"])
remove_participant(user_id)[source]

Remove user from the group.

Parameters

user_id (str) – User ID to remove

Example

>>> group.remove_participant("1234")
add_admins(user_ids)[source]

Set specified users as group admins.

Parameters

user_ids (Iterable[str]) – One or more user IDs to set admin

Example

>>> group.add_admins(["1234", "2345"])
remove_admins(user_ids)[source]

Remove admin status from specified users.

Parameters

user_ids (Iterable[str]) – One or more user IDs to remove admin

Example

>>> group.remove_admins(["1234", "2345"])
set_title(title)[source]

Change title of the group.

Parameters

title (str) – New title

Example

>>> group.set_title("Abc")
set_image(image_id)[source]

Change the group image from an image id.

Parameters

image_id (str) – ID of uploaded image

Example

Upload an image, and use it as the group image.

>>> with open("image.png", "rb") as f:
...     (file,) = client.upload([("image.png", f, "image/png")])
...
>>> group.set_image(file[0])
set_approval_mode(require_admin_approval)[source]

Change the group’s approval mode.

Parameters

require_admin_approval (bool) – True or False

Example

>>> group.set_approval_mode(False)
accept_users(user_ids)[source]

Accept users to the group from the group’s approval.

Parameters

user_ids (Iterable[str]) – One or more user IDs to accept

Example

>>> group.accept_users(["1234", "2345"])
deny_users(user_ids)[source]

Deny users from joining the group.

Parameters

user_ids (Iterable[str]) – One or more user IDs to deny

Example

>>> group.deny_users(["1234", "2345"])