Version up

[Feature] Quick replies

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Create a report if you're having trouble with `fbchat`
+
+---
+
+## Description of the problem
+Example: Logging in fails when the character `%` is in the password. A specific password that fails is `a_password_with_%`
+
+## Code to reproduce
+```py
+# Example code
+from fbchat import Client
+client = Client("[REDACTED_USERNAME]", "a_password_with_%")
+```
+
+## Traceback
+```
+Traceback (most recent call last):
+  File "<test.py>", line 1, in <module>
+  File "[site-packages]/fbchat/client.py", line 78, in __init__
+    self.login(email, password, max_tries)
+  File "[site-packages]/fbchat/client.py", line 407, in login
+    raise FBchatUserError('Login failed. Check email/password. (Failed on url: {})'.format(login_url))
+fbchat.models.FBchatUserError: Login failed. Check email/password. (Failed on url: https://m.facebook.com/login.php?login_attempt=1)
+```
+
+## Environment information
+- Python version
+- `fbchat` version
+- If relevant, output from `$ python -m pip list`
+
+If you have done any research, include that.
+Make sure to redact all personal information.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest a feature that you'd like to see implemented
+
+---
+
+## Description
+Example: There's no way to send messages to groups
+
+## Research (if applicable)
+Example: I've found the URL `https://facebook.com/send_message.php`, to which you can send a POST requests with the following JSON:
+```json
+{
+   "text": message_content,
+   "fbid": group_id,
+   "some_variable": ?
+}
+```
+But I don't know how what `some_variable` does, and it doesn't work without it. I've found some examples of `some_variable` to be: `MTIzNDU2Nzg5MA`, `MTIzNDU2Nzg5MQ` and `MTIzNDU2Nzg5Mg`

.gitignore

@@ -1,14 +1,18 @@
 *py[co]
 
+.idea/
+
 # Test scripts
 *.sh
 
 # Packages
 *.egg
 *.egg-info
+*.dist-info
 dist
 build
 eggs
+.eggs
 parts
 bin
 var
@@ -22,5 +26,12 @@ develop-eggs
 # Sphinx documentation
 docs/_build/
 
-# Data for tests
+# Scripts and data for tests
+my_tests.py
+my_test_data.json
+my_data.json
 tests.data
+.pytest_cache
+
+# Virtual environment
+venv/

.travis.yml

@@ -0,0 +1,55 @@
+sudo: false
+language: python
+python: 3.6
+
+cache: pip
+
+before_install: pip install flit
+install: flit install --deps production --extras test
+script: pytest -m offline
+
+jobs:
+  include:
+  - python: 2.7
+    before_install:
+    - sudo apt-get -y install python3-pip python3-setuptools
+    - sudo pip3 install flit
+    install: flit install --python python --deps production --extras test
+  - python: 3.4
+  - python: 3.5
+  - python: 3.6
+  - python: 3.7
+    dist: xenial
+    sudo: required
+  - python: pypy3.5
+
+  - name: Lint
+    before_install: skip
+    install: pip install black
+    script: black --check --verbose .
+
+  - stage: deploy
+    name: Github Releases
+    if: tag IS present
+    install: skip
+    script: flit build
+    deploy:
+      provider: releases
+      api_key: $GITHUB_OAUTH_TOKEN
+      file_glob: true
+      file: dist/*
+      skip_cleanup: true
+      draft: true
+      on:
+        tags: true
+
+  - stage: deploy
+    name: PyPI
+    if: tag IS present
+    install: skip
+    script: skip
+    deploy:
+      provider: script
+      script: flit publish
+      on:
+        tags: true

CODE_OF_CONDUCT

@@ -0,0 +1,75 @@
+Contributor Covenant Code of Conduct
+
+Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+
+Examples of unacceptable behavior by participants include:
+
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others’ private information, such as a physical or electronic
+address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+professional setting
+
+
+Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at carpedm20@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project’s leadership.
+
+Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

CONTRIBUTING.rst

@@ -0,0 +1,38 @@
+Contributing to fbchat
+======================
+
+Thanks for reading this, all contributions are very much welcome!
+
+Please be aware that ``fbchat`` uses `Scemantic Versioning <https://semver.org/>`__
+That means that if you're submitting a breaking change, it will probably take a while before it gets considered.
+
+In that case, you can point your PR to the ``2.0.0-dev`` branch, where the API is being properly developed.
+Otherwise, just point it to ``master``.
+
+Development Environment
+-----------------------
+
+You can use `flit` to install the package as a symlink:
+
+.. code-block::
+
+    $ # *nix:
+    $ flit install --symlink
+    $ # Windows:
+    $ flit install --pth-file
+
+After that, you can ``import`` the module as normal.
+
+Before committing, you should run ``black .`` in the main directory, to format your code.
+
+Testing Environment
+-------------------
+
+The tests use `pytest <https://docs.pytest.org/>`__, and to work they need two Facebook accounts, and a group thread between these.
+To set these up, you should export the following environment variables:
+
+``client1_email``, ``client1_password``, ``client2_email``, ``client2_password`` and ``group_id``
+
+If you're not able to do this, consider simply running ``pytest -m offline``.
+
+And if you're adding new functionality, if possible, make sure to create a new test for it.

LICENSE

@@ -1,4 +1,4 @@
-New BSD License
+BSD 3-Clause License
 
 Copyright (c) 2015, Taehoon Kim
 All rights reserved.
@@ -13,8 +13,9 @@ modification, are permitted provided that the following conditions are met:
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.
 
-* The names of its contributors may not be used to endorse or promote products
-  derived from this software without specific prior written permission.
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

MANIFEST.in

@@ -1,4 +0,0 @@
-include LICENSE.txt
-include MANIFEST.in
-include README.rst
-include setup.py

README.rst

@@ -1,119 +1,52 @@
-======
-fbchat
-======
+fbchat: Facebook Chat (Messenger) for Python
+============================================
 
+.. image:: https://img.shields.io/badge/license-BSD-blue.svg
+    :target: https://github.com/carpedm20/fbchat/tree/master/LICENSE
+    :alt: License: BSD 3-Clause
 
-Facebook Chat (`Messenger <https://www.messenger.com/>`__) for Python. This project was inspired by `facebook-chat-api <https://github.com/Schmavery/facebook-chat-api>`__.
+.. image:: https://img.shields.io/badge/python-2.7%2C%203.4%2C%203.5%2C%203.6%203.7%20pypy-blue.svg
+    :target: https://pypi.python.org/pypi/fbchat
+    :alt: Supported python versions: 2.7, 3.4, 3.5, 3.6, 3.7 and pypy
 
-**No XMPP or API key is needed**. Just use your ID and PASSWORD.
+.. image:: https://readthedocs.org/projects/fbchat/badge/?version=master
+    :target: https://fbchat.readthedocs.io
+    :alt: Documentation
 
+.. image:: https://travis-ci.org/carpedm20/fbchat.svg?branch=master
+    :target: https://travis-ci.org/carpedm20/fbchat
+    :alt: Travis CI
 
-Installation
-============
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/ambv/black
+    :alt: Code style
 
-Simple:
+Facebook Chat (`Messenger <https://www.facebook.com/messages/>`__) for Python.
+This project was inspired by `facebook-chat-api <https://github.com/Schmavery/facebook-chat-api>`__.
 
-.. code-block:: console
+**No XMPP or API key is needed**. Just use your email and password.
+
+Go to `Read the Docs <https://fbchat.readthedocs.io>`__ to see the full documentation,
+or jump right into the code by viewing the `examples <https://github.com/carpedm20/fbchat/tree/master/examples>`__
+
+Installation:
+
+.. code-block::
 
     $ pip install fbchat
 
+You can also install from source, by using `flit`:
 
-Example
-=======
+.. code-block::
 
-.. code-block:: python
-
-    import fbchat
-
-    client = fbchat.Client("YOUR_ID", "YOUR_PASSWORD")
+    $ pip install flit
+    $ git clone https://github.com/carpedm20/fbchat.git
+    $ cd fbchat
+    $ flit install
 
 
-Sending a Message
-=================
+Maintainer
+----------
 
-.. code-block:: python
-    
-    friends = client.getUsers("FRIEND'S NAME")  # return a list of names
-    friend = friends[0]
-    sent = client.send(friend.uid, "Your Message")
-    if sent:
-        print("Message sent successfully!")
-    # IMAGES
-    client.sendLocalImage(friend.uid,message='<message text>',image='<path/to/image/file>') # send local image
-    imgurl = "http://i.imgur.com/LDQ2ITV.jpg"
-    client.sendRemoteImage(friend.uid,message='<message text>', image=imgurl) # send image from image url
-
-
-Getting user info from user id
-==============================
-
-.. code-block:: python
-
-    friend1 = client.getUsers('<friend name 1>')[0]
-    friend2 = client.getUsers('<friend name 2>')[0]
-    friend1_info = client.getUserInfo(friend1.uid) # returns dict with details
-    both_info = client.getUserInfo(friend1.uid,friend2.uid) # query both together, returns list of dicts
-    friend1_name = friend1_info['name'] 
-
-
-Getting last messages sent
-==========================
-
-.. code-block:: python
-    
-    last_messages = client.getThreadInfo(friend.uid, last_n=20)
-    last_messages.reverse()  # messages come in reversed order
-    
-    for message in last_messages:
-        print(message.body)
-
-
-Example Echobot
-===============
-
-.. code-block:: python
-
-    import fbchat
-    #subclass fbchat.Client and override required methods
-    class EchoBot(fbchat.Client): 
-
-        def __init__(self,email, password, debug=True, user_agent=None):            
-            fbchat.Client.__init__(self,email, password, debug, user_agent)
-
-        def on_message(self, mid, author_id, author_name, message, metadata):
-            self.markAsDelivered(author_id, mid) #mark delivered
-            self.markAsRead(author_id) #mark read
-
-            print("%s said: %s"%(author_id, message))
-
-            #if you are not the author, echo
-            if str(author_id) != str(self.uid):
-                self.send(author_id,message)
-    
-    bot = EchoBot("<email>", "<password>")
-    bot.listen()
-
-
-Saving session
-==========================
-
-.. code-block:: python
-    
-    session_cookies = client.setSession()
-    # save session_cookies
-
-
-Loading session
-==========================
-
-.. code-block:: python
-    
-    client = fbchat.Client(None, None, session_cookies=session_cookies)
-    # OR
-    client.setSession(session_cookies)
-
-
-Authors
-=======
-
-Taehoon Kim / `@carpedm20 <http://carpedm20.github.io/about/>`__
+- Mads Marquart / `@madsmtm <https://github.com/madsmtm>`__
+- Taehoon Kim / `@carpedm20 <http://carpedm20.github.io/about/>`__

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python3.6 -msphinx
+SPHINXPROJ    = fbchat
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/license.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="80" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="80" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h47v20H0z"/><path fill="#007ec6" d="M47 0h33v20H47z"/><path fill="url(#b)" d="M0 0h80v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11"><text x="23.5" y="15" fill="#010101" fill-opacity=".3">license</text><text x="23.5" y="14">license</text><text x="62.5" y="15" fill="#010101" fill-opacity=".3">BSD</text><text x="62.5" y="14">BSD</text></g></svg>

docs/_static/python-versions.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="154" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="154" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h49v20H0z"/><path fill="#007ec6" d="M49 0h105v20H49z"/><path fill="url(#b)" d="M0 0h154v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11"><text x="24.5" y="15" fill="#010101" fill-opacity=".3">python</text><text x="24.5" y="14">python</text><text x="100.5" y="15" fill="#010101" fill-opacity=".3">2.7, 3.4, 3.5, 3.6</text><text x="100.5" y="14">2.7, 3.4, 3.5, 3.6</text></g></svg>

docs/_templates/layout.html

@@ -0,0 +1,26 @@
+{% extends '!layout.html' %}
+
+{% block extrahead %}
+<script async defer src="https://buttons.github.io/buttons.js"></script>
+<!-- Alabaster (krTheme++) Hacks, modified version of Kenneth Reitz' https://github.com/kennethreitz/requests/blob/master/docs/_templates/hacks.html -->
+<style type="text/css">
+    /* Rezzy requires precise alignment. */
+    img.logo {margin-left: -20px!important;}
+    /* "Quick Search" should be capitalized. */
+    div#searchbox h3 {text-transform: capitalize;}
+    /* Go button should be behind input field */
+    div.sphinxsidebar div#searchbox input[type="text"] {width: 160px}
+    div#searchbox form div {display: inline-block;}
+    /* Make the document a little wider, less code is cut-off. */
+    div.document {width: 1008px;}
+    /* Much-improved spacing around code blocks. */
+    div.highlight pre {padding: 11px 14px;}
+    /* Remain Responsive! */
+    @media screen and (max-width: 1008px) {
+        div.sphinxsidebar {display: none;}
+        div.document {width: 100%!important;}
+        /* Have code blocks escape the document right-margin. */
+        div.highlight pre {margin-right: -30px;}
+    }
+</style>
+{% endblock %}

docs/_templates/sidebar.html

@@ -0,0 +1,13 @@
+<h3>
+    <a href="{{ pathto(master_doc) }}">{{ _(project) }}</a>
+</h3>
+
+<p>
+    <a class="github-button" href="https://github.com/carpedm20/fbchat" data-size="large" data-show-count="true" aria-label="Star carpedm20/fbchat on GitHub">Star</a>
+</p>
+
+<p>
+    {{ _(shorttitle) }}
+</p>
+
+{{ toctree() }}

docs/api.rst

@@ -0,0 +1,44 @@
+.. module:: fbchat
+.. highlight:: python
+.. _api:
+
+Full API
+========
+
+If you are looking for information on a specific function, class, or method, this part of the documentation is for you.
+
+
+.. _api_client:
+
+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)
+
+.. autoclass:: Client(email, password, user_agent=None, max_tries=5, session_cookies=None, logging_level=logging.INFO)
+    :members:
+
+
+.. _api_models:
+
+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
+
+.. automodule:: fbchat.models
+    :members:
+    :undoc-members:
+
+
+.. _api_utils:
+
+Utils
+-----
+
+These functions and values are used internally by fbchat, and are subject to change. Do **NOT** rely on these to be backwards compatible!
+
+.. automodule:: fbchat.utils
+    :members:

docs/conf.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# fbchat documentation build configuration file, created by
+# sphinx-quickstart on Thu May 25 15:43:01 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+import fbchat
+import tests
+from fbchat import __copyright__, __author__, __version__, __description__
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# General information about the project.
+project = "fbchat"
+title = "fbchat Documentation"
+copyright = __copyright__
+author = __author__
+description = __description__
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = __version__
+# The full version, including alpha/beta/rc tags.
+release = __version__
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+
+html_theme = "alabaster"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = project + "doc"
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [(master_doc, project + ".tex", title, author, "manual")]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [(master_doc, project, title, [author], 1)]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, project, title, author, project, description, "Miscellaneous")
+]
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {"https://docs.python.org/3/": None}
+
+
+add_function_parentheses = False
+
+html_theme_options = {
+    "show_powered_by": False,
+    "github_user": "carpedm20",
+    "github_repo": project,
+    "github_banner": True,
+    "show_related": False,
+}
+
+html_sidebars = {"**": ["sidebar.html", "searchbox.html"]}
+
+html_show_sphinx = False
+html_show_sourcelink = False
+autoclass_content = "init"
+html_short_title = description

docs/examples.rst

@@ -0,0 +1,56 @@
+.. highlight:: python
+.. _examples:
+
+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`
+
+.. literalinclude:: ../examples/basic_usage.py
+
+
+Interacting with Threads
+------------------------
+
+This will interact with the thread in every way `fbchat` supports
+
+.. literalinclude:: ../examples/interract.py
+
+
+Fetching Information
+--------------------
+
+This will show the different ways of fetching information about users and threads
+
+.. literalinclude:: ../examples/fetch.py
+
+
+Echobot
+-------
+
+This will reply to any message with the same message
+
+.. literalinclude:: ../examples/echobot.py
+
+
+Remove Bot
+----------
+
+This will remove a user from a group if they write the message `Remove me!`
+
+.. literalinclude:: ../examples/removebot.py
+
+
+"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
+
+.. literalinclude:: ../examples/keepbot.py

docs/faq.rst

@@ -0,0 +1,44 @@
+.. highlight:: python
+.. module:: fbchat
+.. _faq:
+
+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
+
+.. code-block:: sh
+
+    $ 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 <https://github.com/carpedm20/fbchat>`_.
+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

docs/index.rst

@@ -0,0 +1,66 @@
+.. highlight:: python
+.. module:: fbchat
+.. fbchat documentation master file, created by
+   sphinx-quickstart on Thu May 25 15:43:01 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. This documentation's layout is heavily inspired by requests' layout: https://requests.readthedocs.io
+   Some documentation is also partially copied from facebook-chat-api: https://github.com/Schmavery/facebook-chat-api
+
+fbchat: Facebook Chat (Messenger) for Python
+============================================
+
+Release v\ |version|. (:ref:`install`)
+
+.. generated with: https://img.shields.io/badge/license-BSD-blue.svg
+
+.. image:: /_static/license.svg
+    :target: https://github.com/carpedm20/fbchat/blob/master/LICENSE.txt
+    :alt: License: BSD
+
+.. generated with: https://img.shields.io/badge/python-2.7%2C%203.4%2C%203.5%2C%203.6-blue.svg
+
+.. image:: /_static/python-versions.svg
+    :target: https://pypi.python.org/pypi/fbchat
+    :alt: Supported python versions: 2.7, 3.4, 3.5 and 3.6
+
+Facebook Chat (`Messenger <https://www.facebook.com/messages/>`_) for Python.
+This project was inspired by `facebook-chat-api <https://github.com/Schmavery/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 :ref:`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 <https://developers.facebook.com/docs/messenger-platform>`_ 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 :ref:`examples` to see example usage of `fbchat`
+
+
+Overview
+--------
+
+.. toctree::
+    :maxdepth: 2
+
+    install
+    intro
+    examples
+    testing
+    api
+    todo
+    faq

docs/install.rst

@@ -0,0 +1,36 @@
+.. highlight:: sh
+.. _install:
+
+Installation
+============
+
+Pip Install fbchat
+------------------
+
+To install fbchat, run this command::
+
+    $ pip install fbchat
+
+If you don't have `pip <https://pip.pypa.io>`_ installed,
+`this Python installation guide <http://docs.python-guide.org/en/latest/starting/installation/>`_
+can guide you through the process.
+
+Get the Source Code
+-------------------
+
+fbchat is developed on GitHub, where the code is
+`always available <https://github.com/carpedm20/fbchat>`_.
+
+You can either clone the public repository::
+
+    $ git clone git://github.com/carpedm20/fbchat.git
+
+Or, download a `tarball <https://github.com/carpedm20/fbchat/tarball/master>`_::
+
+    $ 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

docs/intro.rst

@@ -0,0 +1,200 @@
+.. highlight:: python
+.. module:: fbchat
+.. _intro:
+
+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
+
+
+.. _intro_logging_in:
+
+Logging In
+----------
+
+Simply create an instance of :class:`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 :func:`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 :class:`Client`)
+
+Throughout your code, if you want to check whether you are still logged in, use :func:`Client.isLoggedIn`.
+An example would be to login again if you've been logged out, using :func:`Client.login`::
+
+    if not client.isLoggedIn():
+        client.login('<email>', '<password>')
+
+When you're done using the client, and want to securely logout, use :func:`Client.logout`::
+
+    client.logout()
+
+
+.. _intro_threads:
+
+Threads
+-------
+
+A thread can refer to two things: A Messenger group chat or a single Facebook user
+
+:class:`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. :func:`Client.searchForGroups`,
+and searching for users is possible via. :func:`Client.searchForUsers`. See :ref:`intro_fetching`
+
+You can get your own user ID by using :any:`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:
+
+.. image:: /_static/find-group-id.png
+    :alt: 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. :func:`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>')
+
+
+.. _intro_message_ids:
+
+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 :func:`Client.reactToMessage`,
+and some of then provide this ID, like :func:`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)
+
+
+.. _intro_interacting:
+
+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 :ref:`examples`
+
+
+.. _intro_fetching:
+
+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 :func:`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 :ref:`examples`
+
+
+.. _intro_sessions:
+
+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 :func:`Client.getSession` to retrieve the cookies::
+
+    session_cookies = client.getSession()
+
+Then you can use :func:`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
+
+
+.. _intro_events:
+
+Listening & Events
+------------------
+
+To use the listening functions `fbchat` offers (like :func:`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 :class:`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 :ref:`examples` to see some more examples illustrating the event system

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=fbchat
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+	echo.then set the SPHINXBUILD environment variable to point to the full
+	echo.path of the 'sphinx-build' executable. Alternatively you may add the
+	echo.Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/testing.rst

@@ -0,0 +1,29 @@
+.. highlight:: sh
+.. module:: fbchat
+.. _testing:
+
+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)
+
+.. automodule:: tests
+    :members: TestFbchat
+    :undoc-members: TestFbchat

docs/todo.rst

@@ -0,0 +1,24 @@
+.. highlight:: python
+.. module:: fbchat
+.. _todo:
+
+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
+-------------
+
+.. todolist::

examples/basic_usage.py

@@ -0,0 +1,12 @@
+# -*- 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()

examples/echobot.py

@@ -0,0 +1,19 @@
+# -*- 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()

examples/fetch.py

@@ -0,0 +1,64 @@
+# -*- 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`

examples/interract.py

@@ -0,0 +1,93 @@
+# -*- 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)

examples/keepbot.py

@@ -0,0 +1,83 @@
+# -*- 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()

examples/removebot.py

@@ -0,0 +1,25 @@
+# -*- 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()

fbchat/__init__.py

@@ -1,26 +1,22 @@
 # -*- coding: UTF-8 -*-
+"""Facebook Chat (Messenger) for Python
 
-"""
-    fbchat
-    ~~~~~~
-
-    Facebook Chat (Messenger) for Python
-
-    :copyright: (c) 2015 by Taehoon Kim.
-    :license: BSD, see LICENSE for more details.
+:copyright: (c) 2015 - 2019 by Taehoon Kim
+:license: BSD 3-Clause, see LICENSE for more details.
 """
 
+from __future__ import unicode_literals
 
 from .client import *
 
+__title__ = "fbchat"
+__version__ = "1.6.2"
+__description__ = "Facebook Chat (Messenger) for Python"
 
-__copyright__ = 'Copyright 2015 by Taehoon Kim'
-__version__ = '0.9.3'
-__license__ = 'BSD'
-__author__ = 'Taehoon Kim; Moreels Pieter-Jan'
-__email__ = 'carpedm20@gmail.com'
-__source__ = 'https://github.com/carpedm20/fbchat/'
+__copyright__ = "Copyright 2015 - 2019 by Taehoon Kim"
+__license__ = "BSD 3-Clause"
 
-__all__ = [
-    'Client',
-]
+__author__ = "Taehoon Kim; Moreels Pieter-Jan; Mads Marquart"
+__email__ = "carpedm20@gmail.com"
+
+__all__ = ["Client"]

fbchat/graphql.py

@@ -0,0 +1,760 @@
+# -*- coding: UTF-8 -*-
+
+from __future__ import unicode_literals
+import json
+import re
+from .models import *
+from .utils import *
+
+# Shameless copy from https://stackoverflow.com/a/8730674
+FLAGS = re.VERBOSE | re.MULTILINE | re.DOTALL
+WHITESPACE = re.compile(r"[ \t\n\r]*", FLAGS)
+
+
+class ConcatJSONDecoder(json.JSONDecoder):
+    def decode(self, s, _w=WHITESPACE.match):
+        s_len = len(s)
+
+        objs = []
+        end = 0
+        while end != s_len:
+            obj, end = self.raw_decode(s, idx=_w(s, end).end())
+            end = _w(s, end).end()
+            objs.append(obj)
+        return objs
+
+
+# End shameless copy
+
+
+def graphql_color_to_enum(color):
+    if color is None:
+        return None
+    if not color:
+        return ThreadColor.MESSENGER_BLUE
+    color = color[2:]  # Strip the alpha value
+    color_value = "#{}".format(color.lower())
+    return enum_extend_if_invalid(ThreadColor, color_value)
+
+
+def get_customization_info(thread):
+    if thread is None or thread.get("customization_info") is None:
+        return {}
+    info = thread["customization_info"]
+
+    rtn = {
+        "emoji": info.get("emoji"),
+        "color": graphql_color_to_enum(info.get("outgoing_bubble_color")),
+    }
+    if (
+        thread.get("thread_type") == "GROUP"
+        or thread.get("is_group_thread")
+        or thread.get("thread_key", {}).get("thread_fbid")
+    ):
+        rtn["nicknames"] = {}
+        for k in info.get("participant_customizations", []):
+            rtn["nicknames"][k["participant_id"]] = k.get("nickname")
+    elif info.get("participant_customizations"):
+        uid = thread.get("thread_key", {}).get("other_user_id") or thread.get("id")
+        pc = info["participant_customizations"]
+        if len(pc) > 0:
+            if pc[0].get("participant_id") == uid:
+                rtn["nickname"] = pc[0].get("nickname")
+            else:
+                rtn["own_nickname"] = pc[0].get("nickname")
+        if len(pc) > 1:
+            if pc[1].get("participant_id") == uid:
+                rtn["nickname"] = pc[1].get("nickname")
+            else:
+                rtn["own_nickname"] = pc[1].get("nickname")
+    return rtn
+
+
+def graphql_to_sticker(s):
+    if not s:
+        return None
+    sticker = Sticker(uid=s["id"])
+    if s.get("pack"):
+        sticker.pack = s["pack"].get("id")
+    if s.get("sprite_image"):
+        sticker.is_animated = True
+        sticker.medium_sprite_image = s["sprite_image"].get("uri")
+        sticker.large_sprite_image = s["sprite_image_2x"].get("uri")
+        sticker.frames_per_row = s.get("frames_per_row")
+        sticker.frames_per_col = s.get("frames_per_column")
+        sticker.frame_rate = s.get("frame_rate")
+    sticker.url = s.get("url")
+    sticker.width = s.get("width")
+    sticker.height = s.get("height")
+    if s.get("label"):
+        sticker.label = s["label"]
+    return sticker
+
+
+def graphql_to_attachment(a):
+    _type = a["__typename"]
+    if _type in ["MessageImage", "MessageAnimatedImage"]:
+        return ImageAttachment(
+            original_extension=a.get("original_extension")
+            or (a["filename"].split("-")[0] if a.get("filename") else None),
+            width=a.get("original_dimensions", {}).get("width"),
+            height=a.get("original_dimensions", {}).get("height"),
+            is_animated=_type == "MessageAnimatedImage",
+            thumbnail_url=a.get("thumbnail", {}).get("uri"),
+            preview=a.get("preview") or a.get("preview_image"),
+            large_preview=a.get("large_preview"),
+            animated_preview=a.get("animated_image"),
+            uid=a.get("legacy_attachment_id"),
+        )
+    elif _type == "MessageVideo":
+        return VideoAttachment(
+            width=a.get("original_dimensions", {}).get("width"),
+            height=a.get("original_dimensions", {}).get("height"),
+            duration=a.get("playable_duration_in_ms"),
+            preview_url=a.get("playable_url"),
+            small_image=a.get("chat_image"),
+            medium_image=a.get("inbox_image"),
+            large_image=a.get("large_image"),
+            uid=a.get("legacy_attachment_id"),
+        )
+    elif _type == "MessageAudio":
+        return AudioAttachment(
+            filename=a.get("filename"),
+            url=a.get("playable_url"),
+            duration=a.get("playable_duration_in_ms"),
+            audio_type=a.get("audio_type"),
+        )
+    elif _type == "MessageFile":
+        return FileAttachment(
+            url=a.get("url"),
+            name=a.get("filename"),
+            is_malicious=a.get("is_malicious"),
+            uid=a.get("message_file_fbid"),
+        )
+    else:
+        return Attachment(uid=a.get("legacy_attachment_id"))
+
+
+def graphql_to_extensible_attachment(a):
+    story = a.get("story_attachment")
+    if story:
+        target = story.get("target")
+        if target:
+            _type = target["__typename"]
+            if _type == "MessageLocation":
+                latitude, longitude = get_url_parameter(
+                    get_url_parameter(story["url"], "u"), "where1"
+                ).split(", ")
+                rtn = LocationAttachment(
+                    uid=int(story["deduplication_key"]),
+                    latitude=float(latitude),
+                    longitude=float(longitude),
+                )
+                if story["media"]:
+                    rtn.image_url = story["media"]["image"]["uri"]
+                    rtn.image_width = story["media"]["image"]["width"]
+                    rtn.image_height = story["media"]["image"]["height"]
+                rtn.url = story["url"]
+                return rtn
+            elif _type == "MessageLiveLocation":
+                rtn = LiveLocationAttachment(
+                    uid=int(story["target"]["live_location_id"]),
+                    latitude=story["target"]["coordinate"]["latitude"]
+                    if story["target"].get("coordinate")
+                    else None,
+                    longitude=story["target"]["coordinate"]["longitude"]
+                    if story["target"].get("coordinate")
+                    else None,
+                    name=story["title_with_entities"]["text"],
+                    expiration_time=story["target"]["expiration_time"]
+                    if story["target"].get("expiration_time")
+                    else None,
+                    is_expired=story["target"]["is_expired"],
+                )
+                if story["media"]:
+                    rtn.image_url = story["media"]["image"]["uri"]
+                    rtn.image_width = story["media"]["image"]["width"]
+                    rtn.image_height = story["media"]["image"]["height"]
+                rtn.url = story["url"]
+                return rtn
+            elif _type in ["ExternalUrl", "Story"]:
+                return ShareAttachment(
+                    uid=a.get("legacy_attachment_id"),
+                    author=story["target"]["actors"][0]["id"]
+                    if story["target"].get("actors")
+                    else None,
+                    url=story["url"],
+                    original_url=get_url_parameter(story["url"], "u")
+                    if "/l.php?u=" in story["url"]
+                    else story["url"],
+                    title=story["title_with_entities"].get("text"),
+                    description=story["description"].get("text")
+                    if story.get("description")
+                    else None,
+                    source=story["source"]["text"],
+                    image_url=story["media"]["image"]["uri"]
+                    if story.get("media")
+                    else None,
+                    original_image_url=(
+                        get_url_parameter(story["media"]["image"]["uri"], "url")
+                        if "/safe_image.php" in story["media"]["image"]["uri"]
+                        else story["media"]["image"]["uri"]
+                    )
+                    if story.get("media")
+                    else None,
+                    image_width=story["media"]["image"]["width"]
+                    if story.get("media")
+                    else None,
+                    image_height=story["media"]["image"]["height"]
+                    if story.get("media")
+                    else None,
+                    attachments=[
+                        graphql_to_subattachment(attachment)
+                        for attachment in story.get("subattachments")
+                    ],
+                )
+        else:
+            return UnsentMessage(uid=a.get("legacy_attachment_id"))
+
+
+def graphql_to_subattachment(a):
+    _type = a["target"]["__typename"]
+    if _type == "Video":
+        return VideoAttachment(
+            duration=a["media"].get("playable_duration_in_ms"),
+            preview_url=a["media"].get("playable_url"),
+            medium_image=a["media"].get("image"),
+            uid=a["target"].get("video_id"),
+        )
+
+
+def graphql_to_live_location(a):
+    return LiveLocationAttachment(
+        uid=a["id"],
+        latitude=a["coordinate"]["latitude"] / (10 ** 8)
+        if not a.get("stopReason")
+        else None,
+        longitude=a["coordinate"]["longitude"] / (10 ** 8)
+        if not a.get("stopReason")
+        else None,
+        name=a.get("locationTitle"),
+        expiration_time=a["expirationTime"],
+        is_expired=bool(a.get("stopReason")),
+    )
+
+
+def graphql_to_poll(a):
+    rtn = Poll(
+        title=a.get("title") if a.get("title") else a.get("text"),
+        options=[graphql_to_poll_option(m) for m in a.get("options")],
+    )
+    rtn.uid = int(a["id"])
+    rtn.options_count = a.get("total_count")
+    return rtn
+
+
+def graphql_to_poll_option(a):
+    if a.get("viewer_has_voted") is None:
+        vote = None
+    elif isinstance(a["viewer_has_voted"], bool):
+        vote = a["viewer_has_voted"]
+    else:
+        vote = a["viewer_has_voted"] == "true"
+    rtn = PollOption(text=a.get("text"), vote=vote)
+    rtn.uid = int(a["id"])
+    rtn.voters = (
+        [m.get("node").get("id") for m in a.get("voters").get("edges")]
+        if isinstance(a.get("voters"), dict)
+        else a.get("voters")
+    )
+    rtn.votes_count = (
+        a.get("voters").get("count")
+        if isinstance(a.get("voters"), dict)
+        else a.get("total_count")
+    )
+    return rtn
+
+
+def graphql_to_plan(a):
+    if a.get("event_members"):
+        rtn = Plan(
+            time=a.get("event_time"),
+            title=a.get("title"),
+            location=a.get("location_name"),
+        )
+        if a.get("location_id") != 0:
+            rtn.location_id = str(a.get("location_id"))
+        rtn.uid = a.get("oid")
+        rtn.author_id = a.get("creator_id")
+        guests = a.get("event_members")
+        rtn.going = [uid for uid in guests if guests[uid] == "GOING"]
+        rtn.declined = [uid for uid in guests if guests[uid] == "DECLINED"]
+        rtn.invited = [uid for uid in guests if guests[uid] == "INVITED"]
+        return rtn
+    elif a.get("id") is None:
+        rtn = Plan(
+            time=a.get("event_time"),
+            title=a.get("event_title"),
+            location=a.get("event_location_name"),
+            location_id=a.get("event_location_id"),
+        )
+        rtn.uid = a.get("event_id")
+        rtn.author_id = a.get("event_creator_id")
+        guests = json.loads(a.get("guest_state_list"))
+    else:
+        rtn = Plan(
+            time=a.get("time"),
+            title=a.get("event_title"),
+            location=a.get("location_name"),
+        )
+        rtn.uid = a.get("id")
+        rtn.author_id = a.get("lightweight_event_creator").get("id")
+        guests = a.get("event_reminder_members").get("edges")
+    rtn.going = [
+        m.get("node").get("id") for m in guests if m.get("guest_list_state") == "GOING"
+    ]
+    rtn.declined = [
+        m.get("node").get("id")
+        for m in guests
+        if m.get("guest_list_state") == "DECLINED"
+    ]
+    rtn.invited = [
+        m.get("node").get("id")
+        for m in guests
+        if m.get("guest_list_state") == "INVITED"
+    ]
+    return rtn
+
+
+def graphql_to_quick_reply(q, is_response=False):
+    data = dict()
+    _type = q.get("content_type").lower()
+    if q.get("payload"):
+        data["payload"] = q["payload"]
+    if q.get("data"):
+        data["data"] = q["data"]
+    if q.get("image_url") and _type is not QuickReplyLocation._type:
+        data["image_url"] = q["image_url"]
+    data["is_response"] = is_response
+    if _type == QuickReplyText._type:
+        if q.get("title") is not None:
+            data["title"] = q["title"]
+        rtn = QuickReplyText(**data)
+    elif _type == QuickReplyLocation._type:
+        rtn = QuickReplyLocation(**data)
+    elif _type == QuickReplyPhoneNumber._type:
+        rtn = QuickReplyPhoneNumber(**data)
+    elif _type == QuickReplyEmail._type:
+        rtn = QuickReplyEmail(**data)
+    return rtn
+
+
+def graphql_to_message(message):
+    if message.get("message_sender") is None:
+        message["message_sender"] = {}
+    if message.get("message") is None:
+        message["message"] = {}
+    rtn = Message(
+        text=message.get("message").get("text"),
+        mentions=[
+            Mention(
+                m.get("entity", {}).get("id"),
+                offset=m.get("offset"),
+                length=m.get("length"),
+            )
+            for m in message.get("message").get("ranges", [])
+        ],
+        emoji_size=get_emojisize_from_tags(message.get("tags_list")),
+        sticker=graphql_to_sticker(message.get("sticker")),
+    )
+    rtn.uid = str(message.get("message_id"))
+    rtn.author = str(message.get("message_sender").get("id"))
+    rtn.timestamp = message.get("timestamp_precise")
+    rtn.unsent = False
+    if message.get("unread") is not None:
+        rtn.is_read = not message["unread"]
+    rtn.reactions = {
+        str(r["user"]["id"]): enum_extend_if_invalid(MessageReaction, r["reaction"])
+        for r in message.get("message_reactions")
+    }
+    if message.get("blob_attachments") is not None:
+        rtn.attachments = [
+            graphql_to_attachment(attachment)
+            for attachment in message["blob_attachments"]
+        ]
+    if message.get("platform_xmd_encoded"):
+        quick_replies = json.loads(message["platform_xmd_encoded"]).get("quick_replies")
+        if isinstance(quick_replies, list):
+            rtn.quick_replies = [graphql_to_quick_reply(q) for q in quick_replies]
+        elif isinstance(quick_replies, dict):
+            rtn.quick_replies = [
+                graphql_to_quick_reply(quick_replies, is_response=True)
+            ]
+    if message.get("extensible_attachment") is not None:
+        attachment = graphql_to_extensible_attachment(message["extensible_attachment"])
+        if isinstance(attachment, UnsentMessage):
+            rtn.unsent = True
+        elif attachment:
+            rtn.attachments.append(attachment)
+    return rtn
+
+
+def graphql_to_user(user):
+    if user.get("profile_picture") is None:
+        user["profile_picture"] = {}
+    c_info = get_customization_info(user)
+    plan = None
+    if user.get("event_reminders"):
+        plan = (
+            graphql_to_plan(user["event_reminders"]["nodes"][0])
+            if user["event_reminders"].get("nodes")
+            else None
+        )
+    return User(
+        user["id"],
+        url=user.get("url"),
+        first_name=user.get("first_name"),
+        last_name=user.get("last_name"),
+        is_friend=user.get("is_viewer_friend"),
+        gender=GENDERS.get(user.get("gender")),
+        affinity=user.get("affinity"),
+        nickname=c_info.get("nickname"),
+        color=c_info.get("color"),
+        emoji=c_info.get("emoji"),
+        own_nickname=c_info.get("own_nickname"),
+        photo=user["profile_picture"].get("uri"),
+        name=user.get("name"),
+        message_count=user.get("messages_count"),
+        plan=plan,
+    )
+
+
+def graphql_to_thread(thread):
+    if thread["thread_type"] == "GROUP":
+        return graphql_to_group(thread)
+    elif thread["thread_type"] == "ONE_TO_ONE":
+        if thread.get("big_image_src") is None:
+            thread["big_image_src"] = {}
+        c_info = get_customization_info(thread)
+        participants = [
+            node["messaging_actor"] for node in thread["all_participants"]["nodes"]
+        ]
+        user = next(
+            p for p in participants if p["id"] == thread["thread_key"]["other_user_id"]
+        )
+        last_message_timestamp = None
+        if "last_message" in thread:
+            last_message_timestamp = thread["last_message"]["nodes"][0][
+                "timestamp_precise"
+            ]
+
+        first_name = user.get("short_name")
+        if first_name is None:
+            last_name = None
+        else:
+            last_name = user.get("name").split(first_name, 1).pop().strip()
+
+        plan = None
+        if thread.get("event_reminders"):
+            plan = (
+                graphql_to_plan(thread["event_reminders"]["nodes"][0])
+                if thread["event_reminders"].get("nodes")
+                else None
+            )
+
+        return User(
+            user["id"],
+            url=user.get("url"),
+            name=user.get("name"),
+            first_name=first_name,
+            last_name=last_name,
+            is_friend=user.get("is_viewer_friend"),
+            gender=GENDERS.get(user.get("gender")),
+            affinity=user.get("affinity"),
+            nickname=c_info.get("nickname"),
+            color=c_info.get("color"),
+            emoji=c_info.get("emoji"),
+            own_nickname=c_info.get("own_nickname"),
+            photo=user["big_image_src"].get("uri"),
+            message_count=thread.get("messages_count"),
+            last_message_timestamp=last_message_timestamp,
+            plan=plan,
+        )
+    else:
+        raise FBchatException(
+            "Unknown thread type: {}, with data: {}".format(
+                thread.get("thread_type"), thread
+            )
+        )
+
+
+def graphql_to_group(group):
+    if group.get("image") is None:
+        group["image"] = {}
+    c_info = get_customization_info(group)
+    last_message_timestamp = None
+    if "last_message" in group:
+        last_message_timestamp = group["last_message"]["nodes"][0]["timestamp_precise"]
+    plan = None
+    if group.get("event_reminders"):
+        plan = (
+            graphql_to_plan(group["event_reminders"]["nodes"][0])
+            if group["event_reminders"].get("nodes")
+            else None
+        )
+    return Group(
+        group["thread_key"]["thread_fbid"],
+        participants=set(
+            [
+                node["messaging_actor"]["id"]
+                for node in group["all_participants"]["nodes"]
+            ]
+        ),
+        nicknames=c_info.get("nicknames"),
+        color=c_info.get("color"),
+        emoji=c_info.get("emoji"),
+        admins=set([node.get("id") for node in group.get("thread_admins")]),
+        approval_mode=bool(group.get("approval_mode"))
+        if group.get("approval_mode") is not None
+        else None,
+        approval_requests=set(
+            node["requester"]["id"] for node in group["group_approval_queue"]["nodes"]
+        )
+        if group.get("group_approval_queue")
+        else None,
+        join_link=group["joinable_mode"].get("link"),
+        photo=group["image"].get("uri"),
+        name=group.get("name"),
+        message_count=group.get("messages_count"),
+        last_message_timestamp=last_message_timestamp,
+        plan=plan,
+    )
+
+
+def graphql_to_page(page):
+    if page.get("profile_picture") is None:
+        page["profile_picture"] = {}
+    if page.get("city") is None:
+        page["city"] = {}
+    plan = None
+    if page.get("event_reminders"):
+        plan = (
+            graphql_to_plan(page["event_reminders"]["nodes"][0])
+            if page["event_reminders"].get("nodes")
+            else None
+        )
+    return Page(
+        page["id"],
+        url=page.get("url"),
+        city=page.get("city").get("name"),
+        category=page.get("category_type"),
+        photo=page["profile_picture"].get("uri"),
+        name=page.get("name"),
+        message_count=page.get("messages_count"),
+        plan=plan,
+    )
+
+
+def graphql_queries_to_json(*queries):
+    """
+    Queries should be a list of GraphQL objects
+    """
+    rtn = {}
+    for i, query in enumerate(queries):
+        rtn["q{}".format(i)] = query.value
+    return json.dumps(rtn)
+
+
+def graphql_response_to_json(content):
+    content = strip_to_json(content)  # Usually only needed in some error cases
+    try:
+        j = json.loads(content, cls=ConcatJSONDecoder)
+    except Exception:
+        raise FBchatException("Error while parsing JSON: {}".format(repr(content)))
+
+    rtn = [None] * (len(j))
+    for x in j:
+        if "error_results" in x:
+            del rtn[-1]
+            continue
+        check_json(x)
+        [(key, value)] = x.items()
+        check_json(value)
+        if "response" in value:
+            rtn[int(key[1:])] = value["response"]
+        else:
+            rtn[int(key[1:])] = value["data"]
+
+    log.debug(rtn)
+
+    return rtn
+
+
+class GraphQL(object):
+    def __init__(self, query=None, doc_id=None, params=None):
+        if params is None:
+            params = {}
+        if query is not None:
+            self.value = {"priority": 0, "q": query, "query_params": params}
+        elif doc_id is not None:
+            self.value = {"doc_id": doc_id, "query_params": params}
+        else:
+            raise FBchatUserError("A query or doc_id must be specified")
+
+    FRAGMENT_USER = """
+    QueryFragment User: User {
+        id,
+        name,
+        first_name,
+        last_name,
+        profile_picture.width(<pic_size>).height(<pic_size>) {
+            uri
+        },
+        is_viewer_friend,
+        url,
+        gender,
+        viewer_affinity
+    }
+    """
+
+    FRAGMENT_GROUP = """
+    QueryFragment Group: MessageThread {
+        name,
+        thread_key {
+            thread_fbid
+        },
+        image {
+            uri
+        },
+        is_group_thread,
+        all_participants {
+            nodes {
+                messaging_actor {
+                    id
+                }
+            }
+        },
+        customization_info {
+            participant_customizations {
+                participant_id,
+                nickname
+            },
+            outgoing_bubble_color,
+            emoji
+        },
+        thread_admins {
+            id
+        },
+        group_approval_queue {
+            nodes {
+                requester {
+                    id
+                }
+            }
+        },
+        approval_mode,
+        joinable_mode {
+            mode,
+            link
+        },
+        event_reminders {
+            nodes {
+                id,
+                lightweight_event_creator {
+                    id
+                },
+                time,
+                location_name,
+                event_title,
+                event_reminder_members {
+                    edges {
+                        node {
+                            id
+                        },
+                        guest_list_state
+                    }
+                }
+            }
+        }
+    }
+    """
+
+    FRAGMENT_PAGE = """
+    QueryFragment Page: Page {
+        id,
+        name,
+        profile_picture.width(32).height(32) {
+            uri
+        },
+        url,
+        category_type,
+        city {
+            name
+        }
+    }
+    """
+
+    SEARCH_USER = (
+        """
+    Query SearchUser(<search> = '', <limit> = 10) {
+        entities_named(<search>) {
+            search_results.of_type(user).first(<limit>) as users {
+                nodes {
+                    @User
+                }
+            }
+        }
+    }
+    """
+        + FRAGMENT_USER
+    )
+
+    SEARCH_GROUP = (
+        """
+    Query SearchGroup(<search> = '', <limit> = 10, <pic_size> = 32) {
+        viewer() {
+            message_threads.with_thread_name(<search>).last(<limit>) as groups {
+                nodes {
+                    @Group
+                }
+            }
+        }
+    }
+    """
+        + FRAGMENT_GROUP
+    )
+
+    SEARCH_PAGE = (
+        """
+    Query SearchPage(<search> = '', <limit> = 10) {
+        entities_named(<search>) {
+            search_results.of_type(page).first(<limit>) as pages {
+                nodes {
+                    @Page
+                }
+            }
+        }
+    }
+    """
+        + FRAGMENT_PAGE
+    )
+
+    SEARCH_THREAD = (
+        """
+    Query SearchThread(<search> = '', <limit> = 10) {
+        entities_named(<search>) {
+            search_results.first(<limit>) as threads {
+                nodes {
+                    __typename,
+                    @User,
+                    @Group,
+                    @Page
+                }
+            }
+        }
+    }
+    """
+        + FRAGMENT_USER
+        + FRAGMENT_GROUP
+        + FRAGMENT_PAGE
+    )

fbchat/models.py

@@ -1,31 +1,957 @@
-from __future__ import unicode_literals
-import sys
+# -*- coding: UTF-8 -*-
+
+from __future__ import unicode_literals
+import aenum
+from string import Formatter
+
+
+class FBchatException(Exception):
+    """Custom exception thrown by fbchat. All exceptions in the fbchat module inherits this"""
+
+
+class FBchatFacebookError(FBchatException):
+    #: The error code that Facebook returned
+    fb_error_code = None
+    #: The error message that Facebook returned (In the user's own language)
+    fb_error_message = None
+    #: The status code that was sent in the http response (eg. 404) (Usually only set if not successful, aka. not 200)
+    request_status_code = None
+
+    def __init__(
+        self,
+        message,
+        fb_error_code=None,
+        fb_error_message=None,
+        request_status_code=None,
+    ):
+        super(FBchatFacebookError, self).__init__(message)
+        """Thrown by fbchat when Facebook returns an error"""
+        self.fb_error_code = str(fb_error_code)
+        self.fb_error_message = fb_error_message
+        self.request_status_code = request_status_code
+
+
+class FBchatUserError(FBchatException):
+    """Thrown by fbchat when wrong values are entered"""
+
+
+class Thread(object):
+    #: The unique identifier of the thread. Can be used a `thread_id`. See :ref:`intro_threads` for more info
+    uid = None
+    #: Specifies the type of thread. Can be used a `thread_type`. See :ref:`intro_threads` for more info
+    type = None
+    #: A url to the thread's picture
+    photo = None
+    #: The name of the thread
+    name = None
+    #: Timestamp of last message
+    last_message_timestamp = None
+    #: Number of messages in the thread
+    message_count = None
+    #: Set :class:`Plan`
+    plan = None
+
+    def __init__(
+        self,
+        _type,
+        uid,
+        photo=None,
+        name=None,
+        last_message_timestamp=None,
+        message_count=None,
+        plan=None,
+    ):
+        """Represents a Facebook thread"""
+        self.uid = str(uid)
+        self.type = _type
+        self.photo = photo
+        self.name = name
+        self.last_message_timestamp = last_message_timestamp
+        self.message_count = message_count
+        self.plan = plan
 
-class Base():
     def __repr__(self):
-        uni = self.__unicode__()
-        return uni.encode('utf-8') if sys.version_info < (3, 0) else uni
+        return self.__unicode__()
 
     def __unicode__(self):
-        return u'<%s %s (%s)>' % (self.type.upper(), self.name, self.url)
+        return "<{} {} ({})>".format(self.type.name, self.name, self.uid)
 
-class User(Base):
-    def __init__(self, data):
-        if data['type'] != 'user':
-            raise Exception("[!] %s <%s> is not a user" % (data['text'], data['path']))
-        self.uid = data['uid']
-        self.type = data['type']
-        self.photo = data['photo']
-        self.url = data['path']
-        self.name = data['text']
-        self.score = data['score']
 
+class User(Thread):
+    #: The profile url
+    url = None
+    #: The users first name
+    first_name = None
+    #: The users last name
+    last_name = None
+    #: Whether the user and the client are friends
+    is_friend = None
+    #: The user's gender
+    gender = None
+    #: From 0 to 1. How close the client is to the user
+    affinity = None
+    #: The user's nickname
+    nickname = None
+    #: The clients nickname, as seen by the user
+    own_nickname = None
+    #: A :class:`ThreadColor`. The message color
+    color = None
+    #: The default emoji
+    emoji = None
+
+    def __init__(
+        self,
+        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
+    ):
+        """Represents a Facebook user. Inherits `Thread`"""
+        super(User, self).__init__(ThreadType.USER, uid, **kwargs)
+        self.url = url
+        self.first_name = first_name
+        self.last_name = last_name
+        self.is_friend = is_friend
+        self.gender = gender
+        self.affinity = affinity
+        self.nickname = nickname
+        self.own_nickname = own_nickname
+        self.color = color
+        self.emoji = emoji
+
+
+class Group(Thread):
+    #: Unique list (set) of the group thread's participant user IDs
+    participants = None
+    #: A dict, containing user nicknames mapped to their IDs
+    nicknames = None
+    #: A :class:`ThreadColor`. The groups's message color
+    color = None
+    #: The groups's default emoji
+    emoji = None
+    # Set containing user IDs of thread admins
+    admins = None
+    # True if users need approval to join
+    approval_mode = None
+    # Set containing user IDs requesting to join
+    approval_requests = None
+    # Link for joining group
+    join_link = None
+
+    def __init__(
+        self,
+        uid,
+        participants=None,
+        nicknames=None,
+        color=None,
+        emoji=None,
+        admins=None,
+        approval_mode=None,
+        approval_requests=None,
+        join_link=None,
+        privacy_mode=None,
+        **kwargs
+    ):
+        """Represents a Facebook group. Inherits `Thread`"""
+        super(Group, self).__init__(ThreadType.GROUP, uid, **kwargs)
+        if participants is None:
+            participants = set()
+        self.participants = participants
+        if nicknames is None:
+            nicknames = []
+        self.nicknames = nicknames
+        self.color = color
+        self.emoji = emoji
+        if admins is None:
+            admins = set()
+        self.admins = admins
+        self.approval_mode = approval_mode
+        if approval_requests is None:
+            approval_requests = set()
+        self.approval_requests = approval_requests
+        self.join_link = join_link
+
+
+class Room(Group):
+    # True is room is not discoverable
+    privacy_mode = None
+
+    def __init__(self, uid, privacy_mode=None, **kwargs):
+        """Deprecated. Use :class:`Group` instead"""
+        super(Room, self).__init__(uid, **kwargs)
+        self.type = ThreadType.ROOM
+        self.privacy_mode = privacy_mode
+
+
+class Page(Thread):
+    #: The page's custom url
+    url = None
+    #: The name of the page's location city
+    city = None
+    #: Amount of likes the page has
+    likes = None
+    #: Some extra information about the page
+    sub_title = None
+    #: The page's category
+    category = None
+
+    def __init__(
+        self,
+        uid,
+        url=None,
+        city=None,
+        likes=None,
+        sub_title=None,
+        category=None,
+        **kwargs
+    ):
+        """Represents a Facebook page. Inherits `Thread`"""
+        super(Page, self).__init__(ThreadType.PAGE, uid, **kwargs)
+        self.url = url
+        self.city = city
+        self.likes = likes
+        self.sub_title = sub_title
+        self.category = category
+
+
+class Message(object):
+    #: The actual message
+    text = None
+    #: A list of :class:`Mention` objects
+    mentions = None
+    #: A :class:`EmojiSize`. Size of a sent emoji
+    emoji_size = None
+    #: The message ID
+    uid = None
+    #: ID of the sender
+    author = None
+    #: Timestamp of when the message was sent
+    timestamp = None
+    #: Whether the message is read
+    is_read = None
+    #: A list of pepole IDs who read the message, works only with :func:`fbchat.Client.fetchThreadMessages`
+    read_by = None
+    #: A dict with user's IDs as keys, and their :class:`MessageReaction` as values
+    reactions = None
+    #: The actual message
+    text = None
+    #: A :class:`Sticker`
+    sticker = None
+    #: A list of attachments
+    attachments = None
+    #: A list of :class:`QuickReply`
+    quick_replies = None
+    #: Whether the message is unsent (deleted for everyone)
+    unsent = None
+
+    def __init__(
+        self,
+        text=None,
+        mentions=None,
+        emoji_size=None,
+        sticker=None,
+        attachments=None,
+        quick_replies=None,
+    ):
+        """Represents a Facebook message"""
+        self.text = text
+        if mentions is None:
+            mentions = []
+        self.mentions = mentions
+        self.emoji_size = emoji_size
+        self.sticker = sticker
+        if attachments is None:
+            attachments = []
+        self.attachments = attachments
+        if quick_replies is None:
+            quick_replies = []
+        self.quick_replies = quick_replies
+        self.reactions = {}
+        self.read_by = []
+        self.deleted = False
+
+    def __repr__(self):
+        return self.__unicode__()
+
+    def __unicode__(self):
+        return "<Message ({}): {}, mentions={} emoji_size={} attachments={}>".format(
+            self.uid, repr(self.text), self.mentions, self.emoji_size, self.attachments
+        )
+
+    @classmethod
+    def formatMentions(cls, text, *args, **kwargs):
+        """Like `str.format`, but takes tuples with a thread id and text instead.
+
+        Returns 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=[]>
+        ```
+        """
+        result = ""
+        mentions = list()
+        offset = 0
+        f = Formatter()
+        field_names = [field_name[1] for field_name in f.parse(text)]
+        automatic = "" in field_names
+        i = 0
+
+        for (literal_text, field_name, format_spec, conversion) in f.parse(text):
+            offset += len(literal_text)
+            result += literal_text
+
+            if field_name is None:
+                continue
+
+            if field_name == "":
+                field_name = str(i)
+                i += 1
+            elif automatic and field_name.isdigit():
+                raise ValueError(
+                    "cannot switch from automatic field numbering to manual field specification"
+                )
+
+            thread_id, name = f.get_field(field_name, args, kwargs)[0]
+
+            if format_spec:
+                name = f.format_field(name, format_spec)
+            if conversion:
+                name = f.convert_field(name, conversion)
+
+            result += name
+            mentions.append(
+                Mention(thread_id=thread_id, offset=offset, length=len(name))
+            )
+            offset += len(name)
+
+        message = cls(text=result, mentions=mentions)
+        return message
+
+
+class Attachment(object):
+    #: The attachment ID
+    uid = None
+
+    def __init__(self, uid=None):
+        """Represents a Facebook attachment"""
+        self.uid = uid
+
+
+class UnsentMessage(Attachment):
+    def __init__(self, *args, **kwargs):
+        """Represents an unsent message attachment"""
+        super(UnsentMessage, self).__init__(*args, **kwargs)
+
+
+class Sticker(Attachment):
+    #: The sticker-pack's ID
+    pack = None
+    #: Whether the sticker is animated
+    is_animated = False
+
+    # If the sticker is animated, the following should be present
+    #: URL to a medium spritemap
+    medium_sprite_image = None
+    #: URL to a large spritemap
+    large_sprite_image = None
+    #: The amount of frames present in the spritemap pr. row
+    frames_per_row = None
+    #: The amount of frames present in the spritemap pr. coloumn
+    frames_per_col = None
+    #: The frame rate the spritemap is intended to be played in
+    frame_rate = None
+
+    #: URL to the sticker's image
+    url = None
+    #: Width of the sticker
+    width = None
+    #: Height of the sticker
+    height = None
+    #: The sticker's label/name
+    label = None
+
+    def __init__(self, *args, **kwargs):
+        """Represents a Facebook sticker that has been sent to a Facebook thread as an attachment"""
+        super(Sticker, self).__init__(*args, **kwargs)
+
+
+class ShareAttachment(Attachment):
+    #: ID of the author of the shared post
+    author = None
+    #: Target URL
+    url = None
+    #: Original URL if Facebook redirects the URL
+    original_url = None
+    #: Title of the attachment
+    title = None
+    #: Description of the attachment
+    description = None
+    #: Name of the source
+    source = None
+    #: URL of the attachment image
+    image_url = None
+    #: URL of the original image if Facebook uses `safe_image`
+    original_image_url = None
+    #: Width of the image
+    image_width = None
+    #: Height of the image
+    image_height = None
+    #: List of additional attachments
+    attachments = None
+
+    def __init__(
+        self,
+        author=None,
+        url=None,
+        original_url=None,
+        title=None,
+        description=None,
+        source=None,
+        image_url=None,
+        original_image_url=None,
+        image_width=None,
+        image_height=None,
+        attachments=None,
+        **kwargs
+    ):
+        """Represents a shared item (eg. URL) that has been sent as a Facebook attachment"""
+        super(ShareAttachment, self).__init__(**kwargs)
+        self.author = author
+        self.url = url
+        self.original_url = original_url
+        self.title = title
+        self.description = description
+        self.source = source
+        self.image_url = image_url
+        self.original_image_url = original_image_url
+        self.image_width = image_width
+        self.image_height = image_height
+        if attachments is None:
+            attachments = []
+        self.attachments = attachments
+
+
+class LocationAttachment(Attachment):
+    #: Latidute of the location
+    latitude = None
+    #: Longitude of the location
+    longitude = None
+    #: URL of image showing the map of the location
+    image_url = None
+    #: Width of the image
+    image_width = None
+    #: Height of the image
+    image_height = None
+    #: URL to Bing maps with the location
+    url = None
+
+    def __init__(self, latitude=None, longitude=None, **kwargs):
+        """Represents a user location"""
+        super(LocationAttachment, self).__init__(**kwargs)
+        self.latitude = latitude
+        self.longitude = longitude
+
+
+class LiveLocationAttachment(LocationAttachment):
+    #: Name of the location
+    name = None
+    #: Timestamp when live location expires
+    expiration_time = None
+    #: True if live location is expired
+    is_expired = None
+
+    def __init__(self, name=None, expiration_time=None, is_expired=None, **kwargs):
+        """Represents a live user location"""
+        super(LiveLocationAttachment, self).__init__(**kwargs)
+        self.expiration_time = expiration_time
+        self.is_expired = is_expired
+
+
+class FileAttachment(Attachment):
+    #: Url where you can download the file
+    url = None
+    #: Size of the file in bytes
+    size = None
+    #: Name of the file
+    name = None
+    #: Whether Facebook determines that this file may be harmful
+    is_malicious = None
+
+    def __init__(self, url=None, size=None, name=None, is_malicious=None, **kwargs):
+        """Represents a file that has been sent as a Facebook attachment"""
+        super(FileAttachment, self).__init__(**kwargs)
+        self.url = url
+        self.size = size
+        self.name = name
+        self.is_malicious = is_malicious
+
+
+class AudioAttachment(Attachment):
+    #: Name of the file
+    filename = None
+    #: Url of the audio file
+    url = None
+    #: Duration of the audioclip in milliseconds
+    duration = None
+    #: Audio type
+    audio_type = None
+
+    def __init__(
+        self, filename=None, url=None, duration=None, audio_type=None, **kwargs
+    ):
+        """Represents an audio file that has been sent as a Facebook attachment"""
+        super(AudioAttachment, self).__init__(**kwargs)
+        self.filename = filename
+        self.url = url
+        self.duration = duration
+        self.audio_type = audio_type
+
+
+class ImageAttachment(Attachment):
+    #: The extension of the original image (eg. 'png')
+    original_extension = None
+    #: Width of original image
+    width = None
+    #: Height of original image
+    height = None
+
+    #: Whether the image is animated
+    is_animated = None
+
+    #: URL to a thumbnail of the image
+    thumbnail_url = None
+
+    #: URL to a medium preview of the image
+    preview_url = None
+    #: Width of the medium preview image
+    preview_width = None
+    #: Height of the medium preview image
+    preview_height = None
+
+    #: URL to a large preview of the image
+    large_preview_url = None
+    #: Width of the large preview image
+    large_preview_width = None
+    #: Height of the large preview image
+    large_preview_height = None
+
+    #: URL to an animated preview of the image (eg. for gifs)
+    animated_preview_url = None
+    #: Width of the animated preview image
+    animated_preview_width = None
+    #: Height of the animated preview image
+    animated_preview_height = None
+
+    def __init__(
+        self,
+        original_extension=None,
+        width=None,
+        height=None,
+        is_animated=None,
+        thumbnail_url=None,
+        preview=None,
+        large_preview=None,
+        animated_preview=None,
+        **kwargs
+    ):
+        """
+        Represents an image that has been sent as a Facebook attachment
+        To retrieve the full image url, use: :func:`fbchat.Client.fetchImageUrl`,
+        and pass it the uid of the image attachment
+        """
+        super(ImageAttachment, self).__init__(**kwargs)
+        self.original_extension = original_extension
+        if width is not None:
+            width = int(width)
+        self.width = width
+        if height is not None:
+            height = int(height)
+        self.height = height
+        self.is_animated = is_animated
+        self.thumbnail_url = thumbnail_url
+
+        if preview is None:
+            preview = {}
+        self.preview_url = preview.get("uri")
+        self.preview_width = preview.get("width")
+        self.preview_height = preview.get("height")
+
+        if large_preview is None:
+            large_preview = {}
+        self.large_preview_url = large_preview.get("uri")
+        self.large_preview_width = large_preview.get("width")
+        self.large_preview_height = large_preview.get("height")
+
+        if animated_preview is None:
+            animated_preview = {}
+        self.animated_preview_url = animated_preview.get("uri")
+        self.animated_preview_width = animated_preview.get("width")
+        self.animated_preview_height = animated_preview.get("height")
+
+
+class VideoAttachment(Attachment):
+    #: Size of the original video in bytes
+    size = None
+    #: Width of original video
+    width = None
+    #: Height of original video
+    height = None
+    #: Length of video in milliseconds
+    duration = None
+    #: URL to very compressed preview video
+    preview_url = None
+
+    #: URL to a small preview image of the video
+    small_image_url = None
+    #: Width of the small preview image
+    small_image_width = None
+    #: Height of the small preview image
+    small_image_height = None
+
+    #: URL to a medium preview image of the video
+    medium_image_url = None
+    #: Width of the medium preview image
+    medium_image_width = None
+    #: Height of the medium preview image
+    medium_image_height = None
+
+    #: URL to a large preview image of the video
+    large_image_url = None
+    #: Width of the large preview image
+    large_image_width = None
+    #: Height of the large preview image
+    large_image_height = None
+
+    def __init__(
+        self,
+        size=None,
+        width=None,
+        height=None,
+        duration=None,
+        preview_url=None,
+        small_image=None,
+        medium_image=None,
+        large_image=None,
+        **kwargs
+    ):
+        """Represents a video that has been sent as a Facebook attachment"""
+        super(VideoAttachment, self).__init__(**kwargs)
+        self.size = size
+        self.width = width
+        self.height = height
+        self.duration = duration
+        self.preview_url = preview_url
+
+        if small_image is None:
+            small_image = {}
+        self.small_image_url = small_image.get("uri")
+        self.small_image_width = small_image.get("width")
+        self.small_image_height = small_image.get("height")
+
+        if medium_image is None:
+            medium_image = {}
+        self.medium_image_url = medium_image.get("uri")
+        self.medium_image_width = medium_image.get("width")
+        self.medium_image_height = medium_image.get("height")
+
+        if large_image is None:
+            large_image = {}
+        self.large_image_url = large_image.get("uri")
+        self.large_image_width = large_image.get("width")
+        self.large_image_height = large_image.get("height")
+
+
+class Mention(object):
+    #: The thread ID the mention is pointing at
+    thread_id = None
+    #: The character where the mention starts
+    offset = None
+    #: The length of the mention
+    length = None
+
+    def __init__(self, thread_id, offset=0, length=10):
+        """Represents a @mention"""
+        self.thread_id = thread_id
+        self.offset = offset
+        self.length = length
+
+    def __repr__(self):
+        return self.__unicode__()
+
+    def __unicode__(self):
+        return "<Mention {}: offset={} length={}>".format(
+            self.thread_id, self.offset, self.length
+        )
+
+
+class QuickReply(object):
+    #: Payload of the quick reply
+    payload = None
+    #: External payload for responses
+    external_payload = None
+    #: Additional data
+    data = None
+    #: Whether it's a response for a quick reply
+    is_response = None
+
+    def __init__(self, payload=None, data=None, is_response=False):
+        """Represents a quick reply"""
+        self.payload = payload
         self.data = data
+        self.is_response = is_response
 
-class Thread():
-    def __init__(self, **entries): 
-        self.__dict__.update(entries)
+    def __repr__(self):
+        return self.__unicode__()
 
-class Message():
-    def __init__(self, **entries):
-        self.__dict__.update(entries)
+    def __unicode__(self):
+        return "<{}: payload={!r}>".format(self.__class__.__name__, self.payload)
+
+
+class QuickReplyText(QuickReply):
+    #: Title of the quick reply
+    title = None
+    #: URL of the quick reply image (optional)
+    image_url = None
+    #: Type of the quick reply
+    _type = "text"
+
+    def __init__(self, title=None, image_url=None, **kwargs):
+        """Represents a text quick reply"""
+        super(QuickReplyText, self).__init__(**kwargs)
+        self.title = title
+        self.image_url = image_url
+
+
+class QuickReplyLocation(QuickReply):
+    #: Type of the quick reply
+    _type = "location"
+
+    def __init__(self, **kwargs):
+        """Represents a location quick reply (Doesn't work on mobile)"""
+        super(QuickReplyLocation, self).__init__(**kwargs)
+        self.is_response = False
+
+
+class QuickReplyPhoneNumber(QuickReply):
+    #: URL of the quick reply image (optional)
+    image_url = None
+    #: Type of the quick reply
+    _type = "user_phone_number"
+
+    def __init__(self, image_url=None, **kwargs):
+        """Represents a phone number quick reply (Doesn't work on mobile)"""
+        super(QuickReplyPhoneNumber, self).__init__(**kwargs)
+        self.image_url = image_url
+
+
+class QuickReplyEmail(QuickReply):
+    #: URL of the quick reply image (optional)
+    image_url = None
+    #: Type of the quick reply
+    _type = "user_email"
+
+    def __init__(self, image_url=None, **kwargs):
+        """Represents an email quick reply (Doesn't work on mobile)"""
+        super(QuickReplyEmail, self).__init__(**kwargs)
+        self.image_url = image_url
+
+
+class Poll(object):
+    #: ID of the poll
+    uid = None
+    #: Title of the poll
+    title = None
+    #: List of :class:`PollOption`, can be fetched with :func:`fbchat.Client.fetchPollOptions`
+    options = None
+    #: Options count
+    options_count = None
+
+    def __init__(self, title, options):
+        """Represents a poll"""
+        self.title = title
+        self.options = options
+
+    def __repr__(self):
+        return self.__unicode__()
+
+    def __unicode__(self):
+        return "<Poll ({}): {} options={}>".format(
+            self.uid, repr(self.title), self.options
+        )
+
+
+class PollOption(object):
+    #: ID of the poll option
+    uid = None
+    #: Text of the poll option
+    text = None
+    #: Whether vote when creating or client voted
+    vote = None
+    #: ID of the users who voted for this poll option
+    voters = None
+    #: Votes count
+    votes_count = None
+
+    def __init__(self, text, vote=False):
+        """Represents a poll option"""
+        self.text = text
+        self.vote = vote
+
+    def __repr__(self):
+        return self.__unicode__()
+
+    def __unicode__(self):
+        return "<PollOption ({}): {} voters={}>".format(
+            self.uid, repr(self.text), self.voters
+        )
+
+
+class Plan(object):
+    #: ID of the plan
+    uid = None
+    #: Plan time (unix time stamp), only precise down to the minute
+    time = None
+    #: Plan title
+    title = None
+    #: Plan location name
+    location = None
+    #: Plan location ID
+    location_id = None
+    #: ID of the plan creator
+    author_id = None
+    #: List of the people IDs who will take part in the plan
+    going = None
+    #: List of the people IDs who won't take part in the plan
+    declined = None
+    #: List of the people IDs who are invited to the plan
+    invited = None
+
+    def __init__(self, time, title, location=None, location_id=None):
+        """Represents a plan"""
+        self.time = int(time)
+        self.title = title
+        self.location = location or ""
+        self.location_id = location_id or ""
+        self.author_id = None
+        self.going = []
+        self.declined = []
+        self.invited = []
+
+    def __repr__(self):
+        return self.__unicode__()
+
+    def __unicode__(self):
+        return "<Plan ({}): {} time={}, location={}, location_id={}>".format(
+            self.uid,
+            repr(self.title),
+            self.time,
+            repr(self.location),
+            repr(self.location_id),
+        )
+
+
+class ActiveStatus(object):
+    #: Whether the user is active now
+    active = None
+    #: Timestamp when the user was last active
+    last_active = None
+    #: Whether the user is playing Messenger game now
+    in_game = None
+
+    def __init__(self, active=None, last_active=None, in_game=None):
+        self.active = active
+        self.last_active = last_active
+        self.in_game = in_game
+
+    def __repr__(self):
+        return self.__unicode__()
+
+    def __unicode__(self):
+        return "<ActiveStatus: active={} last_active={} in_game={}>".format(
+            self.active, self.last_active, self.in_game
+        )
+
+
+class Enum(aenum.Enum):
+    """Used internally by fbchat to support enumerations"""
+
+    def __repr__(self):
+        # For documentation:
+        return "{}.{}".format(type(self).__name__, self.name)
+
+
+class ThreadType(Enum):
+    """Used to specify what type of Facebook thread is being used. See :ref:`intro_threads` for more info"""
+
+    USER = 1
+    GROUP = 2
+    ROOM = 2
+    PAGE = 3
+
+
+class ThreadLocation(Enum):
+    """Used to specify where a thread is located (inbox, pending, archived, other)."""
+
+    INBOX = "INBOX"
+    PENDING = "PENDING"
+    ARCHIVED = "ARCHIVED"
+    OTHER = "OTHER"
+
+
+class TypingStatus(Enum):
+    """Used to specify whether the user is typing or has stopped typing"""
+
+    STOPPED = 0
+    TYPING = 1
+
+
+class EmojiSize(Enum):
+    """Used to specify the size of a sent emoji"""
+
+    LARGE = "369239383222810"
+    MEDIUM = "369239343222814"
+    SMALL = "369239263222822"
+
+
+class ThreadColor(Enum):
+    """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"
+
+
+class MessageReaction(Enum):
+    """Used to specify a message reaction"""
+
+    LOVE = "😍"
+    SMILE = "😆"
+    WOW = "😮"
+    SAD = "😢"
+    ANGRY = "😠"
+    YES = "👍"
+    NO = "👎"

fbchat/stickers.py

@@ -1,8 +0,0 @@
-LIKES={
-    'l': '369239383222810',
-    'm': '369239343222814',
-    's': '369239263222822'
-}
-LIKES['large'] = LIKES['l']
-LIKES['medium'] =LIKES['m']
-LIKES['small'] = LIKES['s']

fbchat/utils.py

@@ -1,64 +1,377 @@
+# -*- coding: UTF-8 -*-
+
+from __future__ import unicode_literals
 import re
 import json
 from time import time
 from random import random
+from contextlib import contextmanager
+from mimetypes import guess_type
+from os.path import basename
+import warnings
+import logging
+import requests
+import aenum
+from .models import *
+
+try:
+    from urllib.parse import urlencode, parse_qs, urlparse
+
+    basestring = (str, bytes)
+except ImportError:
+    from urllib import urlencode
+    from urlparse import parse_qs, urlparse
+
+    basestring = basestring
+
+# Python 2's `input` executes the input, whereas `raw_input` just returns the input
+try:
+    input = raw_input
+except NameError:
+    pass
+
+# Log settings
+log = logging.getLogger("client")
+log.setLevel(logging.DEBUG)
+# Creates the console handler
+handler = logging.StreamHandler()
+log.addHandler(handler)
+
+#: Default list of user agents
 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"
+    "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/536.6 (KHTML, like Gecko) Chrome/20.0.1092.0 Safari/536.6",
 ]
-GENDERS = {
-    0: 'unknown',
-    1: 'female_singular',
-    2: 'male_singular',
-    3: 'female_singular_guess',
-    4: 'male_singular_guess',
-    5: 'mixed',
-    6: 'neuter_singular',
-    7: 'unknown_singular',
-    8: 'female_plural',
-    9: 'male_plural',
-    10: 'neuter_plural',
-    11: 'unknown_plural',
+
+LIKES = {
+    "large": EmojiSize.LARGE,
+    "medium": EmojiSize.MEDIUM,
+    "small": EmojiSize.SMALL,
+    "l": EmojiSize.LARGE,
+    "m": EmojiSize.MEDIUM,
+    "s": EmojiSize.SMALL,
 }
 
+
+GENDERS = {
+    # For standard requests
+    0: "unknown",
+    1: "female_singular",
+    2: "male_singular",
+    3: "female_singular_guess",
+    4: "male_singular_guess",
+    5: "mixed",
+    6: "neuter_singular",
+    7: "unknown_singular",
+    8: "female_plural",
+    9: "male_plural",
+    10: "neuter_plural",
+    11: "unknown_plural",
+    # For graphql requests
+    "UNKNOWN": "unknown",
+    "FEMALE": "female_singular",
+    "MALE": "male_singular",
+    # '': 'female_singular_guess',
+    # '': 'male_singular_guess',
+    # '': 'mixed',
+    "NEUTER": "neuter_singular",
+    # '': 'unknown_singular',
+    # '': 'female_plural',
+    # '': 'male_plural',
+    # '': 'neuter_plural',
+    # '': 'unknown_plural',
+}
+
+
+class ReqUrl(object):
+    """A class containing all urls used by `fbchat`"""
+
+    SEARCH = "https://www.facebook.com/ajax/typeahead/search.php"
+    LOGIN = "https://m.facebook.com/login.php?login_attempt=1"
+    SEND = "https://www.facebook.com/messaging/send/"
+    UNREAD_THREADS = "https://www.facebook.com/ajax/mercury/unread_threads.php"
+    UNSEEN_THREADS = "https://www.facebook.com/mercury/unseen_thread_ids/"
+    THREADS = "https://www.facebook.com/ajax/mercury/threadlist_info.php"
+    MOVE_THREAD = "https://www.facebook.com/ajax/mercury/move_thread.php"
+    ARCHIVED_STATUS = (
+        "https://www.facebook.com/ajax/mercury/change_archived_status.php?dpr=1"
+    )
+    PINNED_STATUS = (
+        "https://www.facebook.com/ajax/mercury/change_pinned_status.php?dpr=1"
+    )
+    MESSAGES = "https://www.facebook.com/ajax/mercury/thread_info.php"
+    READ_STATUS = "https://www.facebook.com/ajax/mercury/change_read_status.php"
+    DELIVERED = "https://www.facebook.com/ajax/mercury/delivery_receipts.php"
+    MARK_SEEN = "https://www.facebook.com/ajax/mercury/mark_seen.php"
+    BASE = "https://www.facebook.com"
+    MOBILE = "https://m.facebook.com/"
+    STICKY = "https://0-edge-chat.facebook.com/pull"
+    PING = "https://0-edge-chat.facebook.com/active_ping"
+    UPLOAD = "https://upload.facebook.com/ajax/mercury/upload.php"
+    INFO = "https://www.facebook.com/chat/user_info/"
+    CONNECT = "https://www.facebook.com/ajax/add_friend/action.php?dpr=1"
+    REMOVE_USER = "https://www.facebook.com/chat/remove_participants/"
+    LOGOUT = "https://www.facebook.com/logout.php"
+    ALL_USERS = "https://www.facebook.com/chat/user_info_all"
+    SAVE_DEVICE = "https://m.facebook.com/login/save-device/cancel/"
+    CHECKPOINT = "https://m.facebook.com/login/checkpoint/"
+    THREAD_COLOR = "https://www.facebook.com/messaging/save_thread_color/?source=thread_settings&dpr=1"
+    THREAD_NICKNAME = "https://www.facebook.com/messaging/save_thread_nickname/?source=thread_settings&dpr=1"
+    THREAD_EMOJI = "https://www.facebook.com/messaging/save_thread_emoji/?source=thread_settings&dpr=1"
+    THREAD_IMAGE = "https://www.facebook.com/messaging/set_thread_image/?dpr=1"
+    THREAD_NAME = "https://www.facebook.com/messaging/set_thread_name/?dpr=1"
+    MESSAGE_REACTION = "https://www.facebook.com/webgraphql/mutation"
+    TYPING = "https://www.facebook.com/ajax/messaging/typ.php"
+    GRAPHQL = "https://www.facebook.com/api/graphqlbatch/"
+    ATTACHMENT_PHOTO = "https://www.facebook.com/mercury/attachments/photo/"
+    PLAN_CREATE = "https://www.facebook.com/ajax/eventreminder/create"
+    PLAN_INFO = "https://www.facebook.com/ajax/eventreminder"
+    PLAN_CHANGE = "https://www.facebook.com/ajax/eventreminder/submit"
+    PLAN_PARTICIPATION = "https://www.facebook.com/ajax/eventreminder/rsvp"
+    MODERN_SETTINGS_MENU = "https://www.facebook.com/bluebar/modern_settings_menu/"
+    REMOVE_FRIEND = "https://m.facebook.com/a/removefriend.php"
+    BLOCK_USER = "https://www.facebook.com/messaging/block_messages/?dpr=1"
+    UNBLOCK_USER = "https://www.facebook.com/messaging/unblock_messages/?dpr=1"
+    SAVE_ADMINS = "https://www.facebook.com/messaging/save_admins/?dpr=1"
+    APPROVAL_MODE = "https://www.facebook.com/messaging/set_approval_mode/?dpr=1"
+    CREATE_GROUP = "https://m.facebook.com/messages/send/?icm=1"
+    DELETE_THREAD = "https://www.facebook.com/ajax/mercury/delete_thread.php?dpr=1"
+    DELETE_MESSAGES = "https://www.facebook.com/ajax/mercury/delete_messages.php?dpr=1"
+    MUTE_THREAD = "https://www.facebook.com/ajax/mercury/change_mute_thread.php?dpr=1"
+    MUTE_REACTIONS = (
+        "https://www.facebook.com/ajax/mercury/change_reactions_mute_thread/?dpr=1"
+    )
+    MUTE_MENTIONS = (
+        "https://www.facebook.com/ajax/mercury/change_mentions_mute_thread/?dpr=1"
+    )
+    CREATE_POLL = "https://www.facebook.com/messaging/group_polling/create_poll/?dpr=1"
+    UPDATE_VOTE = "https://www.facebook.com/messaging/group_polling/update_vote/?dpr=1"
+    GET_POLL_OPTIONS = "https://www.facebook.com/ajax/mercury/get_poll_options"
+    SEARCH_MESSAGES = "https://www.facebook.com/ajax/mercury/search_snippets.php?dpr=1"
+    MARK_SPAM = "https://www.facebook.com/ajax/mercury/mark_spam.php?dpr=1"
+    UNSEND = "https://www.facebook.com/messaging/unsend_message/?dpr=1"
+
+    pull_channel = 0
+
+    def change_pull_channel(self, channel=None):
+        if channel is None:
+            self.pull_channel = (self.pull_channel + 1) % 5  # Pull channel will be 0-4
+        else:
+            self.pull_channel = channel
+        self.STICKY = "https://{}-edge-chat.facebook.com/pull".format(self.pull_channel)
+        self.PING = "https://{}-edge-chat.facebook.com/active_ping".format(
+            self.pull_channel
+        )
+
+
+facebookEncoding = "UTF-8"
+
+
 def now():
-    return int(time()*1000)
+    return int(time() * 1000)
+
 
 def strip_to_json(text):
-    return text[text.index('{'):]
+    try:
+        return text[text.index("{") :]
+    except ValueError:
+        raise FBchatException("No JSON object found: {!r}".format(text))
 
-def get_json(text):
-    return json.loads(strip_to_json(text))
 
-def digit_to_char(digit):
+def get_decoded_r(r):
+    return get_decoded(r._content)
+
+
+def get_decoded(content):
+    return content.decode(facebookEncoding)
+
+
+def parse_json(content):
+    return json.loads(content)
+
+
+def get_json(r):
+    return json.loads(strip_to_json(get_decoded_r(r)))
+
+
+def digitToChar(digit):
     if digit < 10:
         return str(digit)
-    return chr(ord('a') + digit - 10)
+    return chr(ord("a") + digit - 10)
 
-def str_base(number,base):
+
+def str_base(number, base):
     if number < 0:
-        return '-' + str_base(-number, base)
+        return "-" + str_base(-number, base)
     (d, m) = divmod(number, base)
     if d > 0:
-        return str_base(d, base) + digit_to_char(m)
-    return digit_to_char(m)
+        return str_base(d, base) + digitToChar(m)
+    return digitToChar(m)
+
 
 def generateMessageID(client_id=None):
     k = now()
     l = int(random() * 4294967295)
-    return ("<%s:%s-%s@mail.projektitan.com>" % (k, l, client_id));
+    return "<{}:{}-{}@mail.projektitan.com>".format(k, l, client_id)
+
 
 def getSignatureID():
     return hex(int(random() * 2147483648))
 
-def generateOfflineThreadingID() :
-    ret = now()
-    value = int(random() * 4294967295);
-    string = ("0000000000000000000000" + bin(value))[-22:]
-    msgs = bin(ret) + string
-    return str(int(msgs,2))
 
+def generateOfflineThreadingID():
+    ret = now()
+    value = int(random() * 4294967295)
+    string = ("0000000000000000000000" + format(value, "b"))[-22:]
+    msgs = format(ret, "b") + string
+    return str(int(msgs, 2))
+
+
+def check_json(j):
+    if j.get("error") is None:
+        return
+    if "errorDescription" in j:
+        # 'errorDescription' is in the users own language!
+        raise FBchatFacebookError(
+            "Error #{} when sending request: {}".format(
+                j["error"], j["errorDescription"]
+            ),
+            fb_error_code=j["error"],
+            fb_error_message=j["errorDescription"],
+        )
+    elif "debug_info" in j["error"] and "code" in j["error"]:
+        raise FBchatFacebookError(
+            "Error #{} when sending request: {}".format(
+                j["error"]["code"], repr(j["error"]["debug_info"])
+            ),
+            fb_error_code=j["error"]["code"],
+            fb_error_message=j["error"]["debug_info"],
+        )
+    else:
+        raise FBchatFacebookError(
+            "Error {} when sending request".format(j["error"]), fb_error_code=j["error"]
+        )
+
+
+def check_request(r, as_json=True):
+    if not r.ok:
+        raise FBchatFacebookError(
+            "Error when sending request: Got {} response".format(r.status_code),
+            request_status_code=r.status_code,
+        )
+
+    content = get_decoded_r(r)
+
+    if content is None or len(content) == 0:
+        raise FBchatFacebookError("Error when sending request: Got empty response")
+
+    if as_json:
+        content = strip_to_json(content)
+        try:
+            j = json.loads(content)
+        except ValueError:
+            raise FBchatFacebookError("Error while parsing JSON: {!r}".format(content))
+        check_json(j)
+        log.debug(j)
+        return j
+    else:
+        return content
+
+
+def get_jsmods_require(j, index):
+    if j.get("jsmods") and j["jsmods"].get("require"):
+        try:
+            return j["jsmods"]["require"][0][index][0]
+        except (KeyError, IndexError) as e:
+            log.warning(
+                "Error when getting jsmods_require: {}. Facebook might have changed protocol".format(
+                    j
+                )
+            )
+    return None
+
+
+def get_emojisize_from_tags(tags):
+    if tags is None:
+        return None
+    tmp = [tag for tag in tags if tag.startswith("hot_emoji_size:")]
+    if len(tmp) > 0:
+        try:
+            return LIKES[tmp[0].split(":")[1]]
+        except (KeyError, IndexError):
+            log.exception(
+                "Could not determine emoji size from {} - {}".format(tags, tmp)
+            )
+    return None
+
+
+def require_list(list_):
+    if isinstance(list_, list):
+        return set(list_)
+    else:
+        return set([list_])
+
+
+def mimetype_to_key(mimetype):
+    if not mimetype:
+        return "file_id"
+    if mimetype == "image/gif":
+        return "gif_id"
+    x = mimetype.split("/")
+    if x[0] in ["video", "image", "audio"]:
+        return "%s_id" % x[0]
+    return "file_id"
+
+
+def get_files_from_urls(file_urls):
+    files = []
+    for file_url in file_urls:
+        r = requests.get(file_url)
+        # We could possibly use r.headers.get('Content-Disposition'), see
+        # https://stackoverflow.com/a/37060758
+        files.append(
+            (
+                basename(file_url),
+                r.content,
+                r.headers.get("Content-Type") or guess_type(file_url)[0],
+            )
+        )
+    return files
+
+
+@contextmanager
+def get_files_from_paths(filenames):
+    files = []
+    for filename in filenames:
+        files.append(
+            (basename(filename), open(filename, "rb"), guess_type(filename)[0])
+        )
+    yield files
+    for fn, fp, ft in files:
+        fp.close()
+
+
+def enum_extend_if_invalid(enumeration, value):
+    try:
+        return enumeration(value)
+    except ValueError:
+        log.warning(
+            "Failed parsing {.__name__}({!r}). Extending enum.".format(
+                enumeration, value
+            )
+        )
+        aenum.extend_enum(enumeration, "UNKNOWN_{}".format(value).upper(), value)
+        return enumeration(value)
+
+
+def get_url_parameters(url, *args):
+    params = parse_qs(urlparse(url).query)
+    return [params[arg][0] for arg in args if params.get(arg)]
+
+
+def get_url_parameter(url, param):
+    return get_url_parameters(url, param)[0]

pyproject.toml

@@ -0,0 +1,64 @@
+[tool.black]
+line-length = 88
+exclude = '''
+/(
+    \.git
+  | \.pytest_cache
+  | build
+  | dist
+  | venv
+)/
+'''
+
+[build-system]
+requires = ["flit"]
+build-backend = "flit.buildapi"
+
+[tool.flit.metadata]
+module = "fbchat"
+author = "Taehoon Kim"
+author-email = "carpedm20@gmail.com"
+maintainer = "Mads Marquart"
+maintainer-email = "madsmtm@gmail.com"
+home-page = "https://github.com/carpedm20/fbchat/"
+requires = [
+    "aenum",
+    "requests",
+    "beautifulsoup4",
+]
+description-file = "README.rst"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Natural Language :: English",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 2.7",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.4",
+    "Programming Language :: Python :: 3.5",
+    "Programming Language :: Python :: 3.6",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Topic :: Communications :: Chat",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, <4.0"
+keywords = "Facebook FB Messenger Library Chat Api Bot"
+license = "BSD 3-Clause"
+
+[tool.flit.metadata.urls]
+Documentation = "https://fbchat.readthedocs.io/"
+Repository = "https://github.com/carpedm20/fbchat/"
+
+[tool.flit.metadata.requires-extra]
+test = [
+    "pytest~=4.0",
+    "six",
+]

pytest.ini

@@ -0,0 +1,6 @@
+[pytest]
+xfail_strict=true
+markers =
+    offline: Offline tests, aka. tests that can be executed without the need of a client
+    expensive: Expensive tests, which should be executed sparingly
+addopts = -m "not expensive"

setup.py

@@ -1,78 +0,0 @@
-#!/usr/bin/env python
-
-
-"""
-Setup script for fbchat
-"""
-
-
-import os
-try:
-    from setuptools import setup
-except ImportError:
-    from distutils.core import setup
-
-
-with open('README.rst') as f:
-    readme_content = f.read().strip()
-
-
-version = None
-author = None
-email = None
-source = None
-with open(os.path.join('fbchat', '__init__.py')) as f:
-    for line in f:
-        if line.strip().startswith('__version__'):
-            version = line.split('=')[1].strip().replace('"', '').replace("'", '')
-        elif line.strip().startswith('__author__'):
-            author = line.split('=')[1].strip().replace('"', '').replace("'", '')
-        elif line.strip().startswith('__email__'):
-            email = line.split('=')[1].strip().replace('"', '').replace("'", '')
-        elif line.strip().startswith('__source__'):
-            source = line.split('=')[1].strip().replace('"', '').replace("'", '')
-        elif None not in (version, author, email, source):
-            break
-
-setup(
-    name='fbchat',
-    author=author,
-    author_email=email,
-    license='BSD License',
-    keywords=["facebook chat fbchat"],
-    description="Facebook Chat (Messenger) for Python",
-    long_description=readme_content,
-    classifiers=[
-        'Development Status :: 2 - Pre-Alpha',
-        'Intended Audience :: Developers',
-        'Intended Audience :: Developers',
-        'Intended Audience :: Information Technology',
-        'License :: OSI Approved :: BSD License',
-        'License :: OSI Approved :: BSD License',
-        'Operating System :: OS Independent',
-        'Programming Language :: Python :: 2.6',
-        'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3.2',
-        'Programming Language :: Python :: 3.3',
-        'Programming Language :: Python :: 3.3',
-        'Programming Language :: Python :: 3.4',
-        'Programming Language :: Python :: 3.5',
-        'Programming Language :: Python :: Implementation :: CPython',
-        'Programming Language :: Python :: Implementation :: PyPy',
-        'Programming Language :: Python',
-        'Topic :: Software Development :: Libraries :: Python Modules',
-        'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
-        'Topic :: Communications :: Chat',
-    ],
-    include_package_data=True,
-    packages=['fbchat'],
-    install_requires=[
-        'requests',
-        'lxml',
-        'beautifulsoup4'
-    ],
-    url=source,
-    version=version,
-    zip_safe=True,
-)

tests.py

@@ -1,168 +0,0 @@
-#!/usr/bin/env python
-
-import logging
-import fbchat
-import getpass
-import unittest
-import sys
-from os import path
-
-# Disable logging
-logging.basicConfig(level=100)
-fbchat.log.setLevel(100)
-
-"""
-
-Tests for fbchat
-~~~~~~~~~~~~~~~~
-
-To use these tests, put:
-- email
-- password
-- a group_uid
-- a user_uid (the user will be kicked from the group and then added again)
-(seperated these by a newline) in a file called `tests.data`, or type them manually in the terminal prompts
-
-Please remember to test both python v. 2.7 and python v. 3.6!
-
-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 commandline
-
-"""
-
-class TestFbchat(unittest.TestCase):
-    def test_login_functions(self):
-        self.assertTrue(client.is_logged_in())
-        
-        client.logout()
-        
-        self.assertFalse(client.is_logged_in())
-        
-        with self.assertRaises(Exception):
-            client.login("not@email.com", "not_password", max_retries=1)
-        
-        client.login(email, password)
-        
-        self.assertTrue(client.is_logged_in())
-
-    def test_sessions(self):
-        global client
-        session_cookies = client.getSession()
-        client = fbchat.Client(email, password, session_cookies=session_cookies)
-        
-        self.assertTrue(client.is_logged_in())
-
-    def test_setDefaultRecipient(self):
-        client.setDefaultRecipient(client.uid, is_user=True)
-        self.assertTrue(client.send(message="test_default_recipient"))
-
-    def test_getAllUsers(self):
-        users = client.getAllUsers()
-        self.assertGreater(len(users), 0)
-
-    def test_getUsers(self):
-        users = client.getUsers("Mark Zuckerberg")
-        self.assertGreater(len(users), 0)
-        
-        u = users[0]
-        
-        # Test if values are set correctly
-        self.assertIsInstance(u.uid, int)
-        self.assertEquals(u.type, 'user')
-        self.assertEquals(u.photo[:4], 'http')
-        self.assertEquals(u.url[:4], 'http')
-        self.assertEquals(u.name, 'Mark Zuckerberg')
-        self.assertGreater(u.score, 0)
-    
-    def test_send_likes(self):
-        self.assertTrue(client.send(client.uid, like='s'))
-        self.assertTrue(client.send(client.uid, like='m'))
-        self.assertTrue(client.send(client.uid, like='l'))
-        self.assertTrue(client.send(group_uid, like='s', is_user=False))
-        self.assertTrue(client.send(group_uid, like='m', is_user=False))
-        self.assertTrue(client.send(group_uid, like='l', is_user=False))
-    
-    def test_send(self):
-        self.assertTrue(client.send(client.uid, message='test_send_user'))
-        self.assertTrue(client.send(group_uid, message='test_send_group', is_user=False))
-    
-    def test_send_images(self):
-        image_url = 'https://cdn4.iconfinder.com/data/icons/ionicons/512/icon-image-128.png'
-        image_local_url = path.join(path.dirname(__file__), 'test_image.png')
-        self.assertTrue(client.sendRemoteImage(client.uid, message='test_send_user_images_remote', image=image_url))
-        self.assertTrue(client.sendLocalImage(client.uid, message='test_send_user_images_local', image=image_local_url))
-        self.assertTrue(client.sendRemoteImage(group_uid, message='test_send_group_images_remote', is_user=False, image=image_url))
-        self.assertTrue(client.sendLocalImage(group_uid, message='test_send_group_images_local', is_user=False, image=image_local_url))
-    
-    def test_getThreadInfo(self):
-        info = client.getThreadInfo(client.uid, last_n=1)
-        self.assertEquals(info[0].author, 'fbid:' + str(client.uid))
-        client.send(group_uid, message='test_getThreadInfo', is_user=False)
-        info = client.getThreadInfo(group_uid, last_n=1, is_user=False)
-        self.assertEquals(info[0].author, 'fbid:' + str(client.uid))
-        self.assertEquals(info[0].body, 'test_getThreadInfo')
-
-    def test_markAs(self):
-        # To be implemented (requires some form of manual watching)
-        pass
-
-    def test_listen(self):
-        client.do_one_listen()
-
-    def test_getUserInfo(self):
-        info = client.getUserInfo(4)
-        self.assertEquals(info['name'], 'Mark Zuckerberg')
-    
-    def test_remove_add_from_chat(self):
-        self.assertTrue(client.remove_user_from_chat(group_uid, user_uid))
-        self.assertTrue(client.add_users_to_chat(group_uid, user_uid))
-    
-    def test_changeThreadTitle(self):
-        self.assertTrue(client.changeThreadTitle(group_uid, 'test_changeThreadTitle'))
-
-
-def start_test(param_client, param_group_uid, param_user_uid, tests=[]):
-    global client
-    global group_uid
-    global user_uid
-    
-    client = param_client
-    group_uid = param_group_uid
-    user_uid = param_user_uid
-    
-    if len(tests) == 0:
-        suite = unittest.TestLoader().loadTestsFromTestCase(TestFbchat)
-    else:
-        suite = unittest.TestSuite(map(TestFbchat, tests))
-    print ('Starting test(s)')
-    unittest.TextTestRunner(verbosity=2).run(suite)
-
-
-
-if __name__ == '__main__':
-    # Python 3 does not use raw_input, whereas Python 2 does
-    try:
-        input = raw_input
-    except Exception as e:
-        pass
-
-    try:
-        with open(path.join(path.dirname(__file__), 'tests.data'), 'r') as f:
-            content = f.readlines()
-        content = [x.strip() for x in content if len(x.strip()) != 0]
-        email = content[0]
-        password = content[1]
-        group_uid = content[2]
-        user_uid = content[3]
-    except (IOError, IndexError) as e:
-        email = input('Email: ')
-        password = getpass.getpass()
-        group_uid = input('Please enter a group uid (To test group functionality): ')
-        user_uid = input('Please enter a user uid (To test kicking/adding functionality): ')
-
-    print ('Logging in')
-    client = fbchat.Client(email, password)
-    
-    # Warning! Taking user input directly like this could be dangerous! Use only for testing purposes!
-    start_test(client, group_uid, user_uid, sys.argv[1:])
-

tests/conftest.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import pytest
+import json
+
+from utils import *
+from contextlib import contextmanager
+from fbchat.models import ThreadType, Message, Mention
+
+
+@pytest.fixture(scope="session")
+def user(client2):
+    return {"id": client2.uid, "type": ThreadType.USER}
+
+
+@pytest.fixture(scope="session")
+def group(pytestconfig):
+    return {
+        "id": load_variable("group_id", pytestconfig.cache),
+        "type": ThreadType.GROUP,
+    }
+
+
+@pytest.fixture(
+    scope="session",
+    params=["user", "group", pytest.param("none", marks=[pytest.mark.xfail()])],
+)
+def thread(request, user, group):
+    return {
+        "user": user,
+        "group": group,
+        "none": {"id": "0", "type": ThreadType.GROUP},
+    }[request.param]
+
+
+@pytest.fixture(scope="session")
+def client1(pytestconfig):
+    with load_client(1, pytestconfig.cache) as c:
+        yield c
+
+
+@pytest.fixture(scope="session")
+def client2(pytestconfig):
+    with load_client(2, pytestconfig.cache) as c:
+        yield c
+
+
+@pytest.fixture(scope="module")
+def client(client1, thread):
+    client1.setDefaultThread(thread["id"], thread["type"])
+    yield client1
+    client1.resetDefaultThread()
+
+
+@pytest.fixture(scope="session", params=["client1", "client2"])
+def client_all(request, client1, client2):
+    return client1 if request.param == "client1" else client2
+
+
+@pytest.fixture(scope="session")
+def catch_event(client2):
+    t = ClientThread(client2)
+    t.start()
+
+    @contextmanager
+    def inner(method_name):
+        caught = CaughtValue()
+        old_method = getattr(client2, method_name)
+
+        # Will be called by the other thread
+        def catch_value(*args, **kwargs):
+            old_method(*args, **kwargs)
+            # Make sure the `set` is only called once
+            if not caught.is_set():
+                caught.set(kwargs)
+
+        setattr(client2, method_name, catch_value)
+        yield caught
+        caught.wait()
+        if not caught.is_set():
+            raise ValueError("The value could not be caught")
+        setattr(client2, method_name, old_method)
+
+    yield inner
+
+    t.should_stop.set()
+
+    try:
+        # Make the client send a messages to itself, so the blocking pull request will return
+        # This is probably not safe, since the client is making two requests simultaneously
+        client2.sendMessage(random_hex(), client2.uid)
+    finally:
+        t.join()
+
+
+@pytest.fixture(scope="module")
+def compare(client, thread):
+    def inner(caught_event, **kwargs):
+        d = {
+            "author_id": client.uid,
+            "thread_id": client.uid
+            if thread["type"] == ThreadType.USER
+            else thread["id"],
+            "thread_type": thread["type"],
+        }
+        d.update(kwargs)
+        return subset(caught_event.res, **d)
+
+    return inner
+
+
+@pytest.fixture(params=["me", "other", "me other"])
+def message_with_mentions(request, client, client2, group):
+    text = "Hi there ["
+    mentions = []
+    if "me" in request.param:
+        mentions.append(Mention(thread_id=client.uid, offset=len(text), length=2))
+        text += "me, "
+    if "other" in request.param:
+        mentions.append(Mention(thread_id=client2.uid, offset=len(text), length=5))
+        text += "other, "
+    # Unused, because Facebook don't properly support sending mentions with groups as targets
+    if "group" in request.param:
+        mentions.append(Mention(thread_id=group["id"], offset=len(text), length=5))
+        text += "group, "
+    text += "nothing]"
+    return Message(text, mentions=mentions)

tests/resources/file.json

@@ -0,0 +1,4 @@
+{
+    "some": "data",
+    "in": "here"
+}

tests/resources/file.txt

@@ -0,0 +1 @@
+This is just a text file

tests/test_base.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import pytest
+import py_compile
+
+from glob import glob
+from os import path, environ
+from fbchat import Client
+from fbchat.models import FBchatUserError, Message
+
+
+@pytest.mark.offline
+def test_examples():
+    # Compiles the examples, to check for syntax errors
+    for name in glob(path.join(path.dirname(__file__), "../examples", "*.py")):
+        py_compile.compile(name)
+
+
+@pytest.mark.trylast
+@pytest.mark.expensive
+def test_login(client1):
+    assert client1.isLoggedIn()
+    email = client1.email
+    password = client1.password
+
+    client1.logout()
+
+    assert not client1.isLoggedIn()
+
+    with pytest.raises(FBchatUserError):
+        client1.login("<invalid email>", "<invalid password>", max_tries=1)
+
+    client1.login(email, password)
+
+    assert client1.isLoggedIn()
+
+
+@pytest.mark.trylast
+def test_sessions(client1):
+    session = client1.getSession()
+    Client("no email needed", "no password needed", session_cookies=session)
+    client1.setSession(session)
+    assert client1.isLoggedIn()
+
+
+@pytest.mark.tryfirst
+def test_default_thread(client1, thread):
+    client1.setDefaultThread(thread["id"], thread["type"])
+    assert client1.send(Message(text="Sent to the specified thread"))
+
+    client1.resetDefaultThread()
+    with pytest.raises(ValueError):
+        client1.send(Message(text="Should not be sent"))

tests/test_fetch.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import pytest
+
+from os import path
+from fbchat.models import ThreadType, Message, Mention, EmojiSize, Sticker
+from utils import subset, STICKER_LIST, EMOJI_LIST
+
+
+def test_fetch_all_users(client1):
+    users = client1.fetchAllUsers()
+    assert len(users) > 0
+
+
+def test_fetch_thread_list(client1):
+    threads = client1.fetchThreadList(limit=2)
+    assert len(threads) == 2
+
+
+def test_fetch_threads(client1):
+    threads = client1.fetchThreads(limit=2)
+    assert len(threads) == 2
+
+
+@pytest.mark.parametrize("emoji, emoji_size", EMOJI_LIST)
+def test_fetch_message_emoji(client, emoji, emoji_size):
+    mid = client.sendEmoji(emoji, emoji_size)
+    message, = client.fetchThreadMessages(limit=1)
+
+    assert subset(
+        vars(message), uid=mid, author=client.uid, text=emoji, emoji_size=emoji_size
+    )
+
+
+@pytest.mark.parametrize("emoji, emoji_size", EMOJI_LIST)
+def test_fetch_message_info_emoji(client, thread, emoji, emoji_size):
+    mid = client.sendEmoji(emoji, emoji_size)
+    message = client.fetchMessageInfo(mid, thread_id=thread["id"])
+
+    assert subset(
+        vars(message), uid=mid, author=client.uid, text=emoji, emoji_size=emoji_size
+    )
+
+
+def test_fetch_message_mentions(client, thread, message_with_mentions):
+    mid = client.send(message_with_mentions)
+    message, = client.fetchThreadMessages(limit=1)
+
+    assert subset(
+        vars(message), uid=mid, author=client.uid, text=message_with_mentions.text
+    )
+    # The mentions are not ordered by offset
+    for m in message.mentions:
+        assert vars(m) in [vars(x) for x in message_with_mentions.mentions]
+
+
+def test_fetch_message_info_mentions(client, thread, message_with_mentions):
+    mid = client.send(message_with_mentions)
+    message = client.fetchMessageInfo(mid, thread_id=thread["id"])
+
+    assert subset(
+        vars(message), uid=mid, author=client.uid, text=message_with_mentions.text
+    )
+    # The mentions are not ordered by offset
+    for m in message.mentions:
+        assert vars(m) in [vars(x) for x in message_with_mentions.mentions]
+
+
+@pytest.mark.parametrize("sticker", STICKER_LIST)
+def test_fetch_message_sticker(client, sticker):
+    mid = client.send(Message(sticker=sticker))
+    message, = client.fetchThreadMessages(limit=1)
+
+    assert subset(vars(message), uid=mid, author=client.uid)
+    assert subset(vars(message.sticker), uid=sticker.uid)
+
+
+@pytest.mark.parametrize("sticker", STICKER_LIST)
+def test_fetch_message_info_sticker(client, thread, sticker):
+    mid = client.send(Message(sticker=sticker))
+    message = client.fetchMessageInfo(mid, thread_id=thread["id"])
+
+    assert subset(vars(message), uid=mid, author=client.uid)
+    assert subset(vars(message.sticker), uid=sticker.uid)
+
+
+def test_fetch_info(client1, group):
+    info = client1.fetchUserInfo("4")["4"]
+    assert info.name == "Mark Zuckerberg"
+
+    info = client1.fetchGroupInfo(group["id"])[group["id"]]
+    assert info.type == ThreadType.GROUP
+
+
+def test_fetch_image_url(client):
+    client.sendLocalFiles([path.join(path.dirname(__file__), "resources", "image.png")])
+    message, = client.fetchThreadMessages(limit=1)
+
+    assert client.fetchImageUrl(message.attachments[0].uid)

tests/test_message_management.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import pytest
+
+from fbchat.models import Message, MessageReaction
+from utils import subset
+
+
+def test_set_reaction(client):
+    mid = client.send(Message(text="This message will be reacted to"))
+    client.reactToMessage(mid, MessageReaction.LOVE)
+
+
+def test_delete_messages(client):
+    text1 = "This message will stay"
+    text2 = "This message will be removed"
+    mid1 = client.sendMessage(text1)
+    mid2 = client.sendMessage(text2)
+    client.deleteMessages(mid2)
+    message, = client.fetchThreadMessages(limit=1)
+    assert subset(vars(message), uid=mid1, author=client.uid, text=text1)

tests/test_plans.py

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import pytest
+
+from fbchat.models import Plan, FBchatFacebookError, ThreadType
+from utils import random_hex, subset
+from time import time
+
+
+@pytest.fixture(
+    scope="module",
+    params=[
+        Plan(int(time()) + 100, random_hex()),
+        pytest.param(
+            Plan(int(time()), random_hex()),
+            marks=[pytest.mark.xfail(raises=FBchatFacebookError)],
+        ),
+        pytest.param(Plan(0, None), marks=[pytest.mark.xfail()]),
+    ],
+)
+def plan_data(request, client, user, thread, catch_event, compare):
+    with catch_event("onPlanCreated") as x:
+        client.createPlan(request.param, thread["id"])
+    assert compare(x)
+    assert subset(
+        vars(x.res["plan"]),
+        time=request.param.time,
+        title=request.param.title,
+        author_id=client.uid,
+        going=[client.uid],
+        declined=[],
+    )
+    plan_id = x.res["plan"]
+    assert user["id"] in x.res["plan"].invited
+    request.param.uid = x.res["plan"].uid
+    yield x.res, request.param
+    with catch_event("onPlanDeleted") as x:
+        client.deletePlan(plan_id)
+    assert compare(x)
+
+
+@pytest.mark.tryfirst
+def test_create_delete_plan(plan_data):
+    pass
+
+
+def test_fetch_plan_info(client, catch_event, plan_data):
+    event, plan = plan_data
+    fetched_plan = client.fetchPlanInfo(plan.uid)
+    assert subset(
+        vars(fetched_plan), time=plan.time, title=plan.title, author_id=int(client.uid)
+    )
+
+
+@pytest.mark.parametrize("take_part", [False, True])
+def test_change_plan_participation(
+    client, thread, catch_event, compare, plan_data, take_part
+):
+    event, plan = plan_data
+    with catch_event("onPlanParticipation") as x:
+        client.changePlanParticipation(plan, take_part=take_part)
+    assert compare(x, take_part=take_part)
+    assert subset(
+        vars(x.res["plan"]),
+        time=plan.time,
+        title=plan.title,
+        author_id=client.uid,
+        going=[client.uid] if take_part else [],
+        declined=[client.uid] if not take_part else [],
+    )
+
+
+@pytest.mark.trylast
+def test_edit_plan(client, thread, catch_event, compare, plan_data):
+    event, plan = plan_data
+    new_plan = Plan(plan.time + 100, random_hex())
+    with catch_event("onPlanEdited") as x:
+        client.editPlan(plan, new_plan)
+    assert compare(x)
+    assert subset(
+        vars(x.res["plan"]),
+        time=new_plan.time,
+        title=new_plan.title,
+        author_id=client.uid,
+    )
+
+
+@pytest.mark.trylast
+@pytest.mark.expensive
+def test_on_plan_ended(client, thread, catch_event, compare):
+    with catch_event("onPlanEnded") as x:
+        client.createPlan(Plan(int(time()) + 120, "Wait for ending"))
+        x.wait(180)
+    assert subset(
+        x.res,
+        thread_id=client.uid if thread["type"] == ThreadType.USER else thread["id"],
+        thread_type=thread["type"],
+    )
+
+
+# createPlan(self, plan, thread_id=None)
+# editPlan(self, plan, new_plan)
+# deletePlan(self, plan)
+# changePlanParticipation(self, plan, take_part=True)
+
+# onPlanCreated(self, mid=None, plan=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)
+# onPlanEnded(self, mid=None, plan=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)
+# onPlanEdited(self, mid=None, plan=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)
+# onPlanDeleted(self, mid=None, plan=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)
+# onPlanParticipation(self, mid=None, plan=None, take_part=None, author_id=None, thread_id=None, thread_type=None, ts=None, metadata=None, msg=None)
+
+# fetchPlanInfo(self, plan_id)

tests/test_polls.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import pytest
+
+from fbchat.models import Poll, PollOption, ThreadType
+from utils import random_hex, subset
+
+
+@pytest.fixture(
+    scope="module",
+    params=[
+        Poll(title=random_hex(), options=[]),
+        Poll(
+            title=random_hex(),
+            options=[
+                PollOption(random_hex(), vote=True),
+                PollOption(random_hex(), vote=True),
+            ],
+        ),
+        Poll(
+            title=random_hex(),
+            options=[
+                PollOption(random_hex(), vote=False),
+                PollOption(random_hex(), vote=False),
+            ],
+        ),
+        Poll(
+            title=random_hex(),
+            options=[
+                PollOption(random_hex(), vote=True),
+                PollOption(random_hex(), vote=True),
+                PollOption(random_hex(), vote=False),
+                PollOption(random_hex(), vote=False),
+                PollOption(random_hex()),
+                PollOption(random_hex()),
+            ],
+        ),
+        pytest.param(
+            Poll(title=None, options=[]), marks=[pytest.mark.xfail(raises=ValueError)]
+        ),
+    ],
+)
+def poll_data(request, client1, group, catch_event):
+    with catch_event("onPollCreated") as x:
+        client1.createPoll(request.param, thread_id=group["id"])
+    options = client1.fetchPollOptions(x.res["poll"].uid)
+    return x.res, request.param, options
+
+
+def test_create_poll(client1, group, catch_event, poll_data):
+    event, poll, _ = poll_data
+    assert subset(
+        event,
+        author_id=client1.uid,
+        thread_id=group["id"],
+        thread_type=ThreadType.GROUP,
+    )
+    assert subset(
+        vars(event["poll"]), title=poll.title, options_count=len(poll.options)
+    )
+    for recv_option in event[
+        "poll"
+    ].options:  # The recieved options may not be the full list
+        old_option, = list(filter(lambda o: o.text == recv_option.text, poll.options))
+        voters = [client1.uid] if old_option.vote else []
+        assert subset(
+            vars(recv_option), voters=voters, votes_count=len(voters), vote=False
+        )
+
+
+def test_fetch_poll_options(client1, group, catch_event, poll_data):
+    _, poll, options = poll_data
+    assert len(options) == len(poll.options)
+    for option in options:
+        assert subset(vars(option))
+
+
+@pytest.mark.trylast
+def test_update_poll_vote(client1, group, catch_event, poll_data):
+    event, poll, options = poll_data
+    new_vote_ids = [o.uid for o in options[0 : len(options) : 2] if not o.vote]
+    re_vote_ids = [o.uid for o in options[0 : len(options) : 2] if o.vote]
+    new_options = [random_hex(), random_hex()]
+    with catch_event("onPollVoted") as x:
+        client1.updatePollVote(
+            event["poll"].uid,
+            option_ids=new_vote_ids + re_vote_ids,
+            new_options=new_options,
+        )
+
+    assert subset(
+        x.res,
+        author_id=client1.uid,
+        thread_id=group["id"],
+        thread_type=ThreadType.GROUP,
+    )
+    assert subset(
+        vars(x.res["poll"]), title=poll.title, options_count=len(options + new_options)
+    )
+    for o in new_vote_ids:
+        assert o in x.res["added_options"]
+    assert len(x.res["added_options"]) == len(new_vote_ids) + len(new_options)
+    assert set(x.res["removed_options"]) == set(
+        o.uid for o in options if o.vote and o.uid not in re_vote_ids
+    )

tests/test_search.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+from fbchat.models import ThreadType
+
+
+def test_search_for(client1):
+    users = client1.searchForUsers("Mark Zuckerberg")
+    assert len(users) > 0
+
+    u = users[0]
+
+    assert u.uid == "4"
+    assert u.type == ThreadType.USER
+    assert u.photo[:4] == "http"
+    assert u.url[:4] == "http"
+    assert u.name == "Mark Zuckerberg"

tests/test_send.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import pytest
+
+from os import path
+from fbchat.models import FBchatFacebookError, Message, Mention
+from utils import subset, STICKER_LIST, EMOJI_LIST, TEXT_LIST
+
+
+@pytest.mark.parametrize("text", TEXT_LIST)
+def test_send_text(client, catch_event, compare, text):
+    with catch_event("onMessage") as x:
+        mid = client.sendMessage(text)
+
+    assert compare(x, mid=mid, message=text)
+    assert subset(vars(x.res["message_object"]), uid=mid, author=client.uid, text=text)
+
+
+@pytest.mark.parametrize("emoji, emoji_size", EMOJI_LIST)
+def test_send_emoji(client, catch_event, compare, emoji, emoji_size):
+    with catch_event("onMessage") as x:
+        mid = client.sendEmoji(emoji, emoji_size)
+
+    assert compare(x, mid=mid, message=emoji)
+    assert subset(
+        vars(x.res["message_object"]),
+        uid=mid,
+        author=client.uid,
+        text=emoji,
+        emoji_size=emoji_size,
+    )
+
+
+def test_send_mentions(client, catch_event, compare, message_with_mentions):
+    with catch_event("onMessage") as x:
+        mid = client.send(message_with_mentions)
+
+    assert compare(x, mid=mid, message=message_with_mentions.text)
+    assert subset(
+        vars(x.res["message_object"]),
+        uid=mid,
+        author=client.uid,
+        text=message_with_mentions.text,
+    )
+    # The mentions are not ordered by offset
+    for m in x.res["message_object"].mentions:
+        assert vars(m) in [vars(x) for x in message_with_mentions.mentions]
+
+
+@pytest.mark.parametrize("sticker", STICKER_LIST)
+def test_send_sticker(client, catch_event, compare, sticker):
+    with catch_event("onMessage") as x:
+        mid = client.send(Message(sticker=sticker))
+
+    assert compare(x, mid=mid)
+    assert subset(vars(x.res["message_object"]), uid=mid, author=client.uid)
+    assert subset(vars(x.res["message_object"].sticker), uid=sticker.uid)
+
+
+# Kept for backwards compatibility
+@pytest.mark.parametrize(
+    "method_name, url",
+    [
+        (
+            "sendRemoteImage",
+            "https://github.com/carpedm20/fbchat/raw/master/tests/image.png",
+        ),
+        ("sendLocalImage", path.join(path.dirname(__file__), "resources", "image.png")),
+    ],
+)
+def test_send_images(client, catch_event, compare, method_name, url):
+    text = "An image sent with {}".format(method_name)
+    with catch_event("onMessage") as x:
+        mid = getattr(client, method_name)(url, Message(text))
+
+    assert compare(x, mid=mid, message=text)
+    assert subset(vars(x.res["message_object"]), uid=mid, author=client.uid, text=text)
+    assert x.res["message_object"].attachments[0]
+
+
+def test_send_local_files(client, catch_event, compare):
+    files = [
+        "image.png",
+        "image.jpg",
+        "image.gif",
+        "file.json",
+        "file.txt",
+        "audio.mp3",
+        "video.mp4",
+    ]
+    text = "Files sent locally"
+    with catch_event("onMessage") as x:
+        mid = client.sendLocalFiles(
+            [path.join(path.dirname(__file__), "resources", f) for f in files],
+            message=Message(text),
+        )
+
+    assert compare(x, mid=mid, message=text)
+    assert subset(vars(x.res["message_object"]), uid=mid, author=client.uid, text=text)
+    assert len(x.res["message_object"].attachments) == len(files)
+
+
+# To be changed when merged into master
+def test_send_remote_files(client, catch_event, compare):
+    files = ["image.png", "data.json"]
+    text = "Files sent from remote"
+    with catch_event("onMessage") as x:
+        mid = client.sendRemoteFiles(
+            [
+                "https://github.com/carpedm20/fbchat/raw/master/tests/{}".format(f)
+                for f in files
+            ],
+            message=Message(text),
+        )
+
+    assert compare(x, mid=mid, message=text)
+    assert subset(vars(x.res["message_object"]), uid=mid, author=client.uid, text=text)
+    assert len(x.res["message_object"].attachments) == len(files)
+
+
+@pytest.mark.parametrize("wave_first", [True, False])
+def test_wave(client, wave_first):
+    client.wave(wave_first)

tests/test_tests.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import pytest
+
+
+def test_catch_event(client2, catch_event):
+    mid = "test"
+    with catch_event("onMessage") as x:
+        client2.onMessage(mid=mid)
+    assert x.res["mid"] == mid

tests/test_thread_interraction.py

@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import pytest
+
+from fbchat.models import (
+    Message,
+    ThreadType,
+    FBchatFacebookError,
+    TypingStatus,
+    ThreadColor,
+)
+from utils import random_hex, subset
+from os import path
+
+
+def test_remove_from_and_add_to_group(client1, client2, group, catch_event):
+    # Test both methods, while ensuring that the user gets added to the group
+    try:
+        with catch_event("onPersonRemoved") as x:
+            client1.removeUserFromGroup(client2.uid, group["id"])
+        assert subset(
+            x.res, removed_id=client2.uid, author_id=client1.uid, thread_id=group["id"]
+        )
+    finally:
+        with catch_event("onPeopleAdded") as x:
+            client1.addUsersToGroup(client2.uid, group["id"])
+        assert subset(
+            x.res, added_ids=[client2.uid], author_id=client1.uid, thread_id=group["id"]
+        )
+
+
+def test_remove_from_and_add_admins_to_group(client1, client2, group, catch_event):
+    # Test both methods, while ensuring that the user gets added as group admin
+    try:
+        with catch_event("onAdminRemoved") as x:
+            client1.removeGroupAdmins(client2.uid, group["id"])
+        assert subset(
+            x.res, removed_id=client2.uid, author_id=client1.uid, thread_id=group["id"]
+        )
+    finally:
+        with catch_event("onAdminAdded") as x:
+            client1.addGroupAdmins(client2.uid, group["id"])
+        assert subset(
+            x.res, added_id=client2.uid, author_id=client1.uid, thread_id=group["id"]
+        )
+
+
+def test_change_title(client1, group, catch_event):
+    title = random_hex()
+    with catch_event("onTitleChange") as x:
+        client1.changeThreadTitle(title, group["id"], thread_type=ThreadType.GROUP)
+    assert subset(
+        x.res,
+        author_id=client1.uid,
+        new_title=title,
+        thread_id=group["id"],
+        thread_type=ThreadType.GROUP,
+    )
+
+
+def test_change_nickname(client, client_all, catch_event, compare):
+    nickname = random_hex()
+    with catch_event("onNicknameChange") as x:
+        client.changeNickname(nickname, client_all.uid)
+    assert compare(x, changed_for=client_all.uid, new_nickname=nickname)
+
+
+@pytest.mark.parametrize(
+    "emoji",
+    [
+        "😀",
+        "😂",
+        "😕",
+        "😍",
+        pytest.param("🙃", marks=[pytest.mark.xfail(raises=FBchatFacebookError)]),
+        pytest.param(
+            "not an emoji", marks=[pytest.mark.xfail(raises=FBchatFacebookError)]
+        ),
+    ],
+)
+def test_change_emoji(client, catch_event, compare, emoji):
+    with catch_event("onEmojiChange") as x:
+        client.changeThreadEmoji(emoji)
+    assert compare(x, new_emoji=emoji)
+
+
+def test_change_image_local(client1, group, catch_event):
+    url = path.join(path.dirname(__file__), "resources", "image.png")
+    with catch_event("onImageChange") as x:
+        image_id = client1.changeGroupImageLocal(url, group["id"])
+    assert subset(
+        x.res, new_image=image_id, author_id=client1.uid, thread_id=group["id"]
+    )
+
+
+# To be changed when merged into master
+def test_change_image_remote(client1, group, catch_event):
+    url = "https://github.com/carpedm20/fbchat/raw/master/tests/image.png"
+    with catch_event("onImageChange") as x:
+        image_id = client1.changeGroupImageRemote(url, group["id"])
+    assert subset(
+        x.res, new_image=image_id, author_id=client1.uid, thread_id=group["id"]
+    )
+
+
+@pytest.mark.parametrize(
+    "color",
+    [
+        x
+        if x in [ThreadColor.MESSENGER_BLUE, ThreadColor.PUMPKIN]
+        else pytest.param(x, marks=[pytest.mark.expensive()])
+        for x in ThreadColor
+    ],
+)
+def test_change_color(client, catch_event, compare, color):
+    with catch_event("onColorChange") as x:
+        client.changeThreadColor(color)
+    assert compare(x, new_color=color)
+
+
+@pytest.mark.xfail(raises=FBchatFacebookError, reason="Should fail, but doesn't")
+def test_change_color_invalid(client):
+    class InvalidColor:
+        value = "#0077ff"
+
+    client.changeThreadColor(InvalidColor())
+
+
+@pytest.mark.parametrize("status", TypingStatus)
+def test_typing_status(client, catch_event, compare, status):
+    with catch_event("onTyping") as x:
+        client.setTypingStatus(status)
+    assert compare(x, status=status)
+
+
+@pytest.mark.parametrize("require_admin_approval", [True, False])
+def test_change_approval_mode(client1, group, catch_event, require_admin_approval):
+    with catch_event("onApprovalModeChange") as x:
+        client1.changeGroupApprovalMode(require_admin_approval, group["id"])
+
+    assert subset(
+        x.res,
+        approval_mode=require_admin_approval,
+        author_id=client1.uid,
+        thread_id=group["id"],
+    )
+
+
+@pytest.mark.parametrize("mute_time", [0, 10, 100, 1000, -1])
+def test_mute_thread(client, mute_time):
+    assert client.muteThread(mute_time)
+    assert client.unmuteThread()
+
+
+def test_mute_thread_reactions(client):
+    assert client.muteThreadReactions()
+    assert client.unmuteThreadReactions()
+
+
+def test_mute_thread_mentions(client):
+    assert client.muteThreadMentions()
+    assert client.unmuteThreadMentions()

tests/utils.py

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import unicode_literals
+
+import threading
+import logging
+import six
+import pytest
+
+from os import environ
+from random import randrange
+from contextlib import contextmanager
+from six import viewitems
+from fbchat import Client
+from fbchat.models import ThreadType, EmojiSize, FBchatFacebookError, Sticker
+
+log = logging.getLogger("fbchat.tests").addHandler(logging.NullHandler())
+
+
+EMOJI_LIST = [
+    ("😆", EmojiSize.SMALL),
+    ("😆", EmojiSize.MEDIUM),
+    ("😆", EmojiSize.LARGE),
+    # These fail in `catch_event` because the emoji is made into a sticker
+    # This should be fixed
+    pytest.param(None, EmojiSize.SMALL, marks=[pytest.mark.xfail()]),
+    pytest.param(None, EmojiSize.MEDIUM, marks=[pytest.mark.xfail()]),
+    pytest.param(None, EmojiSize.LARGE, marks=[pytest.mark.xfail()]),
+]
+
+STICKER_LIST = [
+    Sticker("767334476626295"),
+    pytest.param(Sticker("0"), marks=[pytest.mark.xfail(raises=FBchatFacebookError)]),
+    pytest.param(Sticker(None), marks=[pytest.mark.xfail(raises=FBchatFacebookError)]),
+]
+
+TEXT_LIST = [
+    "test_send",
+    "😆",
+    "\\\n\t%?&'\"",
+    "ˁҭʚ¹Ʋջوװ՞ޱɣࠚԹБɑȑңКએ֭ʗыԈٌʼőԈ×௴nચϚࠖణٔє܅Ԇޑط",
+    "a" * 20000,  # Maximum amount of characters you can send
+    pytest.param("a" * 20001, marks=[pytest.mark.xfail(raises=FBchatFacebookError)]),
+    pytest.param(None, marks=[pytest.mark.xfail(raises=FBchatFacebookError)]),
+]
+
+
+class ClientThread(threading.Thread):
+    def __init__(self, client, *args, **kwargs):
+        self.client = client
+        self.should_stop = threading.Event()
+        super(ClientThread, self).__init__(*args, **kwargs)
+
+    def start(self):
+        self.client.startListening()
+        self.client.doOneListen()  # QPrimer, Facebook now knows we're about to start pulling
+        super(ClientThread, self).start()
+
+    def run(self):
+        while not self.should_stop.is_set() and self.client.doOneListen():
+            pass
+
+        self.client.stopListening()
+
+
+if six.PY2:
+    event_class = threading._Event
+else:
+    event_class = threading.Event
+
+
+class CaughtValue(event_class):
+    def set(self, res):
+        self.res = res
+        super(CaughtValue, self).set()
+
+    def wait(self, timeout=3):
+        super(CaughtValue, self).wait(timeout=timeout)
+
+
+def random_hex(length=20):
+    return "{:X}".format(randrange(16 ** length))
+
+
+def subset(a, **b):
+    print(a)
+    print(b)
+    return viewitems(b) <= viewitems(a)
+
+
+def load_variable(name, cache):
+    var = environ.get(name, None)
+    if var is not None:
+        if cache.get(name, None) != var:
+            cache.set(name, var)
+        return var
+
+    var = cache.get(name, None)
+    if var is None:
+        raise ValueError("Variable {!r} neither in environment nor cache".format(name))
+    return var
+
+
+@contextmanager
+def load_client(n, cache):
+    client = Client(
+        load_variable("client{}_email".format(n), cache),
+        load_variable("client{}_password".format(n), cache),
+        user_agent="Mozilla/5.0 (Windows NT 6.3; WOW64; ; NCT50_AAP285C84A1328) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.90 Safari/537.36",
+        session_cookies=cache.get("client{}_session".format(n), None),
+        max_tries=1,
+    )
+    yield client
+    cache.set("client{}_session".format(n), client.getSession())