Skip to content

Commit 2a9c546

Browse files
RoachRoach
authored
Added documentation for the Conversations API (#224)
* Updated too config to add .nojekyll file * Docs CSS tweaks * docs CSS tweaks * Fixed section marker * Added Conversations API and regenerated docs
1 parent d8a0389 commit 2a9c546

23 files changed

+10888
-12
lines changed

‎docs-src/_themes/slack/layout.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
<link rel="stylesheet" href="https://a.slack-edge.com/2133/style/plastic_grid.css" type="text/css" />
1616
<link rel="stylesheet" href="https://a.slack-edge.com/be9e/style/plastic_buttons.css" type="text/css" />
1717
<link rel="stylesheet" href="https://a.slack-edge.com/1d9c/style/libs/lato-1-compressed.css" type="text/css" />
18+
<link rel="stylesheet" href="https://a.slack-edge.com/e8c1/style/slack_iconfont.css" type="text/css">
1819
<link rel="stylesheet" href="{{ pathto('./_static/' + 'default.css', 1) }}" type="text/css" />
1920
<link rel="stylesheet" href="{{ pathto('./_static/' + 'pygments.css', 1) }}" type="text/css" />
2021
{%- endmacro %}

‎docs-src/_themes/slack/static/default.css_t‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
.section h1, .section .headerlink {
2-
display: none;
1+
a.headerlink {
2+
display: none !important;
33
}
44

55
.section-title {

‎docs-src/basic_usage.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ See `chat.postEphemeral <https://api.slack.com/methods/chat.postEphemeral>`_ for
6060
--------
6161

6262
Replying to messages and creating threads
63-
-----------------------
63+
------------------------------------------
6464
Threaded messages are just like regular messages, except thread replies are grouped together to provide greater context
6565
to the user. You can reply to a thread or start a new threaded conversation by simply passing the original message's ``ts``
6666
ID in the ``thread_ts`` attribute when posting a message. If you're replying to a threaded message, you'll pass the `thread_ts`

‎docs-src/conversations.rst‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
.. _conversations_api:
2+
3+
==============================================
4+
Conversations API
5+
==============================================
6+
The Slack Conversations API provides your app with a unified interface to work with all the
7+
channel-like things encountered in Slack; public channels, private channels, direct messages, group
8+
direct messages, and our newest channel type, Shared Channels.
9+
10+
11+
See `Conversations API <https://api.slack.com/docs/conversations-api>`_ docs for more info.
12+
13+
--------
14+
15+
Creating a direct message or multi-person direct message
16+
---------------------------------------------------------
17+
This Conversations API method opens a multi-person direct message or just a 1:1 direct message.
18+
19+
*Use conversations.create for public or private channels.*
20+
21+
Provide 1 to 8 user IDs in the ``user`` parameter to open or resume a conversation. Providing only
22+
1 ID will create a direct message. Providing more will create an ``mpim``.
23+
24+
If there are no conversations already in progress including that exact set of members, a new
25+
multi-person direct message conversation begins.
26+
27+
Subsequent calls to ``conversations.open`` with the same set of users will return the already
28+
existing conversation.
29+
30+
31+
.. code-block:: python
32+
33+
from slackclient import SlackClient
34+
35+
slack_token = os.environ["SLACK_API_TOKEN"]
36+
sc = SlackClient(slack_token)
37+
38+
sc.api_call(
39+
"conversations.open",
40+
users=["W1234567890","U2345678901","U3456789012"]
41+
)
42+
43+
See `conversations.open <https://api.slack.com/methods/conversations.open>`_ additional info.
44+
45+
--------
46+
47+
Creating a public or private channel
48+
-------------------------------------
49+
Initiates a public or private channel-based conversation
50+
51+
.. code-block:: python
52+
53+
from slackclient import SlackClient
54+
55+
slack_token = os.environ["SLACK_API_TOKEN"]
56+
sc = SlackClient(slack_token)
57+
58+
sc.api_call(
59+
"conversations.create",
60+
name="myprivatechannel",
61+
is_private=True
62+
)
63+
64+
See `conversations.create <https://api.slack.com/methods/conversations.create>`_ additional info.
65+
66+
--------
67+
68+
Getting information about a conversation
69+
-----------------------------------------
70+
This Conversations API method returns information about a workspace conversation.
71+
72+
.. code-block:: python
73+
74+
from slackclient import SlackClient
75+
76+
slack_token = os.environ["SLACK_API_TOKEN"]
77+
sc = SlackClient(slack_token)
78+
79+
sc.api_call(
80+
"conversations.info",
81+
channel="C0XXXXXX",
82+
)
83+
84+
See `conversations.info <https://api.slack.com/methods/conversations.info>`_ for more info.
85+
86+
87+
--------
88+
89+
Getting a list of conversations
90+
--------------------------------
91+
This Conversations API method returns a list of all channel-like conversations in a workspace.
92+
The "channels" returned depend on what the calling token has access to and the directives placed
93+
in the ``types`` parameter.
94+
95+
96+
.. code-block:: python
97+
98+
from slackclient import SlackClient
99+
100+
slack_token = os.environ["SLACK_API_TOKEN"]
101+
sc = SlackClient(slack_token)
102+
103+
sc.api_call("conversations.list")
104+
105+
Only public conversations are included by default. You can include DMs and MPIMs by passing
106+
``public_channel,private_channel`` as the ``types`` in your request.
107+
108+
109+
.. code-block:: python
110+
111+
from slackclient import SlackClient
112+
113+
slack_token = os.environ["SLACK_API_TOKEN"]
114+
sc = SlackClient(slack_token)
115+
116+
sc.api_call(
117+
"conversations.list",
118+
types=["public_channel","private_channel"]
119+
)
120+
121+
See `conversations.list <https://api.slack.com/methods/conversations.list>`_ for more info.
122+
123+
124+
--------
125+
126+
Leaving a conversation
127+
-----------------------
128+
Maybe you've finished up all the business you had in a conversation, or maybe you
129+
joined one by accident. This is how you leave a conversation.
130+
131+
.. code-block:: python
132+
133+
from slackclient import SlackClient
134+
135+
slack_token = os.environ["SLACK_API_TOKEN"]
136+
sc = SlackClient(slack_token)
137+
138+
sc.api_call(
139+
"conversations.leave",
140+
channel="C0XXXXXXX"
141+
)
142+
143+
See `conversations.leave <https://api.slack.com/methods/conversations.leave>`_ for more info.
144+
145+
--------
146+
147+
Get conversation members
148+
------------------------------
149+
Get a list fo the members of a conversation
150+
151+
.. code-block:: python
152+
153+
from slackclient import SlackClient
154+
155+
slack_token = os.environ["SLACK_API_TOKEN"]
156+
sc = SlackClient(slack_token)
157+
158+
sc.api_call("conversations.members",
159+
channel="C0XXXXXXX"
160+
)
161+
162+
See `users.list <https://api.slack.com/methods/conversations.members>`_ for more info.
163+
164+
.. include:: metadata.rst

‎docs-src/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
self
55
auth
66
basic_usage
7+
conversations
78
real_time_messaging
89
faq
910
changelog

‎docs.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#!/usr/bin/env bash
2+
3+
sphinx-build -c ./docs-src/_themes/slack/ -b html docs-src docs && touch ./docs/.nojekyll

‎docs/.nojekyll‎

Whitespace-only changes.

‎docs/_static/default.css‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
.section h1, .section .headerlink {
2-
display: none;
1+
a.headerlink {
2+
display: none !important;
33
}
44

55
.section-title {

0 commit comments

Comments
 (0)