Closes direct messages, multi-person or 1:1 or otherwise.

Required Params

• channel - Conversation to close. ex: G1234567890

Errors the API can return:

• channel_not_found - Value passed for channel was invalid

Initiates a public or private channel-based conversation.

Required Params

• name - Name of the public or private channel to create. ex: mychannel

Optional Params

• is_private - Create a private channel instead of a public one. ex: true
• user_ids - Required for workspace apps. A list of between 1 and 30 human users that will be added to the newly-created conversation. This argument has no effect when used by classic Xlack apps. ex: W1234567890,U2345678901,U3456789012

Errors the API can return:

• account_inactive - Authentication token is for a deleted user or workspace.
• ekm_access_denied - Administrators have suspended the ability to post a message.
• fatal_error - The server could not complete your operation(s) without encountering a catastrophic error. It's possible some aspect of the operation succeeded before the error was raised.
• internal_error - The server could not complete your operation(s) without encountering an error, likely due to a transient issue on our end. It's possible some aspect of the operation succeeded before the error was raised.
• invalid_arg_name - The method was passed an argument whose name falls outside the bounds of accepted or expected values. This includes very long names and names with non-alphanumeric characters other than _. If you get this error, it is typically an indication that you have made a very malformed API call.
• invalid_arguments - The method was called with invalid arguments.
• invalid_auth - Some aspect of authentication cannot be validated. Either the provided token is invalid or the request originates from an IP address disallowed from making the request.
• invalid_charset - The method was called via a POST request, but the charset specified in the Content-Type header was invalid. Valid charset names are: utf-8 iso-8859-1.
• invalid_form_data - The method was called via a POST request with Content-Type application/x-www-form-urlencoded or multipart/form-data, but the form data was either missing or syntactically invalid.
• invalid_name - Value passed for name was invalid.
• invalid_name_maxlength - Value passed for name exceeded max length.
• invalid_name_punctuation - Value passed for name contained only punctuation.
• invalid_name_required - Value passed for name was empty.
• invalid_name_specials - Value passed for name contained unallowed special characters or upper case characters.
• invalid_post_type - The method was called via a POST request, but the specified Content-Type was invalid. Valid types are: application/json application/x-www-form-urlencoded multipart/form-data text/plain.
• invalid_users - Value passed for user_ids was empty or invalid.
• is_bot - This method cannot be called by a bot user.
• missing_post_type - The method was called via a POST request and included a data payload, but the request did not include a Content-Type header.
• missing_scope - The token used is not granted the specific scope permissions required to complete this request.
• name_taken - A channel cannot be created with the given name.
• no_channel - Value passed for name was empty.
• no_permission - The workspace token used in this request does not have the permissions necessary to complete the request. Make sure your app is a member of the conversation it's attempting to post a message to.
• not_authed - No authentication token provided.
• org_login_required - The workspace is undergoing an enterprise migration and will not be available until migration is complete.
• request_timeout - The method was called via a POST request, but the POST data was either missing or truncated.
• restricted_action - A team preference prevents the authenticated user from creating channels.
• team_added_to_org - The workspace associated with your request is currently undergoing migration to an Enterprise Organization. Web API and other platform operations will be intermittently unavailable until the transition is complete.
• token_revoked - Authentication token is for a deleted user or workspace or the app has been removed.
• too_many_convos_for_app_on_team - This app has exceeded its per-workspace limit of public and private channels.
• too_many_convos_for_team - The workspace has exceeded its limit of public and private channels.
• user_is_ultra_restricted - This method cannot be called by a single channel guest.
• user_not_found - One or more users in user_ids was not found.

Returns a portion of message events from the specified conversation.

Bot user tokens may use this method for direct message and multi-party direct message conversations but lack sufficient permissions to use this method on public and private channels.

Required Params

• channel - Conversation ID to fetch history for. ex: G1234567890

Optional Params

• cursor - 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 for more detail. ex: dXNlcjpVMDYxTkZUVDI=
• inclusive - Include messages with latest or oldest timestamp in results only when either timestamp is specified. ex: true
• latest - End of time range of messages to include in results. ex: 1234567890.123456
• limit - 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. ex: 20
• oldest - Start of time range of messages to include in results. ex: 1234567890.123456

Errors the API can return:

• channel_not_found - Value passed for channel was invalid

Returns information about a workspace conversation.

Required Params

• channel - Conversation ID to learn more about. ex: G1234567890

Optional Params

• include_locale - Set this to true to receive the locale for this conversation. Defaults to false ex: true
• include_num_members - Set to true to include the member count for the specified conversation. Defaults to false ex: true

Errors the API can return:

• channel_not_found - Value passed for channel was invalid

Invites users to a channel.

Required Params

• channel - The ID of the public or private channel to invite user(s) to. ex: C1234567890
• users - A comma separated list of user IDs. Up to 1000 users may be listed. ex: W1234567890,U2345678901,U3456789012

Errors the API can return:

• account_inactive - Authentication token is for a deleted user or workspace.
• already_in_channel - Invited user is already in the channel.
• cant_invite - User cannot be invited to this channel.
• cant_invite_self - Authenticated user cannot invite themselves to a channel.
• channel_not_found - Value passed for channel was invalid.
• ekm_access_denied - Administrators have suspended the ability to post a message.
• fatal_error - The server could not complete your operation(s) without encountering a catastrophic error. It's possible some aspect of the operation succeeded before the error was raised.
• internal_error - The server could not complete your operation(s) without encountering an error, likely due to a transient issue on our end. It's possible some aspect of the operation succeeded before the error was raised.
• invalid_arg_name - The method was passed an argument whose name falls outside the bounds of accepted or expected values. This includes very long names and names with non-alphanumeric characters other than _. If you get this error, it is typically an indication that you have made a very malformed API call.
• invalid_arguments - The method was called with invalid arguments.
• invalid_auth - Some aspect of authentication cannot be validated. Either the provided token is invalid or the request originates from an IP address disallowed from making the request.
• invalid_charset - The method was called via a POST request, but the charset specified in the Content-Type header was invalid. Valid charset names are: utf-8 iso-8859-1.
• invalid_form_data - The method was called via a POST request with Content-Type application/x-www-form-urlencoded or multipart/form-data, but the form data was either missing or syntactically invalid.
• invalid_post_type - The method was called via a POST request, but the specified Content-Type was invalid. Valid types are: application/json application/x-www-form-urlencoded multipart/form-data text/plain.
• invitee_cant_see_channel - The Grid multi-workspace channel you are inviting a user to is not shared with any workspaces the user is currently a member of.
• is_archived - Channel has been archived.
• is_bot - This method cannot be called by a bot user.
• method_not_supported_for_channel_type - This type of conversation cannot be used with this method.
• missing_post_type - The method was called via a POST request and included a data payload, but the request did not include a Content-Type header.
• missing_scope - The token used is not granted the specific scope permissions required to complete this request.
• no_permission - The workspace token used in this request does not have the permissions necessary to complete the request. Make sure your app is a member of the conversation it's attempting to post a message to.
• no_user - No value was passed for users.
• not_authed - No authentication token provided.
• not_in_channel - Authenticated user is not in the channel.
• org_login_required - The workspace is undergoing an enterprise migration and will not be available until migration is complete.
• request_timeout - The method was called via a POST request, but the POST data was either missing or truncated.
• team_added_to_org - The workspace associated with your request is currently undergoing migration to an Enterprise Organization. Web API and other platform operations will be intermittently unavailable until the transition is complete.
• token_revoked - Authentication token is for a deleted user or workspace or the app has been removed.
• ura_max_channels - URA is already in the maximum number of channels.
• user_is_ultra_restricted - This method cannot be called by a single channel guest.
• user_not_found - Value passed for users was invalid.

Joins an existing conversation

Required Params

• channel - ID of conversation to join ex: C1234567890

Errors the API can return:

• account_inactive - Authentication token is for a deleted user or workspace.
• channel_not_found - Value passed for channel was invalid.
• deprecated_endpoint - The endpoint has been deprecated.
• ekm_access_denied - Administrators have suspended the ability to post a message.
• fatal_error - The server could not complete your operation(s) without encountering a catastrophic error. It's possible some aspect of the operation succeeded before the error was raised.
• internal_error - The server could not complete your operation(s) without encountering an error, likely due to a transient issue on our end. It's possible some aspect of the operation succeeded before the error was raised.
• invalid_arg_name - The method was passed an argument whose name falls outside the bounds of accepted or expected values. This includes very long names and names with non-alphanumeric characters other than _. If you get this error, it is typically an indication that you have made a very malformed API call.
• invalid_arguments - The method was either called with invalid arguments or some detail about the arguments passed are invalid, which is more likely when using complex arguments like blocks or attachments.
• invalid_auth - Some aspect of authentication cannot be validated. Either the provided token is invalid or the request originates from an IP address disallowed from making the request.
• invalid_charset - The method was called via a POST request, but the charset specified in the Content-Type header was invalid. Valid charset names are: utf-8 iso-8859-1.
• invalid_form_data - The method was called via a POST request with Content-Type application/x-www-form-urlencoded or multipart/form-data, but the form data was either missing or syntactically invalid.
• invalid_post_type - The method was called via a POST request, but the specified Content-Type was invalid. Valid types are: application/json application/x-www-form-urlencoded multipart/form-data text/plain.
• is_archived - Channel has been archived.
• is_bot - This method cannot be called by a bot user.
• method_deprecated - The method has been deprecated.
• method_not_supported_for_channel_type - This type of conversation cannot be used with this method.
• missing_post_type - The method was called via a POST request and included a data payload, but the request did not include a Content-Type header.
• missing_scope - The token used is not granted the specific scope permissions required to complete this request.
• no_permission - The workspace token used in this request does not have the permissions necessary to complete the request. Make sure your app is a member of the conversation it's attempting to post a message to.
• not_allowed_token_type - The token type used in this request is not allowed.
• not_authed - No authentication token provided.
• org_login_required - The workspace is undergoing an enterprise migration and will not be available until migration is complete.
• ratelimited - The request has been ratelimited. Refer to the Retry-After header for when to retry the request.
• request_timeout - The method was called via a POST request, but the POST data was either missing or truncated.
• service_unavailable - The service is temporarily unavailable
• team_added_to_org - The workspace associated with your request is currently undergoing migration to an Enterprise Organization. Web API and other platform operations will be intermittently unavailable until the transition is complete.
• token_revoked - Authentication token is for a deleted user or workspace or the app has been removed.
• too_many_members - The membership in the channel has exceeded our maximum member limit. No more users can join the channel.
• user_is_restricted - This method cannot be called by a restricted user or single channel guest.

Returns a list of all channel-like conversations in a workspace.

Optional Params

• cursor - 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 for more detail. ex: dXNlcjpVMDYxTkZUVDI=
• exclude_archived - Set this to true to exclude archived channels from the list ex: true
• limit - The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the list hasn't been reached. Must be an integer no larger than 1000. ex: 20
• types - Mix and match channel types by providing a comma-separated list of any combination of public_channel, private_channel, mpim, im ex: public_channel,private_channel

Errors the API can return:

• invalid_cursor - Value passed for cursor was invalid.
• invalid_limit - Value passed for limit was invalid.
• invalid_types - Value passed for type could not be used based on the method's capabilities or the permission scopes granted to the used token.
• method_not_supported_for_channel_type - This type of conversation cannot be used with this method.

Returns a paginated list of members party to a conversation.

Required Params

• channel - ID of the conversation to retrieve members for ex: G1234567890

Optional Params

• cursor - 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 for more detail. ex: dXNlcjpVMDYxTkZUVDI=
• exclude_archived - Set this to true to exclude archived channels from the list ex: true
• limit - The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the list hasn't been reached. ex: 20

Errors the API can return:

• channel_not_found - Value passed for channel was invalid.
• fetch_members_failed - Failed to fetch members for the conversation.
• invalid_cursor - Value passed for cursor was invalid.
• invalid_limit - Value passed for limit was invalid.
• method_not_supported_for_channel_type - This type of conversation cannot be used with this method.

Opens a multi-person direct message or just a 1:1 direct message.

Optional Params

• channel - Resume a conversation by supplying an im or mpim's ID. Or provide the users field instead. ex: G1234567890
• return_im - Boolean, indicates you want the full IM channel definition in the response. ex: true
• users - Comma separated lists of users. If only one user is included, this creates a 1:1 DM. The ordering of the users is preserved whenever a multi-person direct message is returned. Supply a channel when not supplying users. ex: W1234567890,U2345678901,U3456789012

Errors the API can return:

• channel_not_found - Value passed for channel was invalid
• method_not_supported_for_channel_type - This type of conversation cannot be used with this method.
• not_enough_users - Needs at least 2 users to open
• too_many_users - Needs at most 8 users to open
• user_disabled - A specified user has been disabled
• user_not_found - Value(s) passed for users was invalid
• user_not_visible - The calling user is restricted from seeing the requested user.
• users_list_not_supplied - Missing users in request

Returns an entire thread (a message plus all the messages in reply to it), while conversations.history method returns only parent messages.

Bot user tokens may use this method for direct message and multi-party direct message conversations but lack sufficient permissions to use this method on public and private channels.

Required Params

• channel - Conversation ID to fetch thread from. ex: G1234567890
• ts - Unique identifier of a thread's parent message. ex: 1234567890.123456

Optional Params

• cursor - 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 for more detail. ex: dXNlcjpVMDYxTkZUVDI=
• inclusive - Include messages with latest or oldest timestamp in results only when either timestamp is specified. ex: true
• latest - End of time range of messages to include in results. ex: 1234567890.123456
• limit - 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. ex: 20
• oldest - Start of time range of messages to include in results. ex: 1234567890.123456

Errors the API can return:

• channel_not_found - Value for channel was invalid
• invalid_cursor - Value passed for cursor was invalid.
• invalid_ts_latest - Value passed for latest was invalid.
• invalid_ts_oldest - Value passed for oldest was invalid.
• thread_not_found - Value for ts was missing or invalid

Change the purpose of a conversation. The calling user must be a member of the conversation. Not all conversation types may have a purpose set.

Required Params

• channel - Conversation to set the purpose of. ex: G1234567890
• purpose - A new, specialer purpose ex: My More Special Purpose

Errors the API can return:

• channel_not_found - Value passed for channel was invalid
• is_archived - Channel has been archived
• method_not_supported_for_channel_type - This type of conversation cannot be used with this method.
• not_in_channel - Authenticated user is not in the channel.
• too_long - Purpose was longer than 250 characters.
• user_is_restricted - This method cannot be called by a restricted user or single channel guest.

Change the topic of a conversation. The calling user must be a member of the conversation. Not all conversation types may have a purpose set.

Required Params

• channel - Conversation to set the purpose of. ex: G1234567890
• topic - The new topic string. Does not support formatting or linkification. ex: Apply topically for best effects

Errors the API can return:

• channel_not_found - Value passed for channel was invalid
• is_archived - Channel has been archived
• method_not_supported_for_channel_type - This type of conversation cannot be used with this method.
• not_in_channel - Authenticated user is not in the channel.
• too_long - Topic was longer than 250 characters.
• user_is_restricted - This method cannot be called by a restricted user or single channel guest.