Added message threads to the docs (#163)

* Added message threading to docs

Author: Roach

README.rst

@@ -21,6 +21,7 @@ Whether you're building a custom app for your team, or integrating a third party
 service into your Slack workflows, Slack Developer Kit for Python allows you to leverage the flexibility
 of Python to get your project up and running as quickly as possible.
 
+
 Requirements and Installation
 ******************************
 
@@ -41,6 +42,11 @@ by pulling down the source code directly into your project:
 	git clone https://github.com/slackapi/python-slackclient.git
 	pip install -r requirements.txt
 
+Documentation
+--------------
+
+For comprehensive method information and usage examples, see the `full documentation <http://slackapi.github.io/python-slackclient>`_.
+
 Getting Help
 -------------
 
@@ -49,11 +55,6 @@ If you get stuck, we’re here to help. The following are the best ways to get a
 - Use our `Github Issue Tracker <https://github.com/slackapi/python-slackclient/issues>`_ for reporting bugs or requesting features.
 - Visit the `dev4slack channel <http://dev4slack.xoxco.com>`_ for getting help using Slack Developer Kit for Python or just generally bond with your fellow Slack developers.
 
-Documentation
---------------
-
-For comprehensive method information and usage examples, see the `full documentation <http://slackapi.github.io/python-slackclient>`_.
-
 Basic Usage
 ------------
 The Slack Web API allows you to build applications that interact with Slack in more complex ways than the integrations
@@ -89,6 +90,61 @@ There are some unique options specific to sending IMs, so be sure to read the **
 section of the `chat.postMessage <https://api.slack.com/methods/chat.postMessage#channels>`_
 page for a full list of formatting and authorship options.
 
+
+Replying to messages and creating threads
+********************
+Threaded messages are just like regular messages, except thread replies are grouped together to provide greater context
+to the user. You can reply to a thread or start a new threaded conversation by simply passing the original message's ``ts``
+ID in the ``thread_ts`` attribute when posting a message. If you're replying to a threaded message, you'll pass the `thread_ts`
+ID of the message you're replying to.
+
+A channel or DM conversation is a nearly linear timeline of messages exchanged between people, bots, and apps.
+When one of these messages is replied to, it becomes the parent of a thread. By default, threaded replies do not
+appear directly in the channel, instead relegated to a kind of forked timeline descending from the parent message.
+
+.. code-block:: python
+
+  from slackclient import SlackClient
+
+  slack_token = os.environ["SLACK_API_TOKEN"]
+  sc = SlackClient(slack_token)
+
+  sc.api_call(
+    "chat.postMessage",
+    channel="#python",
+    text="Hello from Python! :tada:",
+    thread_ts="1476746830.000003"
+  )
+
+
+By default, ``reply_broadcast`` is set to ``False``. To indicate your reply is germane to all members of a channel,
+set the ``reply_broadcast`` boolean parameter to ``True``.
+
+.. code-block:: python
+
+  from slackclient import SlackClient
+
+  slack_token = os.environ["SLACK_API_TOKEN"]
+  sc = SlackClient(slack_token)
+
+  sc.api_call(
+    "chat.postMessage",
+    channel="#python",
+    text="Hello from Python! :tada:",
+    thread_ts="1476746830.000003",
+    reply_broadcast=True
+  )
+
+
+**Note:** While threaded messages may contain attachments and message buttons, when your reply is broadcast to the
+channel, it'll actually be a reference to your reply, not the reply itself.
+So, when appearing in the channel, it won't contain any attachments or message buttons. Also note that updates and
+deletion of threaded replies works the same as regular messages.
+
+See the `Threading messages together <https://api.slack.com/docs/message-threading#forking_conversations>`_
+article for more information.
+
+
 Deleting a message
 ********************
 Sometimes you need to delete things.

docs-src/basic_usage.rst

@@ -38,6 +38,62 @@ There are some unique options specific to sending IMs, so be sure to read the **
 section of the `chat.postMessage <https://api.slack.com/methods/chat.postMessage#channels>`_
 page for a full list of formatting and authorship options.
 
+--------
+
+Replying to messages and creating threads
+-----------------------
+Threaded messages are just like regular messages, except thread replies are grouped together to provide greater context
+to the user. You can reply to a thread or start a new threaded conversation by simply passing the original message's ``ts``
+ID in the ``thread_ts`` attribute when posting a message. If you're replying to a threaded message, you'll pass the `thread_ts`
+ID of the message you're replying to.
+
+A channel or DM conversation is a nearly linear timeline of messages exchanged between people, bots, and apps.
+When one of these messages is replied to, it becomes the parent of a thread. By default, threaded replies do not
+appear directly in the channel, instead relegated to a kind of forked timeline descending from the parent message.
+
+.. code-block:: python
+
+  from slackclient import SlackClient
+
+  slack_token = os.environ["SLACK_API_TOKEN"]
+  sc = SlackClient(slack_token)
+
+  sc.api_call(
+    "chat.postMessage",
+    channel="#python",
+    text="Hello from Python! :tada:",
+    thread_ts="1476746830.000003"
+  )
+
+
+By default, ``reply_broadcast`` is set to ``False``. To indicate your reply is germane to all members of a channel,
+set the ``reply_broadcast`` boolean parameter to ``True``.
+
+.. code-block:: python
+
+  from slackclient import SlackClient
+
+  slack_token = os.environ["SLACK_API_TOKEN"]
+  sc = SlackClient(slack_token)
+
+  sc.api_call(
+    "chat.postMessage",
+    channel="#python",
+    text="Hello from Python! :tada:",
+    thread_ts="1476746830.000003",
+    reply_broadcast=True
+  )
+
+
+**Note:** While threaded messages may contain attachments and message buttons, when your reply is broadcast to the
+channel, it'll actually be a reference to your reply, not the reply itself.
+So, when appearing in the channel, it won't contain any attachments or message buttons. Also note that updates and
+deletion of threaded replies works the same as regular messages.
+
+See the `Threading messages together <https://api.slack.com/docs/message-threading#forking_conversations>`_
+article for more information.
+
+
 --------
 
 Updating the content of a message

docs/about.html

@@ -52,6 +52,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#adding-or-removing-an-emoji-reaction">Adding or removing an emoji reaction</a></li>
@@ -77,6 +78,9 @@
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="changelog.html#v1-0-4-2016-12-15">v1.0.4 (2016-12-15)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="changelog.html#v1-0-3-2016-12-13">v1.0.3 (2016-12-13)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="changelog.html#v1-0-2-2016-09-22">v1.0.2 (2016-09-22)</a></li>
 <li class="toctree-l2"><a class="reference internal" href="changelog.html#v1-0-1-2016-03-25">v1.0.1 (2016-03-25)</a></li>
 <li class="toctree-l2"><a class="reference internal" href="changelog.html#v1-0-0-2016-02-28">v1.0.0 (2016-02-28)</a></li>
 <li class="toctree-l2"><a class="reference internal" href="changelog.html#v0-18-0-2016-02-21">v0.18.0 (2016-02-21)</a></li>

docs/auth.html

@@ -52,6 +52,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#adding-or-removing-an-emoji-reaction">Adding or removing an emoji reaction</a></li>
@@ -217,7 +218,7 @@ <h2>The OAuth flow<a class="headerlink" href="#the-oauth-flow" title="Permalink
 user access token instead of the top-level access token granted to your application.</p>
 <div class="highlight-python"><div class="highlight"><pre><span></span><span class="c1"># Save the bot token to an environmental variable or to your data store</span>
 <span class="c1"># for later use</span>
-<span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&quot;SLACK_USER_TOKEN&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">auth_response</span><span class="p">[</span><span class="s1">&#39;user_access_token&#39;</span><span class="p">]</span>
+<span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&quot;SLACK_USER_TOKEN&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">auth_response</span><span class="p">[</span><span class="s1">&#39;access_token&#39;</span><span class="p">]</span>
 <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&quot;SLACK_BOT_TOKEN&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">auth_response</span><span class="p">[</span><span class="s1">&#39;bot&#39;</span><span class="p">][</span><span class="s1">&#39;bot_access_token&#39;</span><span class="p">]</span>
 
 <span class="c1"># Don&#39;t forget to let the user know that auth has succeeded!</span>

docs/basic_usage.html

@@ -52,6 +52,7 @@
 </li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#deleting-a-message">Deleting a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#adding-or-removing-an-emoji-reaction">Adding or removing an emoji reaction</a></li>
@@ -146,6 +147,52 @@ <h2>Sending a message<a class="headerlink" href="#sending-a-message" title="Perm
 page for a full list of formatting and authorship options.</p>
 </div>
 <hr class="docutils" />
+<div class="section" id="replying-to-messages-and-creating-threads">
+<h2>Replying to messages and creating threads<a class="headerlink" href="#replying-to-messages-and-creating-threads" title="Permalink to this headline">¶</a></h2>
+<p>Threaded messages are just like regular messages, except thread replies are grouped together to provide greater context
+to the user. You can reply to a thread or start a new threaded conversation by simply passing the original message&#8217;s <code class="docutils literal"><span class="pre">ts</span></code>
+ID in the <code class="docutils literal"><span class="pre">thread_ts</span></code> attribute when posting a message. If you&#8217;re replying to a threaded message, you&#8217;ll pass the <cite>thread_ts</cite>
+ID of the message you&#8217;re replying to.</p>
+<p>A channel or DM conversation is a nearly linear timeline of messages exchanged between people, bots, and apps.
+When one of these messages is replied to, it becomes the parent of a thread. By default, threaded replies do not
+appear directly in the channel, instead relegated to a kind of forked timeline descending from the parent message.</p>
+<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">slackclient</span> <span class="kn">import</span> <span class="n">SlackClient</span>
+
+<span class="n">slack_token</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&quot;SLACK_API_TOKEN&quot;</span><span class="p">]</span>
+<span class="n">sc</span> <span class="o">=</span> <span class="n">SlackClient</span><span class="p">(</span><span class="n">slack_token</span><span class="p">)</span>
+
+<span class="n">sc</span><span class="o">.</span><span class="n">api_call</span><span class="p">(</span>
+  <span class="s2">&quot;chat.postMessage&quot;</span><span class="p">,</span>
+  <span class="n">channel</span><span class="o">=</span><span class="s2">&quot;#python&quot;</span><span class="p">,</span>
+  <span class="n">text</span><span class="o">=</span><span class="s2">&quot;Hello from Python! :tada:&quot;</span><span class="p">,</span>
+  <span class="n">thread_ts</span><span class="o">=</span><span class="s2">&quot;1476746830.000003&quot;</span>
+<span class="p">)</span>
+</pre></div>
+</div>
+<p>By default, <code class="docutils literal"><span class="pre">reply_broadcast</span></code> is set to <code class="docutils literal"><span class="pre">False</span></code>. To indicate your reply is germane to all members of a channel,
+set the <code class="docutils literal"><span class="pre">reply_broadcast</span></code> boolean parameter to <code class="docutils literal"><span class="pre">True</span></code>.</p>
+<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">slackclient</span> <span class="kn">import</span> <span class="n">SlackClient</span>
+
+<span class="n">slack_token</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&quot;SLACK_API_TOKEN&quot;</span><span class="p">]</span>
+<span class="n">sc</span> <span class="o">=</span> <span class="n">SlackClient</span><span class="p">(</span><span class="n">slack_token</span><span class="p">)</span>
+
+<span class="n">sc</span><span class="o">.</span><span class="n">api_call</span><span class="p">(</span>
+  <span class="s2">&quot;chat.postMessage&quot;</span><span class="p">,</span>
+  <span class="n">channel</span><span class="o">=</span><span class="s2">&quot;#python&quot;</span><span class="p">,</span>
+  <span class="n">text</span><span class="o">=</span><span class="s2">&quot;Hello from Python! :tada:&quot;</span><span class="p">,</span>
+  <span class="n">thread_ts</span><span class="o">=</span><span class="s2">&quot;1476746830.000003&quot;</span><span class="p">,</span>
+  <span class="n">reply_broadcast</span><span class="o">=</span><span class="bp">True</span>
+<span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Note:</strong> While threaded messages may contain attachments and message buttons, when your reply is broadcast to the
+channel, it&#8217;ll actually be a reference to your reply, not the reply itself.
+So, when appearing in the channel, it won&#8217;t contain any attachments or message buttons. Also note that updates and
+deletion of threaded replies works the same as regular messages.</p>
+<p>See the <a class="reference external" href="https://api.slack.com/docs/message-threading#forking_conversations">Threading messages together</a>
+article for more information.</p>
+</div>
+<hr class="docutils" />
 <div class="section" id="updating-the-content-of-a-message">
 <h2>Updating the content of a message<a class="headerlink" href="#updating-the-content-of-a-message" title="Permalink to this headline">¶</a></h2>
 <p>Let&#8217;s say you have a bot which posts the status of a request. When that request

docs/changelog.html

@@ -52,6 +52,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#adding-or-removing-an-emoji-reaction">Adding or removing an emoji reaction</a></li>

docs/faq.html

@@ -52,6 +52,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#adding-or-removing-an-emoji-reaction">Adding or removing an emoji reaction</a></li>

docs/genindex.html

@@ -53,6 +53,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#adding-or-removing-an-emoji-reaction">Adding or removing an emoji reaction</a></li>

docs/index.html

@@ -52,6 +52,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#adding-or-removing-an-emoji-reaction">Adding or removing an emoji reaction</a></li>