Full API

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

Client

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

A client for the Facebook Chat (Messenger).

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 on methods, to provide custom event handling (mainly useful while listening).

Initialize and log 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

  • 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 logging.INFO

Raises

FBchatException – On failed login

listening = False

Whether the client is listening.

Used when creating an external event loop to determine when to stop listening.

property ssl_verify

Verify SSL certificate.

Set to False to allow debugging with a proxy.

property uid

The ID of the client.

Can be used as thread_id. See Threads for more info.

graphql_requests(*queries)[source]

Execute GraphQL queries.

Parameters

queries (dict) – Zero or more dictionaries

Returns

A tuple containing JSON GraphQL queries

Return type

tuple

Raises

FBchatException – If request failed

graphql_request(query)[source]

Shorthand for graphql_requests(query)[0].

Raises

FBchatException – If request failed

isLoggedIn()[source]

Send a request to Facebook to check the login status.

Returns

True if the client is still logged in

Return type

bool

getSession()[source]

Retrieve session cookies.

Returns

A dictionary containing session cookies

Return type

dict

setSession(session_cookies, user_agent=None)[source]

Load session cookies.

Parameters

session_cookies (dict) – A dictionary containing session cookies

Returns

False if session_cookies does not contain proper cookies

Return type

bool

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

Login the user, using email and password.

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 log out the client.

Returns

True if the action was successful

Return type

bool

setDefaultThread(thread_id, thread_type)[source]

Set default thread to send messages to.

Parameters
resetDefaultThread()[source]

Reset default thread.

fetchThreads(thread_location, before=None, after=None, limit=None)[source]

Fetch all threads in thread_location.

Threads will be sorted from newest to oldest.

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

  • before – Fetch only thread before this epoch (in ms) (default all threads)

  • after – Fetch only thread after this epoch (in ms) (default all threads)

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

Returns

Thread objects

Return type

list

Raises

FBchatException – If request failed

fetchAllUsersFromThreads(threads)[source]

Fetch all users involved in given threads.

Parameters

threads – Thread: List of threads to check for users

Returns

User objects

Return type

list

Raises

FBchatException – If request failed

fetchAllUsers()[source]

Fetch all users the client is currently chatting with.

Returns

User objects

Return type

list

Raises

FBchatException – If request failed

searchForUsers(name, limit=10)[source]

Find and get users by their name.

Parameters
  • name – Name of the user

  • limit – The max. amount of users to fetch

Returns

User objects, ordered by relevance

Return type

list

Raises

FBchatException – If request failed

searchForPages(name, limit=10)[source]

Find and get pages by their name.

Parameters

name – Name of the page

Returns

Page objects, ordered by relevance

Return type

list

Raises

FBchatException – If request failed

searchForGroups(name, limit=10)[source]

Find and get group threads by their name.

Parameters
  • name – Name of the group thread

  • limit – The max. amount of groups to fetch

Returns

Group objects, ordered by relevance

Return type

list

Raises

FBchatException – If request failed

searchForThreads(name, limit=10)[source]

Find and get threads by their name.

Parameters
  • name – Name of the thread

  • limit – The max. amount of groups to fetch

Returns

User, Group and Page 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

typing.Iterable

Raises

FBchatException – If request failed

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

Find and get 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 Message objects

Return type

typing.Iterable

Raises

FBchatException – If request failed

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

Search for messages in all threads.

Parameters
  • query – Text to search for

  • fetch_messages – Whether to fetch 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 iterables to get messages as values

Return type

typing.Dict[str, typing.Iterable]

Raises

FBchatException – If request failed

fetchUserInfo(*user_ids)[source]

Fetch 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

User objects, labeled by their ID

Return type

dict

Raises

FBchatException – If request failed

fetchPageInfo(*page_ids)[source]

Fetch 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

Page objects, labeled by their ID

Return type

dict

Raises

FBchatException – If request failed

fetchGroupInfo(*group_ids)[source]

Fetch groups’ info from IDs, unordered.

Parameters

group_ids – One or more group ID(s) to query

Returns

Group objects, labeled by their ID

Return type

dict

Raises

FBchatException – If request failed

fetchThreadInfo(*thread_ids)[source]

Fetch 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

Thread objects, labeled by their ID

Return type

dict

Raises

FBchatException – If request failed

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

Fetch messages in a thread, ordered by most recent.

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

Message objects

Return type

list

Raises

FBchatException – If request failed

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

Fetch the client’s thread list.

Parameters
  • offset – Deprecated. Do not use!

  • limit (int) – Max. number of threads to retrieve. Capped at 20

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

  • before (int) – A timestamp (in milliseconds), indicating from which point to retrieve threads

Returns

Thread objects

Return type

list

Raises

FBchatException – If request failed

fetchUnread()[source]

Fetch unread threads.

Returns

List of unread thread ids

Return type

list

Raises

FBchatException – If request failed

fetchUnseen()[source]

Fetch unseen / new threads.

Returns

List of unseen thread ids

Return type

list

Raises

FBchatException – If request failed

fetchImageUrl(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

Returns

An URL where you can download the original image

Return type

str

Raises

FBchatException – If request failed

fetchMessageInfo(mid, thread_id=None)[source]

Fetch Message object from the given message id.

Parameters
  • mid – Message ID to fetch from

  • thread_id – User/Group ID to get message info from. See Threads

Returns

Message object

Return type

Message

Raises

FBchatException – If request failed

fetchPollOptions(poll_id)[source]

Fetch list of PollOption objects from the poll id.

Parameters

poll_id – Poll ID to fetch from

Returns

list

Raises

FBchatException – If request failed

fetchPlanInfo(plan_id)[source]

Fetch Plan object from the plan id.

Parameters

plan_id – Plan ID to fetch from

Returns

Plan object

Return type

Plan

Raises

FBchatException – If request failed

getPhoneNumbers()[source]

Fetch list of user’s phone numbers.

Returns

List of phone numbers

Return type

list

getEmails()[source]

Fetch list of user’s emails.

Returns

List of emails

Return type

list

getUserActiveStatus(user_id)[source]

Fetch friend active status as an ActiveStatus object.

Return None if status isn’t known.

Warning

Only works when listening.

Parameters

user_id – ID of the user

Returns

Given user active status

Return type

ActiveStatus

fetchThreadImages(thread_id=None)[source]

Fetch images posted in thread.

Parameters

thread_id – ID of the thread

Returns

ImageAttachment or VideoAttachment

Return type

typing.Iterable

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

Send message to a thread.

Parameters
Returns

Message ID of the sent message

Raises

FBchatException – If request failed

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

Deprecated. Use fbchat.Client.send instead.

sendEmoji(emoji=None, size=EmojiSize.SMALL, thread_id=None, thread_type=ThreadType.USER)[source]

Deprecated. Use fbchat.Client.send instead.

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

Wave hello 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 (ThreadType) – See Threads

Returns

Message ID of the sent message

Raises

FBchatException – If request failed

quickReply(quick_reply, payload=None, thread_id=None, thread_type=None)[source]

Reply to chosen quick reply.

Parameters
  • quick_reply (QuickReply) – Quick reply to reply to

  • payload – Optional answer to the quick reply

  • thread_id – User/Group ID to send to. See Threads

  • thread_type (ThreadType) – See Threads

Returns

Message ID of the sent message

Raises

FBchatException – If request failed

unsend(mid)[source]

Unsend message by it’s ID (removes it for everyone).

Parameters

midMessage ID of the message to unsend

sendLocation(location, message=None, thread_id=None, thread_type=None)[source]

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

Parameters
Returns

Message ID of the sent message

Raises

FBchatException – If request failed

sendPinnedLocation(location, message=None, thread_id=None, thread_type=None)[source]

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

Parameters
Returns

Message ID of the sent message

Raises

FBchatException – If request failed

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

Send 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 (ThreadType) – See Threads

Returns

Message ID of the sent files

Raises

FBchatException – If request failed

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

Send local files to a thread.

Parameters
  • file_paths – Paths of files to upload and send

  • message – Additional message

  • thread_id – User/Group ID to send to. See Threads

  • thread_type (ThreadType) – See Threads

Returns

Message ID of the sent files

Raises

FBchatException – If request failed

sendRemoteVoiceClips(clip_urls, message=None, thread_id=None, thread_type=ThreadType.USER)[source]

Send voice clips from URLs to a thread.

Parameters
  • clip_urls – URLs of clips to upload and send

  • message – Additional message

  • thread_id – User/Group ID to send to. See Threads

  • thread_type (ThreadType) – See Threads

Returns

Message ID of the sent files

Raises

FBchatException – If request failed

sendLocalVoiceClips(clip_paths, message=None, thread_id=None, thread_type=ThreadType.USER)[source]

Send local voice clips to a thread.

Parameters
  • clip_paths – Paths of clips to upload and send

  • message – Additional message

  • thread_id – User/Group ID to send to. See Threads

  • thread_type (ThreadType) – See Threads

Returns

Message ID of the sent files

Raises

FBchatException – If request failed

sendImage(image_id, message=None, thread_id=None, thread_type=ThreadType.USER, is_gif=False)[source]

Deprecated.

sendRemoteImage(image_url, message=None, thread_id=None, thread_type=ThreadType.USER)[source]

Deprecated. Use fbchat.Client.sendRemoteFiles instead.

sendLocalImage(image_path, message=None, thread_id=None, thread_type=ThreadType.USER)[source]

Deprecated. Use fbchat.Client.sendLocalFiles instead.

forwardAttachment(attachment_id, thread_id=None)[source]

Forward an attachment.

Parameters
  • attachment_id – Attachment ID to forward

  • thread_id – User/Group ID to send to. See Threads

Raises

FBchatException – If request failed

createGroup(message, user_ids)[source]

Create a group with the given user 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

addUsersToGroup(user_ids, thread_id=None)[source]

Add 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

removeUserFromGroup(user_id, thread_id=None)[source]

Remove user 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

addGroupAdmins(admin_ids, thread_id=None)[source]

Set specified 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

removeGroupAdmins(admin_ids, thread_id=None)[source]

Remove admin status from specified 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

changeGroupApprovalMode(require_admin_approval, thread_id=None)[source]

Change 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

acceptUsersToGroup(user_ids, thread_id=None)[source]

Accept 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

denyUsersFromGroup(user_ids, thread_id=None)[source]

Deny users from joining the group.

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

changeGroupImageRemote(image_url, thread_id=None)[source]

Change 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

changeGroupImageLocal(image_path, thread_id=None)[source]

Change 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

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

Change 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 (ThreadType) – See Threads

Raises

FBchatException – If request failed

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

Change 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 (ThreadType) – See Threads

Raises

FBchatException – If request failed

changeThreadColor(color, thread_id=None)[source]

Change thread color.

Parameters
  • color (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]

Change thread color.

Note

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

reactToMessage(message_id, reaction)[source]

React to a message, or removes reaction.

Parameters
Raises

FBchatException – If request failed

createPlan(plan, thread_id=None)[source]

Set a plan.

Parameters
  • plan (Plan) – Plan to set

  • thread_id – User/Group ID to send plan to. See Threads

Raises

FBchatException – If request failed

editPlan(plan, new_plan)[source]

Edit a plan.

Parameters
  • plan (Plan) – Plan to edit

  • new_plan – New plan

Raises

FBchatException – If request failed

deletePlan(plan)[source]

Delete a plan.

Parameters

plan – Plan to delete

Raises

FBchatException – If request failed

changePlanParticipation(plan, take_part=True)[source]

Change 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

eventReminder(thread_id, time, title, location='', location_id='')[source]

Deprecated. Use fbchat.Client.createPlan instead.

createPoll(poll, thread_id=None)[source]

Create poll in a group thread.

Parameters
  • poll (Poll) – Poll to create

  • thread_id – User/Group ID to create poll in. See Threads

Raises

FBchatException – If request failed

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

Update 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 (ThreadType) – See Threads

Raises

FBchatException – If request failed

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

Set users typing status in a thread.

Parameters
Raises

FBchatException – If request failed

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

True

Raises

FBchatException – If request failed

markAsRead(thread_ids=None)[source]

Mark threads as read.

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

Parameters

thread_ids – User/Group IDs to set as read. See Threads

Raises

FBchatException – If request failed

markAsUnread(thread_ids=None)[source]

Mark threads as unread.

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

Parameters

thread_ids – User/Group IDs to set as unread. See Threads

Raises

FBchatException – If request failed

markAsSeen()[source]

Todo

Documenting this

friendConnect(friend_id)[source]

Todo

Documenting this

removeFriend(friend_id=None)[source]

Remove a specified friend from the client’s friend list.

Parameters

friend_id – The ID of the friend that you want to remove

Returns

True

Raises

FBchatException – If request failed

blockUser(user_id)[source]

Block messages from a specified user.

Parameters

user_id – The ID of the user that you want to block

Returns

True

Raises

FBchatException – If request failed

unblockUser(user_id)[source]

Unblock a previously 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

moveThreads(location, thread_ids)[source]

Move threads to specified location.

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

  • thread_ids – Thread IDs to move. See Threads

Returns

True

Raises

FBchatException – If request failed

deleteThreads(thread_ids)[source]

Delete threads.

Parameters

thread_ids – Thread IDs to delete. See Threads

Returns

True

Raises

FBchatException – If request failed

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

True

Raises

FBchatException – If request failed

deleteMessages(message_ids)[source]

Delete specified messages.

Parameters

message_ids – Message IDs to delete

Returns

True

Raises

FBchatException – If request failed

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

Mute thread.

Parameters
  • mute_time – Mute time in seconds, leave blank to mute forever

  • thread_id – User/Group ID to mute. See Threads

unmuteThread(thread_id=None)[source]

Unmute thread.

Parameters

thread_id – User/Group ID to unmute. See Threads

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

Mute thread reactions.

Parameters
  • mute – Boolean. True to mute, False to unmute

  • thread_id – User/Group ID to mute. See Threads

unmuteThreadReactions(thread_id=None)[source]

Unmute thread reactions.

Parameters

thread_id – User/Group ID to unmute. See Threads

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

Mute thread mentions.

Parameters
  • mute – Boolean. True to mute, False to unmute

  • thread_id – User/Group ID to mute. See Threads

unmuteThreadMentions(thread_id=None)[source]

Unmute thread mentions.

Parameters

thread_id – User/Group ID to unmute. See Threads

startListening()[source]

Start listening from an external event loop.

Raises

FBchatException – If request failed

doOneListen(markAlive=None)[source]

Do one cycle of the listening loop.

This method is useful if you want to control the client from an external event loop.

Warning

markAlive parameter is deprecated, use Client.setActiveStatus or markAlive parameter in Client.listen instead.

Returns

Whether the loop should keep running

Return type

bool

stopListening()[source]

Clean up the variables from Client.startListening.

listen(markAlive=None)[source]

Initialize and runs the listening loop continually.

Parameters

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

setActiveStatus(markAlive)[source]

Change active status while listening.

Parameters

markAlive (bool) – Whether to show if client is active

onLoggingIn(email=None)[source]

Called when the client is logging in.

Parameters

email – The email of the client

on2FACode()[source]

Called when a 2FA code is needed to progress.

onLoggedIn(email=None)[source]

Called when the client is successfully logged in.

Parameters

email – The email of the client

onListening()[source]

Called when the client is listening.

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

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 (Message) – The message (As a Message object)

  • thread_id – Thread ID that the message was sent to. See Threads

  • thread_type (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 received

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 (ThreadColor) – The new color

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (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 received

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 (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 received

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 a thread’s title.

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 (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 received

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

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

Parameters
  • mid – The action ID

  • author_id – The ID of the person who changed the image

  • new_image – The ID of the new image

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (ThreadType) – Type of thread that the action was sent to. See Threads

  • ts – A timestamp of the action

  • msg – A full set of the data received

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 a nickname.

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 (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 received

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.

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 received

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 is removed as an admin in a group.

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 received

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.

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 received

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 (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 received

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 (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 received

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 received

onMessageUnsent(mid=None, author_id=None, thread_id=None, thread_type=None, ts=None, msg=None)[source]

Called when the client is listening, and someone unsends (deletes for everyone) a message.

Parameters
  • mid – ID of the unsent message

  • author_id – The ID of the person who unsent the message

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (ThreadType) – Type of thread that the action was sent to. See Threads

  • ts – A timestamp of the action

  • msg – A full set of the data received

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 received

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 received

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 received

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 received

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 (TypingStatus) – The typing status

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (ThreadType) – Type of thread that the action was sent to. See Threads

  • msg – A full set of the data received

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 leader board of the game in the thread

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (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 received

onReactionAdded(mid=None, reaction=None, author_id=None, thread_id=None, thread_type=None, ts=None, msg=None)[source]

Called when the client is listening, and somebody reacts to a message.

Parameters
  • mid – Message ID, that user reacted to

  • reaction (MessageReaction) – Reaction

  • add_reaction – Whether user added or removed reaction

  • author_id – The ID of the person who reacted to the message

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (ThreadType) – Type of thread that the action was sent to. See Threads

  • ts – A timestamp of the action

  • msg – A full set of the data received

onReactionRemoved(mid=None, author_id=None, thread_id=None, thread_type=None, ts=None, msg=None)[source]

Called when the client is listening, and somebody removes reaction from a message.

Parameters
  • mid – Message ID, that user reacted to

  • author_id – The ID of the person who removed reaction

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (ThreadType) – Type of thread that the action was sent to. See Threads

  • ts – A timestamp of the action

  • msg – A full set of the data received

onBlock(author_id=None, thread_id=None, thread_type=None, ts=None, msg=None)[source]

Called when the client is listening, and somebody blocks client.

Parameters
  • author_id – The ID of the person who blocked

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (ThreadType) – Type of thread that the action was sent to. See Threads

  • ts – A timestamp of the action

  • msg – A full set of the data received

onUnblock(author_id=None, thread_id=None, thread_type=None, ts=None, msg=None)[source]

Called when the client is listening, and somebody blocks client.

Parameters
  • author_id – The ID of the person who unblocked

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (ThreadType) – Type of thread that the action was sent to. See Threads

  • ts – A timestamp of the action

  • msg – A full set of the data received

onLiveLocation(mid=None, location=None, author_id=None, thread_id=None, thread_type=None, ts=None, msg=None)[source]

Called when the client is listening and somebody sends live location info.

Parameters
  • mid – The action ID

  • location (LiveLocationAttachment) – Sent location info

  • author_id – The ID of the person who sent location info

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (ThreadType) – Type of thread that the action was sent to. See Threads

  • ts – A timestamp of the action

  • msg – A full set of the data received

onCallStarted(mid=None, caller_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 starts a call in a group.

Todo

Make this work with private calls.

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 (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 received

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]

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

Todo

Make this work with private calls.

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 (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 received

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 (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 received

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 (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 (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 received

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 (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 (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 received

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 (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 (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 received

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 (Plan) – Ended plan

  • thread_id – Thread ID that the action was sent to. See Threads

  • thread_type (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 received

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 (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 (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 received

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 (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 (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 received

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 (Plan) – Plan

  • take_part (bool) – 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 (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 received

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 received

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

Called when the client receives chat online presence update.

Parameters
  • buddylist – A list of dictionaries with friend id and last seen timestamp

  • msg – A full set of the data received

onBuddylistOverlay(statuses=None, msg=None)[source]

Called when the client is listening and client receives information about friend active status.

Parameters
  • statuses (dict) – Dictionary with user IDs as keys and ActiveStatus as values

  • msg – A full set of the data received

onUnknownMesssageType(msg=None)[source]

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

Parameters

msg – A full set of the data received

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

Called when an error was encountered while parsing received data.

Parameters
  • exception – The exception that was encountered

  • msg – A full set of the data received

Threads

class fbchat.Thread[source]

Represents a Facebook thread.

uid = None

The unique identifier of the thread. Can be used a thread_id. See Threads for more info

type = None

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

photo = None

A URL to the thread’s picture

name = None

The name of the thread

last_message_timestamp = None

Timestamp of last message

message_count = None

Number of messages in the thread

plan = None

Set Plan

class fbchat.ThreadType(Enum)[source]

Used to specify what type of Facebook thread is being used.

See Threads for more info.

USER = 1
GROUP = 2
ROOM = 2
PAGE = 3
class fbchat.Page[source]

Represents a Facebook page. Inherits Thread.

url = None

The page’s custom URL

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

category = None

The page’s category

class fbchat.User[source]

Represents a Facebook user. Inherits Thread.

url = None

The profile URL

first_name = None

The users first name

last_name = None

The users last name

is_friend = None

Whether the user and the client are friends

gender = None

The user’s gender

affinity = None

From 0 to 1. How close the client is to the user

nickname = None

The user’s nickname

own_nickname = None

The clients nickname, as seen by the user

color = None

A ThreadColor. The message color

emoji = None

The default emoji

class fbchat.Group[source]

Represents a Facebook group. Inherits Thread.

participants = None

Unique list (set) of the group thread’s participant user IDs

nicknames = None

A dictionary, containing user nicknames mapped to their IDs

color = None

A ThreadColor. The groups’s message color

emoji = None

The groups’s default emoji

Messages

class fbchat.Message(text=None, mentions=NOTHING, emoji_size=None, sticker=None, attachments=NOTHING, quick_replies=NOTHING, reply_to_id=None)[source]

Represents a Facebook message.

text = None

The actual message

mentions = None

A list of Mention objects

emoji_size = None

A EmojiSize. Size of a sent emoji

uid = None

The message ID

author = None

ID of the sender

timestamp = None

Timestamp of when the message was sent

is_read = None

Whether the message is read

read_by = None

A list of people IDs who read the message, works only with fbchat.Client.fetchThreadMessages

reactions = None

A dictionary with user’s IDs as keys, and their MessageReaction as values

sticker = None

A Sticker

attachments = None

A list of attachments

quick_replies = None

A list of QuickReply

unsent = None

Whether the message is unsent (deleted for everyone)

reply_to_id = None

Message ID you want to reply to

replied_to = None

Replied message

forwarded = None

Whether the message was forwarded

classmethod formatMentions(text, *args, **kwargs)[source]

Like str.format, but takes tuples with a thread id and text instead.

Return a Message object, with the formatted string and relevant mentions.

>>> Message.formatMentions("Hey {!r}! My name is {}", ("1234", "Peter"), ("4321", "Michael"))
<Message (None): "Hey 'Peter'! My name is Michael", mentions=[<Mention 1234: offset=4 length=7>, <Mention 4321: offset=24 length=7>] emoji_size=None attachments=[]>
>>> Message.formatMentions("Hey {p}! My name is {}", ("1234", "Michael"), p=("4321", "Peter"))
<Message (None): 'Hey Peter! My name is Michael', mentions=[<Mention 4321: offset=4 length=5>, <Mention 1234: offset=22 length=7>] emoji_size=None attachments=[]>
class fbchat.Mention(thread_id, offset=0, length=10)[source]

Represents a @mention.

thread_id = None

The thread ID the mention is pointing at

offset = None

The character where the mention starts

length = None

The length of the mention

class fbchat.EmojiSize(Enum)[source]

Used to specify the size of a sent emoji.

LARGE = '369239383222810'
MEDIUM = '369239343222814'
SMALL = '369239263222822'
class fbchat.MessageReaction(Enum)[source]

Used to specify a message reaction.

HEART = '❤'
LOVE = '😍'
SMILE = '😆'
WOW = '😮'
SAD = '😢'
ANGRY = '😠'
YES = '👍'
NO = '👎'

Exceptions

exception fbchat.FBchatException[source]

Custom exception thrown by fbchat.

All exceptions in the fbchat module inherits this.

exception fbchat.FBchatFacebookError[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 (e.g. 404) (Usually only set if not successful, aka. not 200)

exception fbchat.FBchatUserError[source]

Thrown by fbchat when wrong values are entered.

Attachments

class fbchat.Attachment[source]

Represents a Facebook attachment.

uid = None

The attachment ID

class fbchat.ShareAttachment[source]

Represents a shared item (e.g. URL) attachment.

author = None

ID of the author of the shared post

url = None

Target URL

original_url = None

Original URL if Facebook redirects the URL

title = None

Title of the attachment

description = None

Description of the attachment

source = None

Name of the source

image_url = None

URL of the attachment image

original_image_url = None

URL of the original image if Facebook uses safe_image

image_width = None

Width of the image

image_height = None

Height of the image

attachments = None

List of additional attachments

class fbchat.Sticker[source]

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

pack = None

The sticker-pack’s ID

is_animated = None

Whether the sticker is animated

medium_sprite_image = None

URL to a medium spritemap

large_sprite_image = None

URL to a large spritemap

frames_per_row = None

The amount of frames present in the spritemap pr. row

frames_per_col = None

The amount of frames present in the spritemap pr. column

frame_rate = None

The frame rate the spritemap is intended to be played in

url = None

URL to the sticker’s image

width = None

Width of the sticker

height = None

Height of the sticker

label = None

The sticker’s label/name

class fbchat.LocationAttachment[source]

Represents a user location.

Latitude and longitude OR address is provided by Facebook.

latitude = None

Latitude of the location

longitude = None

Longitude of the location

image_url = None

URL of image showing the map of the location

image_width = None

Width of the image

image_height = None

Height of the image

url = None

URL to Bing maps with the location

class fbchat.LiveLocationAttachment[source]

Represents a live user location.

name = None

Name of the location

expiration_time = None

Timestamp when live location expires

is_expired = None

True if live location is expired

class fbchat.FileAttachment[source]

Represents a file that has been sent as a Facebook attachment.

url = None

URL where you can download the file

size = None

Size of the file in bytes

name = None

Name of the file

is_malicious = None

Whether Facebook determines that this file may be harmful

class fbchat.AudioAttachment[source]

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

filename = None

Name of the file

url = None

URL of the audio file

duration = None

Duration of the audio clip in milliseconds

audio_type = None

Audio type

class fbchat.ImageAttachment[source]

Represents an image that has been sent as a Facebook attachment.

To retrieve the full image URL, use: Client.fetchImageUrl, and pass it the id of the image attachment.

original_extension = None

The extension of the original image (e.g. png)

width = None

Width of original image

height = None

Height of original image

is_animated = None

Whether the image is animated

thumbnail_url = None

URL to a thumbnail of the image

preview_url = None

URL to a medium preview of the image

preview_width = None

Width of the medium preview image

preview_height = None

Height of the medium preview image

large_preview_url = None

URL to a large preview of the image

large_preview_width = None

Width of the large preview image

large_preview_height = None

Height of the large preview image

animated_preview_url = None

URL to an animated preview of the image (e.g. for GIFs)

animated_preview_width = None

Width of the animated preview image

animated_preview_height = None

Height of the animated preview image

class fbchat.VideoAttachment[source]

Represents a video that has been sent as a Facebook attachment.

size = None

Size of the original video in bytes

width = None

Width of original video

height = None

Height of original video

duration = None

Length of video in milliseconds

preview_url = None

URL to very compressed preview video

small_image_url = None

URL to a small preview image of the video

small_image_width = None

Width of the small preview image

small_image_height = None

Height of the small 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

medium_image_height = None

Height of the medium 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

large_image_height = None

Height of the large preview image

class fbchat.ImageAttachment[source]

Represents an image that has been sent as a Facebook attachment.

To retrieve the full image URL, use: Client.fetchImageUrl, and pass it the id of the image attachment.

original_extension = None

The extension of the original image (e.g. png)

width = None

Width of original image

height = None

Height of original image

is_animated = None

Whether the image is animated

thumbnail_url = None

URL to a thumbnail of the image

preview_url = None

URL to a medium preview of the image

preview_width = None

Width of the medium preview image

preview_height = None

Height of the medium preview image

large_preview_url = None

URL to a large preview of the image

large_preview_width = None

Width of the large preview image

large_preview_height = None

Height of the large preview image

animated_preview_url = None

URL to an animated preview of the image (e.g. for GIFs)

animated_preview_width = None

Width of the animated preview image

animated_preview_height = None

Height of the animated preview image

Miscellaneous

class fbchat.ThreadLocation(Enum)[source]

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

INBOX = 'INBOX'
PENDING = 'PENDING'
ARCHIVED = 'ARCHIVED'
OTHER = 'OTHER'
class fbchat.ThreadColor(Enum)[source]

Used to specify a thread colors.

MESSENGER_BLUE = '#0084ff'
VIKING = '#44bec7'
GOLDEN_POPPY = '#ffc300'
RADICAL_RED = '#fa3c4c'
SHOCKING = '#d696bb'
PICTON_BLUE = '#6699cc'
FREE_SPEECH_GREEN = '#13cf13'
PUMPKIN = '#ff7e29'
LIGHT_CORAL = '#e68585'
MEDIUM_SLATE_BLUE = '#7646ff'
DEEP_SKY_BLUE = '#20cef5'
FERN = '#67b868'
CAMEO = '#d4a88c'
BRILLIANT_ROSE = '#ff5ca1'
BILOBA_FLOWER = '#a695c7'
TICKLE_ME_PINK = '#ff7ca8'
MALACHITE = '#1adb5b'
RUBY = '#f01d6a'
DARK_TANGERINE = '#ff9c19'
BRIGHT_TURQUOISE = '#0edcde'
class fbchat.ActiveStatus[source]
active = None

Whether the user is active now

last_active = None

Timestamp when the user was last active

in_game = None

Whether the user is playing Messenger game now

class fbchat.TypingStatus(Enum)[source]

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

STOPPED = 0
TYPING = 1
class fbchat.QuickReply(payload=None, data=None, is_response=False)[source]

Represents a quick reply.

payload = None

Payload of the quick reply

external_payload = None

External payload for responses

data = None

Additional data

is_response = None

Whether it’s a response for a quick reply

class fbchat.QuickReplyText(title=None, image_url=None, **kwargs)[source]

Represents a text quick reply.

title = None

Title of the quick reply

image_url = None

URL of the quick reply image (optional)

class fbchat.QuickReplyLocation(**kwargs)[source]

Represents a location quick reply (Doesn’t work on mobile).

class fbchat.QuickReplyPhoneNumber(image_url=None, **kwargs)[source]

Represents a phone number quick reply (Doesn’t work on mobile).

image_url = None

URL of the quick reply image (optional)

class fbchat.QuickReplyEmail(image_url=None, **kwargs)[source]

Represents an email quick reply (Doesn’t work on mobile).

image_url = None

URL of the quick reply image (optional)

class fbchat.Poll(title, options, options_count=None, uid=None)[source]

Represents a poll.

title = None

Title of the poll

options = None

List of PollOption, can be fetched with fbchat.Client.fetchPollOptions

options_count = None

Options count

uid = None

ID of the poll

class fbchat.PollOption(text, vote=False, voters=None, votes_count=None, uid=None)[source]

Represents a poll option.

text = None

Text 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

uid = None

ID of the poll option

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

Represents a plan.

uid = None

ID of the plan

time = None

Plan time (timestamp), only precise down to the minute

title = None

Plan title

location = None

Plan location name

location_id = None

Plan location ID

author_id = None

ID of the plan creator

guests = None

Dictionary of User IDs mapped to their GuestStatus

property going

List of the User IDs who will take part in the plan.

property declined

List of the User IDs who won’t take part in the plan.

property invited

List of the User IDs who are invited to the plan.

class fbchat.GuestStatus(Enum)[source]
INVITED = 1
GOING = 2
DECLINED = 3