fbchat: Facebook Chat (Messenger) for Python¶

Release v1.4.2. (Installation)

Facebook Chat (Messenger) for Python. This project was inspired by facebook-chat-api.

No XMPP or API key is needed. Just use your email and password.

Currently fbchat support Python 2.7, 3.4, 3.5 and 3.6:

fbchat works by emulating the browser. This means doing the exact same GET/POST requests and tricking Facebook into thinking it’s accessing the website normally. Therefore, this API requires the credentials of a Facebook account.

Note

If you’re having problems, please check the FAQ, before asking questions on Github

Warning

We are not responsible if your account gets banned for spammy activities, such as sending lots of messages to people you don’t know, sending messages very quickly, sending spammy looking URLs, logging in and out very quickly… Be responsible Facebook citizens.

Note

Facebook now has an official API for chat bots, so if you’re familiar with node.js, this might be what you’re looking for.

If you’re already familiar with the basics of how Facebook works internally, go to Examples to see example usage of fbchat

Overview¶

Installation¶

Pip Install fbchat¶

To install fbchat, run this command:

$ pip install fbchat

If you don’t have pip installed, this Python installation guide can guide you through the process.

Get the Source Code¶

fbchat is developed on GitHub, where the code is always available.

You can either clone the public repository:

$ git clone git://github.com/carpedm20/fbchat.git

Or, download a tarball:

$ curl -OL https://github.com/carpedm20/fbchat/tarball/master
  # optionally, zipball is also available (for Windows users).

Once you have a copy of the source, you can embed it in your own Python package, or install it into your site-packages easily:

$ python setup.py install

Introduction¶

fbchat uses your email and password to communicate with the Facebook server. That means that you should always store your password in a separate file, in case e.g. someone looks over your shoulder while you’re writing code. You should also make sure that the file’s access control is appropriately restrictive

Logging In¶

Simply create an instance of Client. If you have two factor authentication enabled, type the code in the terminal prompt (If you want to supply the code in another fashion, overwrite Client.on2FACode):

from fbchat import Client
from fbchat.models import *
client = Client('<email>', '<password>')

Replace <email> and <password> with your email and password respectively

Note

For ease of use then most of the code snippets in this document will assume you’ve already completed the login process Though the second line, from fbchat.models import *, is not strictly neccesary here, later code snippets will assume you’ve done this

If you want to change how verbose fbchat is, change the logging level (in Client)

Throughout your code, if you want to check whether you are still logged in, use Client.isLoggedIn. An example would be to login again if you’ve been logged out, using Client.login:

if not client.isLoggedIn():
    client.login('<email>', '<password>')

When you’re done using the client, and want to securely logout, use Client.logout:

client.logout()

Threads¶

A thread can refer to two things: A Messenger group chat or a single Facebook user

models.ThreadType is an enumerator with two values: USER and GROUP. These will specify whether the thread is a single user chat or a group chat. This is required for many of fbchat’s functions, since Facebook differentiates between these two internally

Searching for group chats and finding their ID can be done via. Client.searchForGroups, and searching for users is possible via. Client.searchForUsers. See Fetching Information

You can get your own user ID by using Client.uid

Getting the ID of a group chat is fairly trivial otherwise, since you only need to navigate to https://www.facebook.com/messages/, click on the group you want to find the ID of, and then read the id from the address bar. The URL will look something like this: https://www.facebook.com/messages/t/1234567890, where 1234567890 would be the ID of the group. An image to illustrate this is shown below:

An image illustrating how to find the ID of a group

The same method can be applied to some user accounts, though if they’ve set a custom URL, then you’ll just see that URL instead

Here’s an snippet showing the usage of thread IDs and thread types, where <user id> and <group id> corresponds to the ID of a single user, and the ID of a group respectively:

client.send(Message(text='<message>'), thread_id='<user id>', thread_type=ThreadType.USER)
client.send(Message(text='<message>'), thread_id='<group id>', thread_type=ThreadType.GROUP)

Some functions (e.g. Client.changeThreadColor) don’t require a thread type, so in these cases you just provide the thread ID:

client.changeThreadColor(ThreadColor.BILOBA_FLOWER, thread_id='<user id>')
client.changeThreadColor(ThreadColor.MESSENGER_BLUE, thread_id='<group id>')

Message IDs¶

Every message you send on Facebook has a unique ID, and every action you do in a thread, like changing a nickname or adding a person, has a unique ID too.

Some of fbchat’s functions require these ID’s, like Client.reactToMessage, and some of then provide this ID, like Client.sendMessage. This snippet shows how to send a message, and then use the returned ID to react to that message with a 😍 emoji:

message_id = client.send(Message(text='message'), thread_id=thread_id, thread_type=thread_type)
client.reactToMessage(message_id, MessageReaction.LOVE)

Interacting with Threads¶

fbchat provides multiple functions for interacting with threads

Most functionality works on all threads, though some things, like adding users to and removing users from a group chat, logically only works on group chats

The simplest way of using fbchat is to send a message. The following snippet will, as you’ve probably already figured out, send the message test message to your account:

message_id = client.send(Message(text='test message'), thread_id=client.uid, thread_type=ThreadType.USER)

You can see a full example showing all the possible thread interactions with fbchat by going to Examples

Fetching Information¶

You can use fbchat to fetch basic information like user names, profile pictures, thread names and user IDs

You can retrieve a user’s ID with Client.searchForUsers. The following snippet will search for users by their name, take the first (and most likely) user, and then get their user ID from the result:

users = client.searchForUsers('<name of user>')
user = users[0]
print("User's ID: {}".format(user.uid))
print("User's name: {}".format(user.name))
print("User's profile picture url: {}".format(user.photo))
print("User's main url: {}".format(user.url))

Since this uses Facebook’s search functions, you don’t have to specify the whole name, first names will usually be enough

You can see a full example showing all the possible ways to fetch information with fbchat by going to Examples

Sessions¶

fbchat provides functions to retrieve and set the session cookies. This will enable you to store the session cookies in a separate file, so that you don’t have to login each time you start your script. Use Client.getSession to retrieve the cookies:

session_cookies = client.getSession()

Then you can use Client.setSession:

client.setSession(session_cookies)

Or you can set the session_cookies on your initial login. (If the session cookies are invalid, your email and password will be used to login instead):

client = Client('<email>', '<password>', session_cookies=session_cookies)

Warning

You session cookies can be just as valueable as you password, so store them with equal care

Listening & Events¶

To use the listening functions fbchat offers (like Client.listen), you have to define what should be executed when certain events happen. By default, (most) events will just be a logging.info statement, meaning it will simply print information to the console when an event happens

Note

You can identify the event methods by their on prefix, e.g. onMessage

The event actions can be changed by subclassing the Client, and then overwriting the event methods:

class CustomClient(Client):
    def onMessage(self, mid, author_id, message_object, thread_id, thread_type, ts, metadata, msg, **kwargs):
        # Do something with message_object here
        pass

client = CustomClient('<email>', '<password>')

Notice: The following snippet is as equally valid as the previous one:

class CustomClient(Client):
    def onMessage(self, message_object, author_id, thread_id, thread_type, **kwargs):
        # Do something with message_object here
        pass

client = CustomClient('<email>', '<password>')

The change was in the parameters that our onMessage method took: message_object and author_id got swapped, and mid, ts, metadata and msg got removed, but the function still works, since we included **kwargs

Note

Therefore, for both backwards and forwards compatability, the API actually requires that you include **kwargs as your final argument.

View the Examples to see some more examples illustrating the event system

Examples¶

These are a few examples on how to use fbchat. Remember to swap out <email> and <password> for your email and password

Basic example¶

This will show basic usage of fbchat

# -*- coding: UTF-8 -*-

from fbchat import Client
from fbchat.models import *

client = Client('<email>', '<password>')

print('Own id: {}'.format(client.uid))

client.send(Message(text='Hi me!'), thread_id=client.uid, thread_type=ThreadType.USER)

client.logout()

Interacting with Threads¶

This will interact with the thread in every way fbchat supports

# -*- coding: UTF-8 -*-

from fbchat import Client
from fbchat.models import *

client = Client("<email>", "<password>")

thread_id = '1234567890'
thread_type = ThreadType.GROUP

# Will send a message to the thread
client.send(Message(text='<message>'), thread_id=thread_id, thread_type=thread_type)

# Will send the default `like` emoji
client.send(Message(emoji_size=EmojiSize.LARGE), thread_id=thread_id, thread_type=thread_type)

# Will send the emoji `👍`
client.send(Message(text='👍', emoji_size=EmojiSize.LARGE), thread_id=thread_id, thread_type=thread_type)

# Will send the sticker with ID `767334476626295`
client.send(Message(sticker=Sticker('767334476626295')), thread_id=thread_id, thread_type=thread_type)

# Will send a message with a mention
client.send(Message(text='This is a @mention', mentions=[Mention(thread_id, offset=10, length=8)]), thread_id=thread_id, thread_type=thread_type)

# Will send the image located at `<image path>`
client.sendLocalImage('<image path>', message=Message(text='This is a local image'), thread_id=thread_id, thread_type=thread_type)

# Will download the image at the url `<image url>`, and then send it
client.sendRemoteImage('<image url>', message=Message(text='This is a remote image'), thread_id=thread_id, thread_type=thread_type)


# Only do these actions if the thread is a group
if thread_type == ThreadType.GROUP:
    # Will remove the user with ID `<user id>` from the thread
    client.removeUserFromGroup('<user id>', thread_id=thread_id)

    # Will add the user with ID `<user id>` to the thread
    client.addUsersToGroup('<user id>', thread_id=thread_id)

    # Will add the users with IDs `<1st user id>`, `<2nd user id>` and `<3th user id>` to the thread
    client.addUsersToGroup(['<1st user id>', '<2nd user id>', '<3rd user id>'], thread_id=thread_id)


# Will change the nickname of the user `<user_id>` to `<new nickname>`
client.changeNickname('<new nickname>', '<user id>', thread_id=thread_id, thread_type=thread_type)

# Will change the title of the thread to `<title>`
client.changeThreadTitle('<title>', thread_id=thread_id, thread_type=thread_type)

# Will set the typing status of the thread to `TYPING`
client.setTypingStatus(TypingStatus.TYPING, thread_id=thread_id, thread_type=thread_type)

# Will change the thread color to `MESSENGER_BLUE`
client.changeThreadColor(ThreadColor.MESSENGER_BLUE, thread_id=thread_id)

# Will change the thread emoji to `👍`
client.changeThreadEmoji('👍', thread_id=thread_id)

# Will react to a message with a 😍 emoji
client.reactToMessage('<message id>', MessageReaction.LOVE)

Fetching Information¶

This will show the different ways of fetching information about users and threads

# -*- coding: UTF-8 -*-

from fbchat import Client
from fbchat.models import *

client = Client('<email>', '<password>')

# Fetches a list of all users you're currently chatting with, as `User` objects
users = client.fetchAllUsers()

print("users' IDs: {}".format([user.uid for user in users]))
print("users' names: {}".format([user.name for user in users]))


# If we have a user id, we can use `fetchUserInfo` to fetch a `User` object
user = client.fetchUserInfo('<user id>')['<user id>']
# We can also query both mutiple users together, which returns list of `User` objects
users = client.fetchUserInfo('<1st user id>', '<2nd user id>', '<3rd user id>')

print("user's name: {}".format(user.name))
print("users' names: {}".format([users[k].name for k in users]))


# `searchForUsers` searches for the user and gives us a list of the results,
# and then we just take the first one, aka. the most likely one:
user = client.searchForUsers('<name of user>')[0]

print('user ID: {}'.format(user.uid))
print("user's name: {}".format(user.name))
print("user's photo: {}".format(user.photo))
print("Is user client's friend: {}".format(user.is_friend))


# Fetches a list of the 20 top threads you're currently chatting with
threads = client.fetchThreadList()
# Fetches the next 10 threads
threads += client.fetchThreadList(offset=20, limit=10)

print("Threads: {}".format(threads))


# Gets the last 10 messages sent to the thread
messages = client.fetchThreadMessages(thread_id='<thread id>', limit=10)
# Since the message come in reversed order, reverse them
messages.reverse()

# Prints the content of all the messages
for message in messages:
    print(message.text)


# If we have a thread id, we can use `fetchThreadInfo` to fetch a `Thread` object
thread = client.fetchThreadInfo('<thread id>')['<thread id>']
print("thread's name: {}".format(thread.name))
print("thread's type: {}".format(thread.type))


# `searchForThreads` searches works like `searchForUsers`, but gives us a list of threads instead
thread = client.searchForThreads('<name of thread>')[0]
print("thread's name: {}".format(thread.name))
print("thread's type: {}".format(thread.type))


# Here should be an example of `getUnread`

Echobot¶

This will reply to any message with the same message

# -*- coding: UTF-8 -*-

from fbchat import log, Client

# Subclass fbchat.Client and override required methods
class EchoBot(Client):
    def onMessage(self, author_id, message_object, thread_id, thread_type, **kwargs):
        self.markAsDelivered(thread_id, message_object.uid)
        self.markAsRead(thread_id)

        log.info("{} from {} in {}".format(message_object, thread_id, thread_type.name))

        # If you're not the author, echo
        if author_id != self.uid:
            self.send(message_object, thread_id=thread_id, thread_type=thread_type)

client = EchoBot("<email>", "<password>")
client.listen()

Remove Bot¶

This will remove a user from a group if they write the message Remove me!

# -*- coding: UTF-8 -*-

from fbchat import log, Client
from fbchat.models import *

class RemoveBot(Client):
    def onMessage(self, author_id, message_object, thread_id, thread_type, **kwargs):
        # We can only kick people from group chats, so no need to try if it's a user chat
        if message_object.text == 'Remove me!' and thread_type == ThreadType.GROUP:
            log.info('{} will be removed from {}'.format(author_id, thread_id))
            self.removeUserFromGroup(author_id, thread_id=thread_id)
        else:
            # Sends the data to the inherited onMessage, so that we can still see when a message is recieved
            super(RemoveBot, self).onMessage(author_id=author_id, message_object=message_object, thread_id=thread_id, thread_type=thread_type, **kwargs)

client = RemoveBot("<email>", "<password>")
client.listen()

“Prevent changes”-Bot¶

This will prevent chat color, emoji, nicknames and chat name from being changed. It will also prevent people from being added and removed

# -*- coding: UTF-8 -*-

from fbchat import log, Client
from fbchat.models import *

# Change this to your group id
old_thread_id = '1234567890'

# Change these to match your liking
old_color = ThreadColor.MESSENGER_BLUE
old_emoji = '👍'
old_title = 'Old group chat name'
old_nicknames = {
    '12345678901': "User nr. 1's nickname",
    '12345678902': "User nr. 2's nickname",
    '12345678903': "User nr. 3's nickname",
    '12345678904': "User nr. 4's nickname"
}

class KeepBot(Client):
    def onColorChange(self, author_id, new_color, thread_id, thread_type, **kwargs):
        if old_thread_id == thread_id and old_color != new_color:
            log.info("{} changed the thread color. It will be changed back".format(author_id))
            self.changeThreadColor(old_color, thread_id=thread_id)

    def onEmojiChange(self, author_id, new_emoji, thread_id, thread_type, **kwargs):
        if old_thread_id == thread_id and new_emoji != old_emoji:
            log.info("{} changed the thread emoji. It will be changed back".format(author_id))
            self.changeThreadEmoji(old_emoji, thread_id=thread_id)

    def onPeopleAdded(self, added_ids, author_id, thread_id, **kwargs):
        if old_thread_id == thread_id and author_id != self.uid:
            log.info("{} got added. They will be removed".format(added_ids))
            for added_id in added_ids:
                self.removeUserFromGroup(added_id, thread_id=thread_id)

    def onPersonRemoved(self, removed_id, author_id, thread_id, **kwargs):
        # No point in trying to add ourself
        if old_thread_id == thread_id and removed_id != self.uid and author_id != self.uid:
            log.info("{} got removed. They will be re-added".format(removed_id))
            self.addUsersToGroup(removed_id, thread_id=thread_id)

    def onTitleChange(self, author_id, new_title, thread_id, thread_type, **kwargs):
        if old_thread_id == thread_id and old_title != new_title:
            log.info("{} changed the thread title. It will be changed back".format(author_id))
            self.changeThreadTitle(old_title, thread_id=thread_id, thread_type=thread_type)

    def onNicknameChange(self, author_id, changed_for, new_nickname, thread_id, thread_type, **kwargs):
        if old_thread_id == thread_id and changed_for in old_nicknames and old_nicknames[changed_for] != new_nickname:
            log.info("{} changed {}'s' nickname. It will be changed back".format(author_id, changed_for))
            self.changeNickname(old_nicknames[changed_for], changed_for, thread_id=thread_id, thread_type=thread_type)

client = KeepBot("<email>", "<password>")
client.listen()

Testing¶

To use the tests, copy tests/data.json to tests/my_data.json or type the information manually in the terminal prompts.

email: Your (or a test user’s) email / phone number
password: Your (or a test user’s) password
group_thread_id: A test group that will be used to test group functionality
user_thread_id: A person that will be used to test kick/add functionality (This user should be in the group)

Please remember to test all supported python versions. If you’ve made any changes to the 2FA functionality, test it with a 2FA enabled account.

If you only want to execute specific tests, pass the function names in the command line (not including the test_ prefix). Example:

$ python tests.py sendMessage sessions sendEmoji

Warning

Do not execute the full set of tests in too quick succession. This can get your account temporarily blocked for spam! (You should execute the script at max about 10 times a day)

Full API¶

If you are looking for information on a specific function, class, or method, this part of the documentation is for you.

Client¶

This is the main class of fbchat, which contains all the methods you use to interact with Facebook. You can extend this class, and overwrite the events, to provide custom event handling (mainly used while listening)

class fbchat.Client(email, password, user_agent=None, max_tries=5, session_cookies=None, logging_level=logging.INFO)[source]¶

Initializes and logs in the client

Parameters:

email – Facebook email, id or phone number
password – Facebook account password
user_agent – Custom user agent to use when sending requests. If None, user agent will be chosen from a premade list (see utils.USER_AGENTS)
max_tries (int) – Maximum number of times to try logging in
session_cookies (dict) – Cookies from a previous session (Will default to login if these are invalid)
logging_level (int) – Configures the logging level. Defaults to INFO

Raises:

FBchatException on failed login

acceptUsersToGroup(user_ids, thread_id=None)[source]¶

Accepts users to the group from the group’s approval

Parameters:	user_ids – One or more user IDs to accept thread_id – Group ID to accept users to. See Threads
Raises:	FBchatException if request failed

addGroupAdmins(admin_ids, thread_id=None)[source]¶

Sets specifed users as group admins.

Parameters:	admin_ids – One or more user IDs to set admin thread_id – Group ID to remove people from. See Threads
Raises:	FBchatException if request failed

addUsersToGroup(user_ids, thread_id=None)[source]¶

Adds users to a group.

Parameters:	user_ids (list) – One or more user IDs to add thread_id – Group ID to add people to. See Threads
Raises:	FBchatException if request failed

blockUser(user_id)[source]¶

Blocks messages from a specifed user

Parameters:	user_id – The ID of the user that you want to block
Returns:	Whether the request was successful
Raises:	FBchatException if request failed

changeGroupApprovalMode(require_admin_approval, thread_id=None)[source]¶

Changes group’s approval mode

Parameters:	require_admin_approval – True or False thread_id – Group ID to remove people from. See Threads
Raises:	FBchatException if request failed

changeGroupImageLocal(image_path, thread_id=None)[source]¶

Changes a thread image from a local path

Parameters:	image_path – Path of an image to upload and change thread_id – User/Group ID to change image. See Threads
Raises:	FBchatException if request failed

changeGroupImageRemote(image_url, thread_id=None)[source]¶

Changes a thread image from a URL

Parameters:	image_url – URL of an image to upload and change thread_id – User/Group ID to change image. See Threads
Raises:	FBchatException if request failed

changeNickname(nickname, user_id, thread_id=None, thread_type=ThreadType.USER)[source]¶

Changes the nickname of a user in a thread

Parameters:	nickname – New nickname user_id – User that will have their nickname changed thread_id – User/Group ID to change color of. See Threads thread_type (models.ThreadType) – See Threads
Raises:	FBchatException if request failed

changePlanParticipation(plan, take_part=True)[source]¶

Changes participation in a plan

Parameters:	plan – Plan to take part in or not take_part – Whether to take part in the plan
Raises:	FBchatException if request failed

changeThreadColor(color, thread_id=None)[source]¶

Changes thread color

Parameters:	color (models.ThreadColor) – New thread color thread_id – User/Group ID to change color of. See Threads
Raises:	FBchatException if request failed

changeThreadEmoji(emoji, thread_id=None)[source]¶

Changes thread color

Trivia: While changing the emoji, the Facebook web client actually sends multiple different requests, though only this one is required to make the change

Parameters:	color – New thread emoji thread_id – User/Group ID to change emoji of. See Threads
Raises:	FBchatException if request failed

changeThreadTitle(title, thread_id=None, thread_type=ThreadType.USER)[source]¶

Changes title of a thread. If this is executed on a user thread, this will change the nickname of that user, effectively changing the title

Parameters:	title – New group thread title thread_id – Group ID to change title of. See Threads thread_type (models.ThreadType) – See Threads
Raises:	FBchatException if request failed

createGroup(message, user_ids)[source]¶

Creates a group with the given ids

Parameters:	message – The initial message user_ids – A list of users to create the group with.
Returns:	ID of the new group
Raises:	FBchatException if request failed

createPlan(plan, thread_id=None)[source]¶

Sets a plan

Parameters:	plan (models.Plan) – Plan to set thread_id – User/Group ID to send plan to. See Threads
Raises:	FBchatException if request failed

createPoll(poll, thread_id=None)[source]¶

Creates poll in a group thread

Parameters:	poll (models.Poll) – Poll to create thread_id – User/Group ID to create poll in. See Threads
Raises:	FBchatException if request failed

deleteMessages(message_ids)[source]¶

Deletes specifed messages

Parameters:	message_ids – Message IDs to delete
Returns:	Whether the request was successful
Raises:	FBchatException if request failed

deletePlan(plan)[source]¶

Deletes a plan

Parameters:	plan – Plan to delete
Raises:	FBchatException if request failed

deleteThreads(thread_ids)[source]¶

Deletes threads

Parameters:	thread_ids – Thread IDs to delete. See Threads
Returns:	Whether the request was successful
Raises:	FBchatException if request failed

denyUsersFromGroup(user_ids, thread_id=None)[source]¶

Denies users from the group’s approval

Parameters:	user_ids – One or more user IDs to deny thread_id – Group ID to deny users from. See Threads
Raises:	FBchatException if request failed

doOneListen(markAlive=True)[source]¶

Does one cycle of the listening loop. This method is useful if you want to control fbchat from an external event loop

Parameters:	markAlive (bool) – Whether this should ping the Facebook server before running
Returns:	Whether the loop should keep running
Return type:	bool

editPlan(plan, new_plan)[source]¶

Edits a plan

Parameters:	plan (models.Plan) – Plan to edit new_plan – New plan
Raises:	FBchatException if request failed

eventReminder(thread_id, time, title, location='', location_id='')[source]¶: Deprecated. Use fbchat.Client.createPlan instead

fetchAllUsers()[source]¶

Gets all users the client is currently chatting with

Returns:	`models.User` objects
Return type:	list
Raises:	FBchatException if request failed

fetchGroupInfo(*group_ids)[source]¶

Get groups’ info from IDs, unordered

Parameters:	group_ids – One or more group ID(s) to query
Returns:	`models.Group` objects, labeled by their ID
Return type:	dict
Raises:	FBchatException if request failed

fetchImageUrl(image_id)[source]¶

Fetches the url to the original image from an image attachment ID

Parameters:	image_id (str) – The image you want to fethc
Returns:	An url where you can download the original image
Return type:	str
Raises:	FBChatException if request failed

fetchMessageInfo(mid, thread_id=None)[source]¶

Fetches models.Message object from the message id

Parameters:	mid – Message ID to fetch from thread_id – User/Group ID to get message info from. See Threads
Returns:	`models.Message` object
Return type:	models.Message
Raises:	FBChatException if request failed

fetchPageInfo(*page_ids)[source]¶

Get pages’ info from IDs, unordered

Warning

Sends two requests, to fetch all available info!

Parameters:	page_ids – One or more page ID(s) to query
Returns:	`models.Page` objects, labeled by their ID
Return type:	dict
Raises:	FBchatException if request failed

fetchPlanInfo(plan_id)[source]¶

Fetches a models.Plan object from the plan id

Parameters:	plan_id – Plan ID to fetch from
Returns:	`models.Plan` object
Return type:	models.Plan
Raises:	FBChatException if request failed

fetchPollOptions(poll_id)[source]¶

Fetches list of models.PollOption objects from the poll id

Parameters:	poll_id – Poll ID to fetch from
Return type:	list
Raises:	FBChatException if request failed

fetchThreadInfo(*thread_ids)[source]¶

Get threads’ info from IDs, unordered

Warning

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

Parameters:	thread_ids – One or more thread ID(s) to query
Returns:	`models.Thread` objects, labeled by their ID
Return type:	dict
Raises:	FBchatException if request failed

fetchThreadList(offset=None, limit=20, thread_location=ThreadLocation.INBOX, before=None)[source]¶

Get thread list of your facebook account

Parameters:	offset – Deprecated. Do not use! limit (int) – Max. number of threads to retrieve. Capped at 20 thread_location – models.ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER before (int) – A timestamp (in milliseconds), indicating from which point to retrieve threads
Returns:	`models.Thread` objects
Return type:	list
Raises:	FBchatException if request failed

fetchThreadMessages(thread_id=None, limit=20, before=None)[source]¶

Get the last messages in a thread

Parameters:	thread_id – User/Group ID to get messages from. See Threads limit (int) – Max. number of messages to retrieve before (int) – A timestamp, indicating from which point to retrieve messages
Returns:	`models.Message` objects
Return type:	list
Raises:	FBchatException if request failed

fetchUnread()[source]¶

Get the unread thread list

Returns:	List of unread thread ids
Return type:	list
Raises:	FBchatException if request failed

fetchUnseen()[source]¶

Get the unseen (new) thread list

Returns:	List of unseen thread ids
Return type:	list
Raises:	FBchatException if request failed

fetchUserInfo(*user_ids)[source]¶

Get users’ info from IDs, unordered

Warning

Sends two requests, to fetch all available info!

Parameters:	user_ids – One or more user ID(s) to query
Returns:	`models.User` objects, labeled by their ID
Return type:	dict
Raises:	FBchatException if request failed

friendConnect(friend_id)[source]¶: Todo

Documenting this

getSession()[source]¶

Retrieves session cookies

Returns:	A dictionay containing session cookies
Return type:	dict

graphql_request(query)[source]¶

Shorthand for graphql_requests(query)[0]

Raises:	FBchatException if request failed

graphql_requests(*queries)[source]¶

Parameters:	queries (GraphQL) – Zero or more GraphQL objects
Raises:	FBchatException if request failed
Returns:	A tuple containing json graphql queries
Return type:	tuple

isLoggedIn()[source]¶

Sends a request to Facebook to check the login status

Returns:	True if the client is still logged in
Return type:	bool

listen(markAlive=True)[source]¶

Initializes and runs the listening loop continually

Parameters:	markAlive (bool) – Whether this should ping the Facebook server each time the loop runs

listening = False¶: Whether the client is listening. Used when creating an external event loop to determine when to stop listening

login(email, password, max_tries=5)[source]¶

Uses email and password to login the user (If the user is already logged in, this will do a re-login)

Parameters:	email – Facebook email or id or phone number password – Facebook account password max_tries (int) – Maximum number of times to try logging in
Raises:	FBchatException on failed login

logout()[source]¶

Safely logs out the client

Parameters:	timeout – See requests timeout
Returns:	True if the action was successful
Return type:	bool

markAsDelivered(thread_id, message_id)[source]¶

Mark a message as delivered

Parameters:	thread_id – User/Group ID to which the message belongs. See Threads message_id – Message ID to set as delivered. See Threads
Returns:	Whether the request was successful
Raises:	FBchatException if request failed

markAsRead(thread_ids=None)[source]¶

Mark threads as read All messages inside the threads will be marked as read

Parameters:	thread_ids – User/Group IDs to set as read. See Threads
Returns:	Whether the request was successful
Raises:	FBchatException if request failed

markAsSeen()[source]¶: Todo

Documenting this

markAsSpam(thread_id=None)[source]¶

Mark a thread as spam and delete it

Parameters:	thread_id – User/Group ID to mark as spam. See Threads
Returns:	Whether the request was successful
Raises:	FBchatException if request failed

markAsUnread(thread_ids=None)[source]¶

Mark threads as unread All messages inside the threads will be marked as unread

Parameters:	thread_ids – User/Group IDs to set as unread. See Threads
Returns:	Whether the request was successful
Raises:	FBchatException if request failed

moveThreads(location, thread_ids)[source]¶

Moves threads to specifed location

Parameters:	location – models.ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER thread_ids – Thread IDs to move. See Threads
Returns:	Whether the request was successful
Raises:	FBchatException if request failed

muteThread(mute_time=-1, thread_id=None)[source]¶

Mutes thread

Parameters:	mute_time – Mute time in seconds, leave blank to mute forever thread_id – User/Group ID to mute. See Threads

muteThreadMentions(mute=True, thread_id=None)[source]¶

Mutes thread mentions

Parameters:	mute – Boolean. True to mute, False to unmute thread_id – User/Group ID to mute. See Threads

muteThreadReactions(mute=True, thread_id=None)[source]¶

Mutes thread reactions

Parameters:	mute – Boolean. True to mute, False to unmute thread_id – User/Group ID to mute. See Threads

on2FACode()[source]¶: Called when a 2FA code is needed to progress

onAdminAdded(mid=None, added_id=None, author_id=None, thread_id=None, thread_type=ThreadType.GROUP, ts=None, msg=None)[source]¶

Called when the client is listening, and somebody adds an admin to a group thread

Parameters:	mid – The action ID added_id – The ID of the admin who got added author_id – The ID of the person who added the admins thread_id – Thread ID that the action was sent to. See Threads ts – A timestamp of the action msg – A full set of the data recieved

onAdminRemoved(mid=None, removed_id=None, author_id=None, thread_id=None, thread_type=ThreadType.GROUP, ts=None, msg=None)[source]¶

Called when the client is listening, and somebody removes an admin from a group thread

Parameters:	mid – The action ID removed_id – The ID of the admin who got removed author_id – The ID of the person who removed the admins thread_id – Thread ID that the action was sent to. See Threads ts – A timestamp of the action msg – A full set of the data recieved

onApprovalModeChange(mid=None, approval_mode=None, author_id=None, thread_id=None, thread_type=ThreadType.GROUP, ts=None, msg=None)[source]¶

Called when the client is listening, and somebody changes approval mode in a group thread

Parameters:	mid – The action ID approval_mode – True if approval mode is activated author_id – The ID of the person who changed approval mode thread_id – Thread ID that the action was sent to. See Threads ts – A timestamp of the action msg – A full set of the data recieved

onCallEnded(mid=None, caller_id=None, is_video_call=None, call_duration=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Todo

Make this work with private calls

Called when the client is listening, and somebody ends a call in a group

Parameters:

mid – The action ID
caller_id – The ID of the person who ended the call
is_video_call – True if it was video call
call_duration – Call duration in seconds
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onCallStarted(mid=None, caller_id=None, is_video_call=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Todo

Make this work with private calls

Called when the client is listening, and somebody starts a call in a group

Parameters:

mid – The action ID
caller_id – The ID of the person who started the call
is_video_call – True if it’s video call
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onChatTimestamp(buddylist=None, msg=None)[source]¶

Called when the client receives chat online presence update

Parameters:	buddylist – A list of dicts with friend id and last seen timestamp msg – A full set of the data recieved

onColorChange(mid=None, author_id=None, new_color=None, thread_id=None, thread_type=ThreadType.USER, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody changes a thread’s color

Parameters:

mid – The action ID
author_id – The ID of the person who changed the color
new_color (models.ThreadColor) – The new color
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onEmojiChange(mid=None, author_id=None, new_emoji=None, thread_id=None, thread_type=ThreadType.USER, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody changes a thread’s emoji

Parameters:

mid – The action ID
author_id – The ID of the person who changed the emoji
new_emoji – The new emoji
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onFriendRequest(from_id=None, msg=None)[source]¶

Called when the client is listening, and somebody sends a friend request

Parameters:	from_id – The ID of the person that sent the request msg – A full set of the data recieved

onGamePlayed(mid=None, author_id=None, game_id=None, game_name=None, score=None, leaderboard=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody plays a game

Parameters:

mid – The action ID
author_id – The ID of the person who played the game
game_id – The ID of the game
game_name – Name of the game
score – Score obtained in the game
leaderboard – Actual leaderboard of the game in the thread
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onImageChange(mid=None, author_id=None, new_image=None, thread_id=None, thread_type=ThreadType.GROUP, ts=None)[source]¶

Called when the client is listening, and somebody changes the image of a thread

Parameters:	mid – The action ID new_image – The ID of the new image author_id – The ID of the person who changed the image thread_id – Thread ID that the action was sent to. See Threads ts – A timestamp of the action

onInbox(unseen=None, unread=None, recent_unread=None, msg=None)[source]¶

Todo

Documenting this

Parameters:	unseen – – unread – – recent_unread – – msg – A full set of the data recieved

onListenError(exception=None)[source]¶

Called when an error was encountered while listening

Parameters:	exception – The exception that was encountered
Returns:	Whether the loop should keep running

onListening()[source]¶: Called when the client is listening

onLoggedIn(email=None)[source]¶

Called when the client is successfully logged in

Parameters:	email – The email of the client

onLoggingIn(email=None)[source]¶

Called when the client is logging in

Parameters:	email – The email of the client

onMarkedSeen(threads=None, seen_ts=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and the client has successfully marked threads as seen

Parameters:	threads – The threads that were marked author_id – The ID of the person who changed the emoji seen_ts – A timestamp of when the threads were seen ts – A timestamp of the action metadata – Extra metadata about the action msg – A full set of the data recieved

onMessage(mid=None, author_id=None, message=None, message_object=None, thread_id=None, thread_type=ThreadType.USER, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody sends a message

Parameters:

mid – The message ID
author_id – The ID of the author
message – (deprecated. Use message_object.text instead)
message_object (models.Message) – The message (As a Message object)
thread_id – Thread ID that the message was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the message was sent to. See Threads
ts – The timestamp of the message
metadata – Extra metadata about the message
msg – A full set of the data recieved

onMessageDelivered(msg_ids=None, delivered_for=None, thread_id=None, thread_type=ThreadType.USER, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody marks messages as delivered

Parameters:

msg_ids – The messages that are marked as delivered
delivered_for – The person that marked the messages as delivered
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onMessageError(exception=None, msg=None)[source]¶

Called when an error was encountered while parsing recieved data

Parameters:	exception – The exception that was encountered msg – A full set of the data recieved

onMessageSeen(seen_by=None, thread_id=None, thread_type=ThreadType.USER, seen_ts=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody marks a message as seen

Parameters:

seen_by – The ID of the person who marked the message as seen
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
seen_ts – A timestamp of when the person saw the message
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onNicknameChange(mid=None, author_id=None, changed_for=None, new_nickname=None, thread_id=None, thread_type=ThreadType.USER, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody changes the nickname of a person

Parameters:

mid – The action ID
author_id – The ID of the person who changed the nickname
changed_for – The ID of the person whom got their nickname changed
new_nickname – The new nickname
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onPeopleAdded(mid=None, added_ids=None, author_id=None, thread_id=None, ts=None, msg=None)[source]¶

Called when the client is listening, and somebody adds people to a group thread

Parameters:	mid – The action ID added_ids – The IDs of the people who got added author_id – The ID of the person who added the people thread_id – Thread ID that the action was sent to. See Threads ts – A timestamp of the action msg – A full set of the data recieved

onPersonRemoved(mid=None, removed_id=None, author_id=None, thread_id=None, ts=None, msg=None)[source]¶

Called when the client is listening, and somebody removes a person from a group thread

Parameters:	mid – The action ID removed_id – The ID of the person who got removed author_id – The ID of the person who removed the person thread_id – Thread ID that the action was sent to. See Threads ts – A timestamp of the action msg – A full set of the data recieved

onPlanCreated(mid=None, plan=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody creates a plan

Parameters:

mid – The action ID
plan (models.Plan) – Created plan
author_id – The ID of the person who created the plan
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onPlanDeleted(mid=None, plan=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody deletes a plan

Parameters:

mid – The action ID
plan (models.Plan) – Deleted plan
author_id – The ID of the person who deleted the plan
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onPlanEdited(mid=None, plan=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody edits a plan

Parameters:

mid – The action ID
plan (models.Plan) – Edited plan
author_id – The ID of the person who edited the plan
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onPlanEnded(mid=None, plan=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and a plan ends

Parameters:	mid – The action ID plan (models.Plan) – Ended plan thread_id – Thread ID that the action was sent to. See Threads thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads ts – A timestamp of the action metadata – Extra metadata about the action msg – A full set of the data recieved

onPlanParticipation(mid=None, plan=None, take_part=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody takes part in a plan or not

Parameters:

mid – The action ID
plan (models.Plan) – Plan
take_part – Whether the person takes part in the plan or not
author_id – The ID of the person who will participate in the plan or not
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onPollCreated(mid=None, poll=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody creates a group poll

Parameters:

mid – The action ID
poll (models.Poll) – Created poll
author_id – The ID of the person who created the poll
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onPollVoted(mid=None, poll=None, added_options=None, removed_options=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody votes in a group poll

Parameters:

mid – The action ID
poll (models.Poll) – Poll, that user voted in
author_id – The ID of the person who voted in the poll
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onQprimer(ts=None, msg=None)[source]¶

Called when the client just started listening

Parameters:	ts – A timestamp of the action msg – A full set of the data recieved

onTitleChange(mid=None, author_id=None, new_title=None, thread_id=None, thread_type=ThreadType.USER, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody changes the title of a thread

Parameters:

mid – The action ID
author_id – The ID of the person who changed the title
new_title – The new title
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

onTyping(author_id=None, status=None, thread_id=None, thread_type=None, msg=None)[source]¶

Called when the client is listening, and somebody starts or stops typing into a chat

Parameters:	author_id – The ID of the person who sent the action status – The typing status thread_id – Thread ID that the action was sent to. See Threads thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads msg – A full set of the data recieved

onUnknownMesssageType(msg=None)[source]¶

Called when the client is listening, and some unknown data was recieved

Parameters:	msg – A full set of the data recieved

onUserJoinedCall(mid=None, joined_id=None, is_video_call=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)[source]¶

Called when the client is listening, and somebody joins a group call

Parameters:

mid – The action ID
joined_id – The ID of the person who joined the call
is_video_call – True if it’s video call
thread_id – Thread ID that the action was sent to. See Threads
thread_type (models.ThreadType) – Type of thread that the action was sent to. See Threads
ts – A timestamp of the action
metadata – Extra metadata about the action
msg – A full set of the data recieved

reactToMessage(message_id, reaction)[source]¶

Reacts to a message

Parameters:	message_id – Message ID to react to reaction (models.MessageReaction) – Reaction emoji to use
Raises:	FBchatException if request failed

removeFriend(friend_id=None)[source]¶

Removes a specifed friend from your friend list

Parameters:	friend_id – The ID of the friend that you want to remove
Returns:	Returns error if the removing was unsuccessful, returns True when successful.

removeGroupAdmins(admin_ids, thread_id=None)[source]¶

Removes admin status from specifed users.

Parameters:	admin_ids – One or more user IDs to remove admin thread_id – Group ID to remove people from. See Threads
Raises:	FBchatException if request failed

removeUserFromGroup(user_id, thread_id=None)[source]¶

Removes users from a group.

Parameters:	user_id – User ID to remove thread_id – Group ID to remove people from. See Threads
Raises:	FBchatException if request failed

resetDefaultThread()[source]¶: Resets default thread

search(query, fetch_messages=False, thread_limit=5, message_limit=5)[source]¶

Searches for messages in all threads

Parameters:	query – Text to search for fetch_messages – Whether to fetch `models.Message` objects or IDs only thread_limit (int) – Max. number of threads to retrieve message_limit (int) – Max. number of messages to retrieve
Returns:	Dictionary with thread IDs as keys and generators to get messages as values
Return type:	generator
Raises:	FBchatException if request failed

searchForGroups(name, limit=1)[source]¶

Find and get group thread by its name

Parameters:	name – Name of the group thread limit – The max. amount of groups to fetch
Returns:	`models.Group` objects, ordered by relevance
Return type:	list
Raises:	FBchatException if request failed

searchForMessageIDs(query, offset=0, limit=5, thread_id=None)[source]¶

Find and get message IDs by query

Parameters:	query – Text to search for offset (int) – Number of messages to skip limit (int) – Max. number of messages to retrieve thread_id – User/Group ID to search in. See Threads
Returns:	Found Message IDs
Return type:	generator
Raises:	FBchatException if request failed

searchForMessages(query, offset=0, limit=5, thread_id=None)[source]¶

Find and get models.Message objects by query

Warning

This method sends request for every found message ID.

Parameters:	query – Text to search for offset (int) – Number of messages to skip limit (int) – Max. number of messages to retrieve thread_id – User/Group ID to search in. See Threads
Returns:	Found `models.Message` objects
Return type:	generator
Raises:	FBchatException if request failed

searchForPages(name, limit=1)[source]¶

Find and get page by its name

Parameters:	name – Name of the page
Returns:	`models.Page` objects, ordered by relevance
Return type:	list
Raises:	FBchatException if request failed

searchForThreads(name, limit=1)[source]¶

Find and get a thread by its name

Parameters:	name – Name of the thread limit – The max. amount of groups to fetch
Returns:	`models.User`, `models.Group` and `models.Page` objects, ordered by relevance
Return type:	list
Raises:	FBchatException if request failed

searchForUsers(name, limit=1)[source]¶

Find and get user by his/her name

Parameters:	name – Name of the user limit – The max. amount of users to fetch
Returns:	`models.User` objects, ordered by relevance
Return type:	list
Raises:	FBchatException if request failed

send(message, thread_id=None, thread_type=ThreadType.USER)[source]¶

Sends a message to a thread

Parameters:	message (models.Message) – Message to send thread_id – User/Group ID to send to. See Threads thread_type (models.ThreadType) – See Threads
Returns:	Message ID of the sent message
Raises:	FBchatException if request failed

sendEmoji(emoji=None, size=EmojiSize.SMALL, thread_id=None, thread_type=ThreadType.USER)[source]¶: Deprecated. Use fbchat.Client.send instead

sendImage(image_id, message=None, thread_id=None, thread_type=ThreadType.USER, is_gif=False)[source]¶: Deprecated. Use fbchat.Client._sendFiles instead

sendLocalFiles(file_paths, message=None, thread_id=None, thread_type=ThreadType.USER)[source]¶

Sends local files to a thread

Parameters:	file_path – Paths of files to upload and send message – Additional message thread_id – User/Group ID to send to. See Threads thread_type (models.ThreadType) – See Threads
Returns:	Message ID of the sent files
Raises:	FBchatException if request failed

sendLocalImage(image_path, message=None, thread_id=None, thread_type=ThreadType.USER)[source]¶: Deprecated. Use fbchat.Client.sendLocalFiles instead

sendMessage(message, thread_id=None, thread_type=ThreadType.USER)[source]¶: Deprecated. Use fbchat.Client.send instead

sendRemoteFiles(file_urls, message=None, thread_id=None, thread_type=ThreadType.USER)[source]¶

Sends files from URLs to a thread

Parameters:	file_urls – URLs of files to upload and send message – Additional message thread_id – User/Group ID to send to. See Threads thread_type (models.ThreadType) – See Threads
Returns:	Message ID of the sent files
Raises:	FBchatException if request failed

sendRemoteImage(image_url, message=None, thread_id=None, thread_type=ThreadType.USER)[source]¶: Deprecated. Use fbchat.Client.sendRemoteFiles instead

setDefaultThread(thread_id, thread_type)[source]¶

Sets default thread to send messages to

Parameters:	thread_id – User/Group ID to default to. See Threads thread_type (models.ThreadType) – See Threads

setSession(session_cookies)[source]¶

Loads session cookies

Parameters:	session_cookies (dict) – A dictionay containing session cookies
Returns:	False if session_cookies does not contain proper cookies
Return type:	bool

setTypingStatus(status, thread_id=None, thread_type=None)[source]¶

Sets users typing status in a thread

Parameters:	status (models.TypingStatus) – Specify the typing status thread_id – User/Group ID to change status in. See Threads thread_type (models.ThreadType) – See Threads
Raises:	FBchatException if request failed

ssl_verify = True¶: Verify ssl certificate, set to False to allow debugging with a proxy

startListening()[source]¶

Start listening from an external event loop

Raises:	FBchatException if request failed

stopListening()[source]¶: Cleans up the variables from startListening

uid = None¶

The ID of the client. Can be used as thread_id. See Threads for more info.

Note: Modifying this results in undefined behaviour

unblockUser(user_id)[source]¶

Unblocks messages from a blocked user

Parameters:	user_id – The ID of the user that you want to unblock
Returns:	Whether the request was successful
Raises:	FBchatException if request failed

unmuteThread(thread_id=None)[source]¶

Unmutes thread

Parameters:	thread_id – User/Group ID to unmute. See Threads

unmuteThreadMentions(thread_id=None)[source]¶

Unmutes thread mentions

Parameters:	thread_id – User/Group ID to unmute. See Threads

unmuteThreadReactions(thread_id=None)[source]¶

Unmutes thread reactions

Parameters:	thread_id – User/Group ID to unmute. See Threads

updatePollVote(poll_id, option_ids=[], new_options=[])[source]¶

Updates a poll vote

Parameters:	poll_id – ID of the poll to update vote option_ids – List of the option IDs to vote new_options – List of the new option names thread_id – User/Group ID to change status in. See Threads thread_type (models.ThreadType) – See Threads
Raises:	FBchatException if request failed

wave(wave_first=True, thread_id=None, thread_type=None)[source]¶

Says hello with a wave to a thread!

Parameters:	wave_first – Whether to wave first or wave back thread_id – User/Group ID to send to. See Threads thread_type (models.ThreadType) – See Threads
Returns:	Message ID of the sent message
Raises:	FBchatException if request failed

Models¶

These models are used in various functions, both as inputs and return values. A good tip is to write from fbchat.models import * at the start of your source, so you can use these models freely

class fbchat.models.Attachment(uid=None)[source]¶

Represents a Facebook attachment

uid = None¶: The attachment ID

class fbchat.models.AudioAttachment(filename=None, url=None, duration=None, audio_type=None, **kwargs)[source]¶

Represents an audio file that has been sent as a Facebook attachment

audio_type = None¶: Audio type

duration = None¶: Duration of the audioclip in milliseconds

filename = None¶: Name of the file

url = None¶: Url of the audio file

class fbchat.models.EmojiSize[source]¶

Used to specify the size of a sent emoji

LARGE = '369239383222810'¶

MEDIUM = '369239343222814'¶

SMALL = '369239263222822'¶

class fbchat.models.Enum[source]¶: Used internally by fbchat to support enumerations

exception fbchat.models.FBchatException[source]¶: Custom exception thrown by fbchat. All exceptions in the fbchat module inherits this

exception fbchat.models.FBchatFacebookError(message, fb_error_code=None, fb_error_message=None, request_status_code=None)[source]¶

fb_error_code = None¶: The error code that Facebook returned

fb_error_message = None¶: The error message that Facebook returned (In the user’s own language)

request_status_code = None¶: The status code that was sent in the http response (eg. 404) (Usually only set if not successful, aka. not 200)

exception fbchat.models.FBchatUserError[source]¶: Thrown by fbchat when wrong values are entered

class fbchat.models.FileAttachment(url=None, size=None, name=None, is_malicious=None, **kwargs)[source]¶

Represents a file that has been sent as a Facebook attachment

is_malicious = None¶: Whether Facebook determines that this file may be harmful

name = None¶: Name of the file

size = None¶: Size of the file in bytes

url = None¶: Url where you can download the file

class fbchat.models.Group(uid, participants=None, nicknames=None, color=None, emoji=None, admins=None, approval_mode=None, approval_requests=None, join_link=None, privacy_mode=None, **kwargs)[source]¶

Represents a Facebook group. Inherits Thread

admins = None¶

approval_mode = None¶

approval_requests = None¶

color = None¶: A ThreadColor. The groups’s message color

emoji = None¶: The groups’s default emoji

join_link = None¶

nicknames = None¶: A dict, containing user nicknames mapped to their IDs

participants = None¶: Unique list (set) of the group thread’s participant user IDs

class fbchat.models.ImageAttachment(original_extension=None, width=None, height=None, is_animated=None, thumbnail_url=None, preview=None, large_preview=None, animated_preview=None, **kwargs)[source]¶

Represents an image that has been sent as a Facebook attachment To retrieve the full image url, use: fbchat.Client.fetchImageUrl, and pass it the uid of the image attachment

animated_preview_height = None¶: Height of the animated preview image

animated_preview_url = None¶: URL to an animated preview of the image (eg. for gifs)

animated_preview_width = None¶: Width of the animated preview image

height = None¶: Height of original image

is_animated = None¶: Whether the image is animated

large_preview_height = None¶: Height of the large preview image

large_preview_url = None¶: URL to a large preview of the image

large_preview_width = None¶: Width of the large preview image

original_extension = None¶: The extension of the original image (eg. ‘png’)

preview_height = None¶: Height of the medium preview image

preview_url = None¶: URL to a medium preview of the image

preview_width = None¶: Width of the medium preview image

thumbnail_url = None¶: URL to a thumbnail of the image

width = None¶: Width of original image

class fbchat.models.Mention(thread_id, offset=0, length=10)[source]¶

Represents a @mention

length = None¶: The length of the mention

offset = None¶: The character where the mention starts

thread_id = None¶: The thread ID the mention is pointing at

class fbchat.models.Message(text=None, mentions=None, emoji_size=None, sticker=None, attachments=None)[source]¶

Represents a Facebook message

attachments = None¶: A list of attachments

author = None¶: ID of the sender

emoji_size = None¶: A EmojiSize. Size of a sent emoji

is_read = None¶: Whether the message is read

mentions = None¶: A list of Mention objects

reactions = None¶: A dict with user’s IDs as keys, and their MessageReaction as values

read_by = None¶: A list of pepole IDs who read the message, works only with fbchat.Client.fetchThreadMessages

sticker = None¶: A Sticker

text = None¶: The actual message

timestamp = None¶: Timestamp of when the message was sent

uid = None¶: The message ID

class fbchat.models.MessageReaction[source]¶

Used to specify a message reaction

ANGRY = '😠'¶

LOVE = '😍'¶

NO = '👎'¶

SAD = '😢'¶

SMILE = '😆'¶

WOW = '😮'¶

YES = '👍'¶

class fbchat.models.Page(uid, url=None, city=None, likes=None, sub_title=None, category=None, **kwargs)[source]¶

Represents a Facebook page. Inherits Thread

category = None¶: The page’s category

city = None¶: The name of the page’s location city

likes = None¶: Amount of likes the page has

sub_title = None¶: Some extra information about the page

url = None¶: The page’s custom url

class fbchat.models.Plan(time, title, location=None, location_id=None)[source]¶

Represents a plan

author_id = None¶: ID of the plan creator

declined = None¶: List of the people IDs who won’t take part in the plan

going = None¶: List of the people IDs who will take part in the plan

invited = None¶: List of the people IDs who are invited to the plan

location = None¶: Plan location name

location_id = None¶: Plan location ID

time = None¶: Plan time (unix time stamp), only precise down to the minute

title = None¶: Plan title

uid = None¶: ID of the plan

class fbchat.models.Poll(title, options)[source]¶

Represents a poll

options = None¶: List of PollOption, can be fetched with fbchat.Client.fetchPollOptions

options_count = None¶: Options count

title = None¶: Title of the poll

uid = None¶: ID of the poll

class fbchat.models.PollOption(text, vote=False)[source]¶

Represents a poll option

text = None¶: Text of the poll option

uid = None¶: ID of the poll option

vote = None¶: Whether vote when creating or client voted

voters = None¶: ID of the users who voted for this poll option

votes_count = None¶: Votes count

class fbchat.models.Room(uid, privacy_mode=None, **kwargs)[source]¶

Deprecated. Use Group instead

privacy_mode = None¶

class fbchat.models.ShareAttachment(**kwargs)[source]¶: Represents a shared item (eg. URL) that has been sent as a Facebook attachment - Currently Incomplete!

class fbchat.models.Sticker(*args, **kwargs)[source]¶

Represents a Facebook sticker that has been sent to a Facebook thread as an attachment

frame_rate = None¶: The frame rate the spritemap is intended to be played in

frames_per_col = None¶: The amount of frames present in the spritemap pr. coloumn

frames_per_row = None¶: The amount of frames present in the spritemap pr. row

height = None¶: Height of the sticker

is_animated = False¶: Whether the sticker is animated

label = None¶: The sticker’s label/name

large_sprite_image = None¶: URL to a large spritemap

medium_sprite_image = None¶: URL to a medium spritemap

pack = None¶: The sticker-pack’s ID

url = None¶: URL to the sticker’s image

width = None¶: Width of the sticker

class fbchat.models.Thread(_type, uid, photo=None, name=None, last_message_timestamp=None, message_count=None, plan=None)[source]¶

Represents a Facebook thread

last_message_timestamp = None¶: Timestamp of last message

message_count = None¶: Number of messages in the thread

name = None¶: The name of the thread

photo = None¶: A url to the thread’s picture

plan = None¶: Set Plan

type = None¶: Specifies the type of thread. Can be used a thread_type. See Threads for more info

uid = None¶: The unique identifier of the thread. Can be used a thread_id. See Threads for more info

class fbchat.models.ThreadColor[source]¶

Used to specify a thread colors

BILOBA_FLOWER = '#a695c7'¶

BRILLIANT_ROSE = '#ff5ca1'¶

CAMEO = '#d4a88c'¶

DEEP_SKY_BLUE = '#20cef5'¶

FERN = '#67b868'¶

FREE_SPEECH_GREEN = '#13cf13'¶

GOLDEN_POPPY = '#ffc300'¶

LIGHT_CORAL = '#e68585'¶

MEDIUM_SLATE_BLUE = '#7646ff'¶

MESSENGER_BLUE = '#0084ff'¶

PICTON_BLUE = '#6699cc'¶

PUMPKIN = '#ff7e29'¶

RADICAL_RED = '#fa3c4c'¶

SHOCKING = '#d696bb'¶

VIKING = '#44bec7'¶

class fbchat.models.ThreadLocation[source]¶

Used to specify where a thread is located (inbox, pending, archived, other).

ARCHIVED = 'ARCHIVED'¶

INBOX = 'INBOX'¶

OTHER = 'OTHER'¶

PENDING = 'PENDING'¶

class fbchat.models.ThreadType[source]¶

Used to specify what type of Facebook thread is being used. See Threads for more info

GROUP = 2¶

PAGE = 3¶

ROOM = 2¶

USER = 1¶

class fbchat.models.TypingStatus[source]¶

Used to specify whether the user is typing or has stopped typing

STOPPED = 0¶

TYPING = 1¶

class fbchat.models.User(uid, url=None, first_name=None, last_name=None, is_friend=None, gender=None, affinity=None, nickname=None, own_nickname=None, color=None, emoji=None, **kwargs)[source]¶

Represents a Facebook user. Inherits Thread

affinity = None¶: From 0 to 1. How close the client is to the user

color = None¶: A ThreadColor. The message color

emoji = None¶: The default emoji

first_name = None¶: The users first name

gender = None¶: The user’s gender

is_friend = None¶: Whether the user and the client are friends

last_name = None¶: The users last name

nickname = None¶: The user’s nickname

own_nickname = None¶: The clients nickname, as seen by the user

url = None¶: The profile url

class fbchat.models.VideoAttachment(size=None, width=None, height=None, duration=None, preview_url=None, small_image=None, medium_image=None, large_image=None, **kwargs)[source]¶

Represents a video that has been sent as a Facebook attachment

duration = None¶: Length of video in milliseconds

height = None¶: Height of original video

large_image_height = None¶: Height of the large preview image

large_image_url = None¶: URL to a large preview image of the video

large_image_width = None¶: Width of the large preview image

medium_image_height = None¶: Height of the medium preview image

medium_image_url = None¶: URL to a medium preview image of the video

medium_image_width = None¶: Width of the medium preview image

preview_url = None¶: URL to very compressed preview video

size = None¶: Size of the original video in bytes

small_image_height = None¶: Height of the small preview image

small_image_url = None¶: URL to a small preview image of the video

small_image_width = None¶: Width of the small preview image

width = None¶: Width of original video

Utils¶

These functions and values are used internally by fbchat, and are subject to change. Do NOT rely on these to be backwards compatible!

class fbchat.utils.ReqUrl[source]¶: A class containing all urls used by fbchat

fbchat.utils.USER_AGENTS = ['Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.90 Safari/537.36', 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/601.1.10 (KHTML, like Gecko) Version/8.0.5 Safari/601.1.10', 'Mozilla/5.0 (Windows NT 6.3; WOW64; ; NCT50_AAP285C84A1328) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.90 Safari/537.36', 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.1 (KHTML, like Gecko) Chrome/22.0.1207.1 Safari/537.1', 'Mozilla/5.0 (X11; CrOS i686 2268.111.0) AppleWebKit/536.11 (KHTML, like Gecko) Chrome/20.0.1132.57 Safari/536.11', 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/536.6 (KHTML, like Gecko) Chrome/20.0.1092.0 Safari/536.6']¶: Default list of user agents

fbchat.utils.random() → x in the interval [0, 1).¶

Todo¶

This page will be periodically updated to show missing features and documentation

Missing Functionality¶

Implement Client.searchForMessage
- This will use the graphql request API
Implement chatting with pages properly
Write better FAQ
Explain usage of graphql

Documentation¶

Todo

Documenting this

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/fbchat/checkouts/v1.4.2/fbchat/client.py:docstring of fbchat.Client.friendConnect, line 1.)

Todo

Documenting this

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/fbchat/checkouts/v1.4.2/fbchat/client.py:docstring of fbchat.Client.markAsSeen, line 1.)

Todo

Make this work with private calls

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/fbchat/checkouts/v1.4.2/fbchat/client.py:docstring of fbchat.Client.onCallEnded, line 1.)

Todo

Make this work with private calls

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/fbchat/checkouts/v1.4.2/fbchat/client.py:docstring of fbchat.Client.onCallStarted, line 1.)

Todo

Documenting this

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/fbchat/checkouts/v1.4.2/fbchat/client.py:docstring of fbchat.Client.onInbox, line 1.)

FAQ¶

Version X broke my installation¶

We try to provide backwards compatibility where possible, but since we’re not part of Facebook, most of the things may be broken at any point in time

Downgrade to an earlier version of fbchat, run this command

$ pip install fbchat==<X>

Where you replace <X> with the version you want to use

Will you be supporting creating posts/events/pages and so on?¶

We won’t be focusing on anything else than chat-related things. This API is called fbCHAT, after all ;)

Submitting Issues¶

If you’re having trouble with some of the snippets, or you think some of the functionality is broken, please feel free to submit an issue on Github. You should first login with logging_level set to logging.DEBUG:

from fbchat import Client
import logging
client = Client('<email>', '<password>', logging_level=logging.DEBUG)

Then you can submit the relevant parts of this log, and detailed steps on how to reproduce

Warning

Always remove your credentials from any debug information you may provide us. Preferably, use a test account, in case you miss anything