Version up, thanks to @ekohilas

Updates setup.py for better compatibility with setuptools

docs/intro.rst

@@ -52,12 +52,12 @@ A thread can refer to two things: A Messenger group chat or a single Facebook us
 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 differetiates between these two internally
 
-Searching for group chats and finding their ID is not yet possible with `fbchat`,
+Searching for group chats and finding their ID can be done via. :func:`Client.searchForGroups`,
-but searching for users is possible via. :func:`Client.searchForUsers`. See :ref:`intro_fetching`
+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 though, since you only need to navigate to `<https://www.facebook.com/messages/>`_,
+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:

examples/fetch.py

@@ -12,7 +12,7 @@ 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 `getUserInfo` to fetch a `User` object
+# 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>')
@@ -49,4 +49,16 @@ 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`

fbchat/__init__.py

@@ -17,7 +17,7 @@ from .client import *
 
 
 __copyright__ = 'Copyright 2015 - {} by Taehoon Kim'.format(datetime.now().year)
-__version__ = '1.0.3'
+__version__ = '1.0.25'
 __license__ = 'BSD'
 __author__ = 'Taehoon Kim; Moreels Pieter-Jan; Mads Marquart'
 __email__ = 'carpedm20@gmail.com'

fbchat/graphql.py

@@ -23,6 +23,44 @@ class ConcatJSONDecoder(json.JSONDecoder):
         return objs
 # End shameless copy
 
+def graphql_color_to_enum(color):
+    if color is None:
+        return None
+    if len(color) == 0:
+        return ThreadColor.MESSENGER_BLUE
+    try:
+        return ThreadColor('#{}'.format(color[2:].lower()))
+    except ValueError:
+        raise FBchatException('Could not get ThreadColor from color: {}'.format(color))
+
+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_message(message):
     if message.get('message_sender') is None:
         message['message_sender'] = {}
@@ -40,12 +78,14 @@ def graphql_to_message(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', [])],
         sticker=message.get('sticker'),
-        attachments=message.get('blob_attachments')
+        attachments=message.get('blob_attachments'),
+        extensible_attachment=message.get('extensible_attachment')
     )
 
 def graphql_to_user(user):
     if user.get('profile_picture') is None:
         user['profile_picture'] = {}
+    c_info = get_customization_info(user)
     return User(
         user['id'],
         url=user.get('url'),
@@ -54,18 +94,28 @@ def graphql_to_user(user):
         is_friend=user.get('is_viewer_friend'),
         gender=GENDERS[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')
+        name=user.get('name'),
+        message_count=user.get('messages_count')
     )
 
 def graphql_to_group(group):
     if group.get('image') is None:
         group['image'] = {}
+    c_info = get_customization_info(group)
     return Group(
         group['thread_key']['thread_fbid'],
-        participants=[node['messaging_actor']['id'] for node in group['all_participants']['nodes']],
+        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'),
         photo=group['image'].get('uri'),
-        name=group.get('name')
+        name=group.get('name'),
+        message_count=group.get('messages_count')
     )
 
 def graphql_to_page(page):
@@ -79,7 +129,8 @@ def graphql_to_page(page):
         city=page.get('city').get('name'),
         category=page.get('category_type'),
         photo=page['profile_picture'].get('uri'),
-        name=page.get('name')
+        name=page.get('name'),
+        message_count=page.get('messages_count')
     )
 
 def graphql_queries_to_json(*queries):
@@ -92,7 +143,11 @@ def graphql_queries_to_json(*queries):
     return json.dumps(rtn)
 
 def graphql_response_to_json(content):
-    j = json.loads(content, cls=ConcatJSONDecoder)
+    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:
@@ -125,7 +180,7 @@ class GraphQL(object):
                 'query_params': params
             }
         else:
-            raise Exception('A query or doc_id must be specified')
+            raise FBchatUserError('A query or doc_id must be specified')
 
 
     FRAGMENT_USER = """
@@ -160,6 +215,14 @@ class GraphQL(object):
                     id
                 }
             }
+        },
+        customization_info {
+            participant_customizations {
+                participant_id,
+                nickname
+            },
+            outgoing_bubble_color,
+            emoji
         }
     }
     """

fbchat/models.py

@@ -4,6 +4,26 @@ from __future__ import unicode_literals
 import enum
 
 
+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 = str
+    #: The error message that Facebook returned (In the user's own language)
+    fb_error_message = str
+    #: The status code that was sent in the http response (eg. 404) (Usually only set if not successful, aka. not 200)
+    request_status_code = int
+    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 = str
@@ -13,13 +33,18 @@ class Thread(object):
     photo = str
     #: The name of the thread
     name = str
-
+    #: Timestamp of last message
-    def __init__(self, _type, uid, photo=None, name=None):
+    last_message_timestamp = str
+    #: Number of messages in the thread
+    message_count = int
+    def __init__(self, _type, uid, photo=None, name=None, last_message_timestamp=None, message_count=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
 
     def __repr__(self):
         return self.__unicode__()
@@ -41,8 +66,16 @@ class User(Thread):
     gender = str
     #: From 0 to 1. How close the client is to the user
     affinity = float
+    #: The user's nickname
+    nickname = str
+    #: The clients nickname, as seen by the user
+    own_nickname = str
+    #: A :class:`ThreadColor`. The message color
+    color = None
+    #: The default emoji
+    emoji = str
 
-    def __init__(self, uid, url=None, first_name=None, last_name=None, is_friend=None, gender=None, affinity=None, **kwargs):
+    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
@@ -51,16 +84,29 @@ class User(Thread):
         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):
-    #: List of the group thread's participant user IDs
+    #: Unique list (set) of the group thread's participant user IDs
-    participants = list
+    participants = set
+    #: Dict, containing user nicknames mapped to their IDs
+    nicknames = dict
+    #: A :class:`ThreadColor`. The groups's message color
+    color = None
+    #: The groups's default emoji
+    emoji = str
 
-    def __init__(self, uid, participants=[], **kwargs):
+    def __init__(self, uid, participants=set(), nicknames=[], color=None, emoji=None, **kwargs):
         """Represents a Facebook group. Inherits `Thread`"""
         super(Group, self).__init__(ThreadType.GROUP, uid, **kwargs)
         self.participants = participants
+        self.nicknames = nicknames
+        self.color = color
+        self.emoji = emoji
 
 
 class Page(Thread):
@@ -104,8 +150,10 @@ class Message(object):
     sticker = str
     #: A list of attachments
     attachments = list
+    #: An extensible attachment, e.g. share object
+    extensible_attachment = dict
 
-    def __init__(self, uid, author=None, timestamp=None, is_read=None, reactions=[], text=None, mentions=[], sticker=None, attachments=[]):
+    def __init__(self, uid, author=None, timestamp=None, is_read=None, reactions=[], text=None, mentions=[], sticker=None, attachments=[], extensible_attachment={}):
         """Represents a Facebook message"""
         self.uid = uid
         self.author = author
@@ -116,6 +164,7 @@ class Message(object):
         self.mentions = mentions
         self.sticker = sticker
         self.attachments = attachments
+        self.extensible_attachment = extensible_attachment
 
 
 class Mention(object):
@@ -144,6 +193,13 @@ class ThreadType(Enum):
     GROUP = 2
     PAGE = 3
 
+class ThreadLocation(Enum):
+    """Used to specify where a thread is located (inbox, pending, archived, other)."""
+    INBOX = 'inbox'
+    PENDING = 'pending'
+    ARCHIVED = 'action:archived'
+    OTHER = 'other'
+
 class TypingStatus(Enum):
     """Used to specify whether the user is typing or has stopped typing"""
     STOPPED = 0

fbchat/utils.py

@@ -32,12 +32,6 @@ USER_AGENTS = [
     "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/536.6 (KHTML, like Gecko) Chrome/20.0.1092.0 Safari/536.6"
 ]
 
-TYPES = {
-    'Page': ThreadType.PAGE,
-    'User': ThreadType.USER,
-    'Group': ThreadType.GROUP
-}
-
 GENDERS = {
     # For standard requests
     0: 'unknown',
@@ -54,7 +48,7 @@ GENDERS = {
     11: 'unknown_plural',
 
     # For graphql requests
-    #'': 'unknown',
+    'UNKNOWN': 'unknown',
     'FEMALE': 'female_singular',
     'MALE': 'male_singular',
     #'': 'female_singular_guess',
@@ -99,6 +93,16 @@ class ReqUrl(object):
     TYPING = "https://www.facebook.com/ajax/messaging/typ.php"
     GRAPHQL = "https://www.facebook.com/api/graphqlbatch/"
 
+    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'
 
@@ -109,7 +113,7 @@ def strip_to_json(text):
     try:
         return text[text.index('{'):]
     except ValueError:
-        raise Exception('No JSON object found: {}, {}'.format(repr(text), text.index('{')))
+        raise FBchatException('No JSON object found: {}, {}'.format(repr(text), text.index('{')))
 
 def get_decoded_r(r):
     return get_decoded(r._content)
@@ -149,30 +153,31 @@ def generateOfflineThreadingID():
     return str(int(msgs, 2))
 
 def check_json(j):
-    if 'error' in j and j['error'] is not None:
+    if j.get('error') is None:
-        if 'errorDescription' in j:
+        return
-            # 'errorDescription' is in the users own language!
+    if 'errorDescription' in j:
-            raise Exception('Error #{} when sending request: {}'.format(j['error'], j['errorDescription']))
+        # 'errorDescription' is in the users own language!
-        elif 'debug_info' in j['error']:
+        raise FBchatFacebookError('Error #{} when sending request: {}'.format(j['error'], j['errorDescription']), fb_error_code=j['error'], fb_error_message=j['errorDescription'])
-            raise Exception('Error #{} when sending request: {}'.format(j['error']['code'], repr(j['error']['debug_info'])))
+    elif 'debug_info' in j['error'] and 'code' in j['error']:
-        else:
+        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'])
-            raise Exception('Error {} when sending request'.format(j['error']))
+    else:
+        raise FBchatFacebookError('Error {} when sending request'.format(j['error']), fb_error_code=j['error'])
 
-def checkRequest(r, do_json_check=True):
+def check_request(r, as_json=True):
     if not r.ok:
-        raise Exception('Error when sending request: Got {} response'.format(r.status_code))
+        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 Exception('Error when sending request: Got empty response')
+        raise FBchatFacebookError('Error when sending request: Got empty response')
 
-    if do_json_check:
+    if as_json:
         content = strip_to_json(content)
         try:
             j = json.loads(content)
-        except Exception as e:
+        except ValueError:
-            raise Exception('Error while parsing JSON: {}'.format(repr(content)), e)
+            raise FBchatFacebookError('Error while parsing JSON: {}'.format(repr(content)))
         check_json(j)
         return j
     else:

requirements.txt

@@ -1,3 +1,4 @@
 requests
 lxml
 beautifulsoup4
+enum34; python_version < '3.4'

setup.py

@@ -4,22 +4,24 @@
 """
 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()
 
-try:
+requirements = [
-    requirements = [line.rstrip('\n') for line in open(os.path.join('fbchat.egg-info', 'requires.txt'))]
+    'requests',
-except FileNotFoundError:
+    'lxml',
-    requirements = [line.rstrip('\n') for line in open('requirements.txt')]
+    'beautifulsoup4'
+]
+
+extras_requirements = {
+    ':python_version < "3.4"': ['enum34']
+}
 
 version = None
 author = None
@@ -75,6 +77,7 @@ setup(
     include_package_data=True,
     packages=['fbchat'],
     install_requires=requirements,
+    extras_require=extras_requirements,
     url=source,
     version=version,
     zip_safe=True,

tests.py

@@ -79,7 +79,7 @@ class TestFbchat(unittest.TestCase):
         users = client.fetchAllUsers()
         self.assertGreater(len(users), 0)
 
-    def test_searchForUsers(self):
+    def test_searchFor(self):
         users = client.searchForUsers('Mark Zuckerberg')
         self.assertGreater(len(users), 0)
 
@@ -92,6 +92,10 @@ class TestFbchat(unittest.TestCase):
         self.assertEqual(u.url[:4], 'http')
         self.assertEqual(u.name, 'Mark Zuckerberg')
 
+        group_name = client.changeThreadTitle('tést_searchFor', thread_id=group_id, thread_type=ThreadType.GROUP)
+        groups = client.searchForGroups('té')
+        self.assertGreater(len(groups), 0)
+
     def test_sendEmoji(self):
         self.assertIsNotNone(client.sendEmoji(size=EmojiSize.SMALL, thread_id=user_id, thread_type=ThreadType.USER))
         self.assertIsNotNone(client.sendEmoji(size=EmojiSize.MEDIUM, thread_id=user_id, thread_type=ThreadType.USER))
@@ -140,10 +144,13 @@ class TestFbchat(unittest.TestCase):
 
         self.assertTrue(client.got_qprimer)
 
-    def test_fetchUserInfo(self):
+    def test_fetchInfo(self):
         info = client.fetchUserInfo('4')['4']
         self.assertEqual(info.name, 'Mark Zuckerberg')
 
+        info = client.fetchGroupInfo(group_id)[group_id]
+        self.assertEqual(info.type, ThreadType.GROUP)
+
     def test_removeAddFromGroup(self):
         client.removeUserFromGroup(user_id, thread_id=group_id)
         client.addUsersToGroup(user_id, thread_id=group_id)