Slack Conversations API

openapi: 3.2.0
info:
  title: Slack Conversations API
  version: '1.0'
  description: 'Operations tagged Conversations across 3 of this provider''s published API definitions: slack-conversations-openapi.yml, slack-users-openapi.yml, slack-web-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://slack.com/api
  description: Slack Web API production server
tags:
- name: Conversations
paths:
  /conversations.create:
    post:
      tags:
      - Conversations
      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: null
                  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
      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
      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: null
                  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
      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
      description: Joins an existing conversation.
      externalDocs:
        description: API method documentation
        url: https://api.slack.com/methods/conversations.join
      operationId: postConversationsJoin
      parameters:
      - name: token
        in: header
        description: 'Authentication token. Requires scope: `channels:write`'
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  description: ID of conversation to join
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  description: ID of conversation to join
      responses:
        '200':
          description: Typical success response
          content:
            application/json:
              schema:
                title: conversations.join success schema
                required:
                - channel
                - ok
                type: object
                properties:
                  channel:
                    $ref: '#/components/schemas/objs_conversation'
                  ok:
                    $ref: '#/components/schemas/defs_ok_true'
                  response_metadata:
                    title: Response metadata
                    type: object
                    properties:
                      warnings:
                        minItems: 1
                        uniqueItems: true
                        type: array
                        items:
                          type: string
                  warning:
                    type: string
                additionalProperties: false
                description: Schema for successful response from conversations.join method
              example:
                channel:
                  created: 1449252889
                  creator: U061F7AUR
                  id: C061EG9SL
                  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_shared: false
                  name: general
                  name_normalized: general
                  pending_shared: []
                  previous_names: []
                  purpose:
                    creator: ''
                    last_set: 0
                    value: For widget discussion
                  topic:
                    creator: ''
                    last_set: 0
                    value: Which widget do you worry about?
                  unlinked: 0
                ok: true
                response_metadata:
                  warnings:
                  - already_in_channel
                warning: already_in_channel
        default:
          description: Typical error response if the conversation is archived and cannot be joined
          content:
            application/json:
              schema:
                title: conversations.join 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
                    - channel_not_found
                    - is_archived
                    - 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.join method
              example:
                error: is_archived
                ok: false
      security:
      - slackAuth:
        - channels:write
      summary: Slack Post Conversations Join
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /conversations.kick:
    post:
      tags:
      - Conversations
      description: Removes a user from a conversation.
      externalDocs:
        description: API method documentation
        url: https://api.slack.com/methods/conversations.kick
      operationId: postConversationsKick
      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 remove user from.
                user:
                  type: string
                  description: User ID to be removed.
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  description: ID of conversation to remove user from.
                user:
                  type: string
                  description: User ID to be removed.
      responses:
        '200':
          description: Typical success response
          content:
            application/json:
              schema:
                title: conversations.kick success schema
                required:
                - ok
                type: object
                properties:
                  ok:
                    $ref: '#/components/schemas/defs_ok_true'
                additionalProperties: false
                description: Schema for successful response conversations.kick method
              example:
                ok: true
        default:
          description: Typical error response when you attempt to kick yourself from a channel
          content:
            application/json:
              schema:
                title: conversations.kick 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
                    - channel_not_found
                    - user_not_found
                    - cant_kick_self
                    - not_in_channel
                    - cant_kick_from_general
                    - restricted_action
                    - 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
                    - 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 conversations.kick method
              example:
                error: cant_kick_self
                ok: false
      security:
      - slackAuth:
        - channels:write
        - groups:write
        - im:write
        - mpim:write

# --- truncated at 32 KB (102 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/slack/refs/heads/main/openapi/slack-conversations-api-openapi.yml