Update README and docs snippets

Update README to include an example and change the status of v0.3.
Update some snippets to fix errors and improve the code.

README.md

@@ -8,10 +8,10 @@
 `pyryver` is an unofficial async Python library for Ryver.
 It provides a simple and sane way of automating tasks on Ryver and building bots, without the need to set up Hubot or Botkit.
 
-Note that since it is still in major version 0, the API may change any time. 
+Note that since it is still in major version 0, there may be small changes to the API any time.
 However, we will attempt to make it as backwards-compatible as possible (excluding version 0.1.0).
 
-Version 0.3.0 is currently in alpha.
+Version 0.3.0 is now stable! It is highly recommended due to the API cleanups and Tasks support.
 
 Special thanks to [@mincrmatt12](https://github.com/mincrmatt12)!
 
@@ -36,3 +36,58 @@ If there's something missing from the API that you'd like to see, create an issu
 Documentation and examples can be found on [Read the Docs](https://pyryver.readthedocs.io).
 
 If you want to see an example of `pyryver` being used in a real project, check out [LaTeX Bot](https://github.com/tylertian123/ryver-latexbot).
+
+Here's an example demonstrating how to send a message:
+```py
+import pyryver
+import asyncio
+
+async def main():
+    # Connect to ryver
+    async with pyryver.Ryver("my_organization", "my_username", "my_password") as ryver:
+        # Load all chats
+        await ryver.load_chats()
+        # Find users and forums/teams
+        friend = ryver.get_user(username="my_friend")
+        forum_or_team = ryver.get_groupchat(name="My Forum or Team")
+        # Send a message
+        await friend.send_message("Hello, friend!")
+        await forum_or_team.send_message("Hello, forum or team!")
+
+asyncio.get_event_loop().run_until_complete(main())
+```
+
+Here's an example demonstrating how to get your bot to respond in real-time:
+```py
+import pyryver
+import asyncio
+
+async def main():
+    # Connect to ryver
+    async with pyryver.Ryver("my_organization", "my_username", "my_password") as ryver:
+        # Load all chats
+        await ryver.load_chats()
+        # Get the bot's user
+        me = ryver.get_user(username="my_username")
+        # Connect to the websockets interface
+        async with ryver.get_live_session() as session:
+            @session.on_chat
+            async def on_message(msg: pyryver.WSChatMessageData):
+                print(msg.text) # print out the message's text
+                # Reply to the message
+                # Make sure to check that the message isn't from the bot itself
+                if msg.from_jid != me.get_jid() and msg.text == "hello":
+                    # Send a message to the same chat
+                    # This could be either a user (for a private message) or a forum/team
+                    chat = ryver.get_chat(jid=msg.to_jid)
+                    await chat.send_message("hi")
+
+            @session.on_connection_loss
+            async def on_connection_loss():
+                await session.close()
+
+            # run until session.close() is called
+            await session.run_forever()
+
+asyncio.get_event_loop().run_until_complete(main())
+```

docs/_snippets/frontpage1.py

@@ -3,21 +3,34 @@
 
 async def main():
     # Connect to ryver
-    async with pyryver.Ryver("myorg", "username", "password") as ryver:
-        await ryver.load_users()
+    async with pyryver.Ryver("my_organization", "my_username", "my_password") as ryver:
+        # Load all chats
+        await ryver.load_chats()
 
         # get a user by username
         my_friend = ryver.get_user(username="tylertian123")
+        me = ryver.get_user(username="my_username")
         # send a message to a chat (in this case a DM)
         await my_friend.send_message("hello there") 
 
         # connect to the websockets interface
         async with ryver.get_live_session() as session:
             @session.on_chat
-            def on_message(msg: pyryver.WSChatMessageData):
+            async def on_message(msg: pyryver.WSChatMessageData):
                 print(msg.text) # print out the message's text
+                # Reply to the message
+                # Make sure to check that the message isn't from the bot itself
+                if msg.from_jid != me.get_jid() and msg.text == "hello":
+                    # Send a message to the same chat
+                    # This could be either a user (for a private message) or a forum/team
+                    chat = ryver.get_chat(jid=msg.to_jid)
+                    await chat.send_message("hi")
+
+            @session.on_connection_loss
+            async def on_connection_loss():
+                await session.close()
 
-            # run until session.close()
+            # run until session.close() is called
             await session.run_forever()
 
 asyncio.get_event_loop().run_until_complete(main())

docs/intro.rst

@@ -85,6 +85,10 @@ The contents of the ``msg`` parameter passed to our callback is an object of typ
 there are two fields our "bot" needs to care about: ``to_jid``, which specifies which chat the message was posted in, and ``text``, which is the content of the message. ``from_jid`` refers to the message's creator.
 Perhaps unintuitively, the ``to_jid`` field should be referring to our user's chat, since we're looking at a private DM. For group chats, you'd expect the chat's JID here.
 
+.. note::
+   Note that the callback will be called even if the message was sent by the current logged in user!
+   Therefore, even if you want to respond to messages from everyone, you should still make sure to check that ``from_jid`` is not the bot user's JID to avoid replying to your own messages.
+
 Notice how we're working with the chat's **JID** here, which is a string, as opposed to the regular ID, which is an integer.
 This is because the websocket system uses JIDs to refer to chats. Using this information, we can complete our terrible little bot: