The Slack Conversations API is the unified Web API for working with all types of Slack conversationspublic and private channels, direct messages, and multi-person DMs. It lets apps discover and inspect conversations, list members, and read message history and threads, as well as create, join, invite, leave, and archive channels where permissions allow.
openapi: 3.1.0
info:
version: "1.0"
title: Slack Conversations API
description: "The Slack Conversations API is the unified Web API for working with all types of Slack conversations\x14public and private channels, direct messages, and multi-person DMs. It lets apps discover
and inspect conversations, list members, and read message history and threads, as well as create, join, invite, leave, and archive channels where permissions allow. By consolidating the legacy channels.*,
groups.*, im.*, and mpim.* endpoints into conversations.*, it provides consistent IDs and behavior across conversation types. It supports cursor-based pagination, filtering by conversation type, and
granular OAuth scopes to ensure apps only access authorized data. Developers use it to find the right place to post, fetch context for workflows, manage membership, and build features that traverse
messages and threads across a workspace (including Slack Connect channels when permitted)."
paths:
/conversations.archive:
post:
tags:
- Archive
- Conversations
- Post
description: Archives a conversation.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/conversations.archive
operationId: postConversationsArchive
parameters:
- name: token
in: header
description: 'Authentication token. Requires scope: `conversations:write`'
schema:
type: string
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
channel:
type: string
description: ID of conversation to archive
application/json:
schema:
type: object
properties:
channel:
type: string
description: ID of conversation to archive
responses:
'200':
description: Typical success response
content:
application/json:
schema:
title: conversations.archive success schema
required:
- ok
type: object
properties:
ok:
$ref: '#/components/schemas/defs_ok_true'
additionalProperties: false
description: Schema for successful response conversations.archive method
example:
ok: true
default:
description: Typical error response
content:
application/json:
schema:
title: conversations.archive error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
error:
type: string
enum:
- method_not_supported_for_channel_type
- missing_scope
- not_supported
- channel_not_found
- already_archived
- cant_archive_general
- restricted_action
- not_authed
- invalid_auth
- account_inactive
- user_is_bot
- user_is_restricted
- user_is_ultra_restricted
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
- team_added_to_org
- missing_charset
- superfluous_charset
needed:
type: string
ok:
$ref: '#/components/schemas/defs_ok_false'
provided:
type: string
additionalProperties: false
description: Schema for error response from conversations.archive method
example:
error: channel_not_found
ok: false
security:
- slackAuth:
- channels:write
- groups:write
- im:write
- mpim:write
summary: Slack Post Conversations Archive
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/conversations.close:
post:
tags:
- Close
- Conversations
- Post
description: Closes a direct message or multi-person direct message.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/conversations.close
operationId: postConversationsClose
parameters:
- name: token
in: header
description: 'Authentication token. Requires scope: `conversations:write`'
schema:
type: string
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
channel:
type: string
description: Conversation to close.
application/json:
schema:
type: object
properties:
channel:
type: string
description: Conversation to close.
responses:
'200':
description: Typical success response
content:
application/json:
schema:
title: conversations.close success schema
required:
- ok
type: object
properties:
already_closed:
type: boolean
no_op:
type: boolean
ok:
$ref: '#/components/schemas/defs_ok_true'
additionalProperties: false
description: Schema for successful response conversations.close method
example:
ok: true
default:
description: Typical error response
content:
application/json:
schema:
title: conversations.close error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
error:
type: string
enum:
- method_not_supported_for_channel_type
- channel_not_found
- user_does_not_own_channel
- missing_scope
- not_authed
- invalid_auth
- account_inactive
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- team_added_to_org
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
needed:
type: string
ok:
$ref: '#/components/schemas/defs_ok_false'
provided:
type: string
additionalProperties: false
description: Schema for error response from conversations.close method
example:
error: channel_not_found
ok: false
security:
- slackAuth:
- channels:write
- groups:write
- im:write
- mpim:write
summary: Slack Post Conversations Close
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/conversations.create:
post:
tags:
- Conversations
- Create
- Post
description: Initiates a public or private channel-based conversation
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/conversations.create
operationId: postConversationsCreate
parameters:
- name: token
in: header
description: 'Authentication token. Requires scope: `conversations:write`'
schema:
type: string
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
description: Name of the public or private channel to create
is_private:
type: boolean
description: Create a private channel instead of a public one
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the public or private channel to create
is_private:
type: boolean
description: Create a private channel instead of a public one
responses:
'200':
description: >-
If successful, the command returns a rather stark [conversation
object](/types/conversation)
content:
application/json:
schema:
title: conversations.create success schema
required:
- channel
- ok
type: object
properties:
channel:
$ref: '#/components/schemas/objs_conversation'
ok:
$ref: '#/components/schemas/defs_ok_true'
additionalProperties: false
description: Schema for successful response conversations.create method
example:
channel:
created: 1504554479
creator: U0123456
id: C0EAQDV4Z
is_archived: false
is_channel: true
is_ext_shared: false
is_general: false
is_group: false
is_im: false
is_member: true
is_mpim: false
is_org_shared: false
is_pending_ext_shared: false
is_private: false
is_shared: false
last_read: '0000000000.000000'
latest:
name: endeavor
name_normalized: endeavor
pending_shared: []
previous_names: []
priority: 0
purpose:
creator: ''
last_set: 0
value: ''
topic:
creator: ''
last_set: 0
value: ''
unlinked: 0
unread_count: 0
unread_count_display: 0
ok: true
default:
description: Typical error response when name already in use
content:
application/json:
schema:
title: conversations.create error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
detail:
type: string
error:
type: string
enum:
- method_not_supported_for_channel_type
- missing_scope
- name_taken
- restricted_action
- no_channel
- invalid_name_required
- invalid_name_punctuation
- invalid_name_maxlength
- invalid_name_specials
- invalid_name
- not_authed
- invalid_auth
- account_inactive
- user_is_bot
- user_is_restricted
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- team_added_to_org
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
needed:
type: string
ok:
$ref: '#/components/schemas/defs_ok_false'
provided:
type: string
additionalProperties: false
description: Schema for error response from conversations.create method
example:
error: name_taken
ok: false
security:
- slackAuth:
- channels:write
- groups:write
- im:write
- mpim:write
summary: Slack Post Conversations Create
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/conversations.history:
get:
tags:
- Conversations
- Get
- History
description: Fetches a conversation's history of messages and events.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/conversations.history
operationId: getConversationsHistory
parameters:
- name: token
in: query
description: 'Authentication token. Requires scope: `conversations:history`'
schema:
type: string
- name: channel
in: query
description: Conversation ID to fetch history for.
schema:
type: string
- name: latest
in: query
description: End of time range of messages to include in results.
schema:
type: number
- name: oldest
in: query
description: Start of time range of messages to include in results.
schema:
type: number
- name: inclusive
in: query
description: >-
Include messages with latest or oldest timestamp in results only
when either timestamp is specified.
schema:
type: boolean
- name: limit
in: query
description: >-
The maximum number of items to return. Fewer than the requested
number of items may be returned, even if the end of the users list
hasn't been reached.
schema:
type: integer
- name: cursor
in: query
description: >-
Paginate through collections of data by setting the `cursor`
parameter to a `next_cursor` attribute returned by a previous
request's `response_metadata`. Default value fetches the first
"page" of the collection. See [pagination](/docs/pagination) for
more detail.
schema:
type: string
responses:
'200':
description: Typical success response containing a channel's messages
content:
application/json:
schema:
title: conversations.history success schema
required:
- channel_actions_count
- channel_actions_ts
- has_more
- messages
- ok
- pin_count
type: object
properties:
channel_actions_count:
type: integer
channel_actions_ts:
type: object
has_more:
type: boolean
messages:
minItems: 1
uniqueItems: true
type: array
items:
$ref: '#/components/schemas/objs_message'
ok:
$ref: '#/components/schemas/defs_ok_true'
pin_count:
type: integer
additionalProperties: false
description: >-
Schema for successful response from conversations.history
method
example:
has_more: true
messages:
- text: I find you punny and would like to smell your nose letter
ts: '1512085950.000216'
type: message
user: U012AB3CDE
- text: What, you want to smell my shoes better?
ts: '1512104434.000490'
type: message
user: U061F7AUR
ok: true
pin_count: 0
response_metadata:
next_cursor: bmV4dF90czoxNTEyMDg1ODYxMDAwNTQz
default:
description: Typical error response
content:
application/json:
schema:
title: conversations.history error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
error:
type: string
enum:
- missing_scope
- channel_not_found
- invalid_ts_latest
- invalid_ts_oldest
- not_authed
- invalid_auth
- account_inactive
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
needed:
type: string
ok:
$ref: '#/components/schemas/defs_ok_false'
provided:
type: string
additionalProperties: false
description: Schema for error response from conversations.history method
example:
error: channel_not_found
ok: false
security:
- slackAuth:
- channels:history
- groups:history
- im:history
- mpim:history
summary: Slack Get Conversations History
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/conversations.info:
get:
tags:
- Conversations
- Get
- Info
description: Retrieve information about a conversation.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/conversations.info
operationId: getConversationsInfo
parameters:
- name: token
in: query
description: 'Authentication token. Requires scope: `conversations:read`'
schema:
type: string
- name: channel
in: query
description: Conversation ID to learn more about
schema:
type: string
- name: include_locale
in: query
description: >-
Set this to `true` to receive the locale for this conversation.
Defaults to `false`
schema:
type: boolean
- name: include_num_members
in: query
description: >-
Set to `true` to include the member count for the specified
conversation. Defaults to `false`
schema:
type: boolean
responses:
'200':
description: >-
Typical success response for a public channel. (Also, a response
from a private channel and a multi-party IM is very similar to this
example.)
content:
application/json:
schema:
title: conversations.info success schema
required:
- channel
- ok
type: object
properties:
channel:
$ref: '#/components/schemas/objs_conversation'
ok:
$ref: '#/components/schemas/defs_ok_true'
additionalProperties: false
description: Schema for successful response conversations.info
example:
channel:
created: 1449252889
creator: W012A3BCD
id: C012AB3CD
is_archived: false
is_channel: true
is_ext_shared: false
is_general: true
is_group: false
is_im: false
is_member: true
is_mpim: false
is_org_shared: false
is_pending_ext_shared: false
is_private: false
is_read_only: false
is_shared: false
last_read: '1502126650.228446'
locale: en-US
name: general
name_normalized: general
parent_conversation:
pending_shared: []
previous_names:
- specifics
- abstractions
- etc
purpose:
creator: W012A3BCD
last_set: 1449709364
value: This part of the workspace is for fun. Make fun here.
topic:
creator: W012A3BCD
last_set: 1449709364
value: For public discussion of generalities
unlinked: 0
ok: true
default:
description: Typical error response when a channel cannot be found
content:
application/json:
schema:
title: conversations.info error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
error:
type: string
enum:
- missing_scope
- channel_not_found
- team_added_to_org
- not_authed
- invalid_auth
- account_inactive
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
needed:
type: string
ok:
$ref: '#/components/schemas/defs_ok_false'
provided:
type: string
additionalProperties: false
description: Schema for error response from conversations.info method
example:
error: channel_not_found
ok: false
security:
- slackAuth:
- channels:read
- groups:read
- im:read
- mpim:read
summary: Slack Get Conversations Info
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/conversations.invite:
post:
tags:
- Conversations
- Invites
- Post
description: Invites users to a channel.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/conversations.invite
operationId: postConversationsInvite
parameters:
- name: token
in: header
description: 'Authentication token. Requires scope: `conversations:write`'
schema:
type: string
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
channel:
type: string
description: >-
The ID of the public or private channel to invite user(s)
to.
users:
type: string
description: >-
A comma separated list of user IDs. Up to 1000 users may be
listed.
application/json:
schema:
type: object
properties:
channel:
type: string
description: >-
The ID of the public or private channel to invite user(s)
to.
users:
type: string
description: >-
A comma separated list of user IDs. Up to 1000 users may be
listed.
responses:
'200':
description: Typical success response when an invitation is extended
content:
application/json:
schema:
title: conversations.invite error schema
required:
- channel
- ok
type: object
properties:
channel:
$ref: '#/components/schemas/objs_conversation'
ok:
$ref: '#/components/schemas/defs_ok_true'
additionalProperties: false
description: >-
Schema for successful response from conversations.invite
method
example:
channel:
created: 1449252889
creator: W012A3BCD
id: C012AB3CD
is_archived: false
is_channel: true
is_ext_shared: false
is_general: true
is_group: false
is_im: false
is_member: true
is_mpim: false
is_org_shared: false
is_pending_ext_shared: false
is_private: false
is_read_only: false
is_shared: false
last_read: '1502126650.228446'
locale: en-US
name: general
name_normalized: general
num_members: 23
pending_shared: []
previous_names:
- specifics
- abstractions
- etc
purpose:
creator: W012A3BCD
last_set: 1449709364
value: This part of the workspace is for fun. Make fun here.
topic:
creator: W012A3BCD
last_set: 1449709364
value: For public discussion of generalities
unlinked: 0
ok: true
default:
description: >-
Typical error response when an invite is attempted on a conversation
type that does not support it
content:
application/json:
schema:
title: conversations.invite error schema
required:
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
error:
type: string
enum:
- method_not_supported_for_channel_type
- missing_scope
- channel_not_found
- user_not_found
- no_user
- cant_invite_self
- not_in_channel
- already_in_channel
- is_archived
- cant_invite
- too_many_users
- ura_max_channels
- not_authed
- invalid_auth
- account_inactive
- user_is_bot
- user_is_restricted
- user_is_ultra_restricted
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
- team_added_to_org
- missing_charset
- superfluous_charset
errors:
title: errors is returned when an error associates an user
minItems: 1
uniqueItems: true
type: array
items:
type: object
additionalProperties: false
needed:
type: string
ok:
$ref: '#/components/schemas/defs_ok_false'
provided:
type: string
additionalProperties: false
description: Schema for error response from conversations.invite method
example:
error: method_not_supported_for_channel_type
ok: false
security:
- slackAuth:
- channels:write
- groups:write
- im:write
- mpim:write
summary: Slack Post Conversations Invite
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/conversations.join:
post:
tags:
- Conversations
- Join
- Post
description: Joins an existing conversation.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/conversations.join
operationId: postConversationsJoin
parameters:
- name: token
in: heade
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/slack/refs/heads/main/openapi/slack-conversations-openapi.yml