Conversation object

A conversation object contains information about a channel-like thing in Slack. It might be a public channel, a private channel, a direct message, a multi-person direct message, or a huddle. You'll find all of these objects throughout the Conversations API. Different fields are included in the object payload depending on the type of conversation (channel, DM, MPIM, etc.). The legacy objects—channel, group, im, and mpim—reference pages are nested under this one for posterity, but they are all now represented by the conversation object.

Example responses

An example response for the conversations.info method is as follows:

{
    "channel": {
        "id": "C123456",
        "name": "general",
        "is_channel": true,
        "is_group": false,
        "is_im": false,
        "is_mpim": false,
        "is_private": false,
        "created": 1449252889,
        "is_archived": false,
        "is_general": true,
        "unlinked": 0,
        "name_normalized": "general",
        "is_shared": false,
        "is_frozen": false,
        "is_org_shared": false,
        "is_pending_ext_shared": false,
        "pending_shared": [],
        "context_team_id": "T12345ABCDE",
        "updated": 1689965803820,
        "parent_conversation": null,
        "creator": "W123456",
        "is_ext_shared": false,
        "shared_team_ids": [
            "T12345ABCDE"
        ],
        "pending_connected_team_ids": [],
        "is_member": true,
        "topic": {
            "value": "For public discussion of generalities",
            "creator": "W123456",
            "last_set": 1449709364
        },
        "purpose": {
            "value": "This part of the workspace is for fun. Make fun here.",
            "creator": "W123456",
            "last_set": 1449709364
        },
        "properties": {
            "posting_restricted_to": {
                "type": [
                    "admin"
                ]
            },
            "threads_restricted_to": {
                "type": [
                    "ra"
                ]
            },
            "tabs": [
                {
                    "id": "files",
                    "label": "",
                    "type": "files"
                },
                {
                    "id": "bookmarks",
                    "label": "",
                    "type": "bookmarks"
                }
            ]
        },
        "previous_names": [
            "specifics",
            "abstractions",
            "etc"
        ]
    }
}

An example response for the conversations.history method is as follows:

{
    "messages": [
        {
            "type": "message",
            "text": "",
            "user": "USLACKBOT",
            "channel": "C12345ABCDE",
            "room": {
                "id": "R12345ABCDE",
                "name": "",
                "media_server": "",
                "created_by": "U12345ABCDE",
                "date_start": 1689964161,
                "date_end": 0,
                "participants": [],
                "participant_history": [
                    "U12345ABCDE"
                ],
                "participants_camera_on": [],
                "participants_camera_off": [],
                "participants_screenshare_on": [],
                "participants_screenshare_off": [],
                "canvas_thread_ts": "1689964161.419229",
                "thread_root_ts": "1689964161.419229",
                "channels": [
                    "C12345ABCDE"
                ],
                "is_dm_call": false,
                "was_rejected": false,
                "was_missed": false,
                "was_accepted": false,
                "has_ended": false,
                "background_id": "GRADIENT_03",
                "canvas_background": "GRADIENT_03",
                "is_prewarmed": false,
                "is_scheduled": false,
                "attached_file_ids": [],
                "media_backend_type": "free_willy",
                "display_id": "",
                "external_unique_id": "12345abc-123a-123b-123c-12345abcde7",
                "app_id": "A00",
                "call_family": "huddle",
                "pending_invitees": {},
                "last_invite_status_by_user": {}
            },
            "no_notifications": true,
            "permalink": "https://example.com",
            "subtype": "huddle_thread",
            "ts": "1689964161.419229",
            "blocks": [
                {
                    "type": "rich_text",
                    "block_id": "aBcDe",
                    "elements": [
                        {
                            "type": "rich_text_section",
                            "elements": [
                                {
                                    "type": "text",
                                    "text": "A huddle started"
                                }
                            ]
                        }
                    ]
                }
            ],
            "team": "T12345ABCDE"
        },
        // ...
    ]
}

Conversation-related booleans

Property	Description
has_pins	Whether a channel has pinned items.
is_archived	Indicates a conversation is archived, frozen in time.
is_channel	Indicates whether a conversation is a channel. Private channels created before March 2021 (with IDs that begin with G) will return false, and is_group will be true instead. Use is_private to determine whether a channel is private or public.
is_channel_agent_enabled	Whether a channel agent is enabled for this channel.
is_ext_shared	Indicates whether a conversation is part of a Shared Channel with a remote organization. Your app should make sure the data it shares in such a channel is appropriate for both workspaces. is_shared will also be true.
is_ext_ws_shared	Whether the channel is shared on an external workspace.
is_file	Whether this is a file channel.
is_frozen	Whether the conversation is frozen (e.g. a disconnected Slack Connect channel becomes a read-only frozen copy on the away-team side).
is_general	Means the channel is the workspace's "general" discussion channel (even if it may not be named #general). That might be important to your app because almost every user is a member.
is_group	Means the channel is a private channel created before March 2021. is_private will also be true.
is_im	Means the conversation is a direct message between two distinguished individuals or a user and a bot. is_private will also be true.
is_member	Indicates whether the user, bot user or Slack app associated with the token making the API call is itself a member of the conversation.
is_non_threadable	Indicates if threads are disabled on this conversation.
is_open	Whether a DM is open; this field is DM/MPIM-specific.
is_mpim	Represents an unnamed private conversation between multiple users. is_private will also be true.
is_org_default	Whether this conversation is an org-wide default channel, meaning it is shared with all workspaces in the Enterprise org (all new members are automatically added).
is_org_mandatory	Whether this conversation is a mandatory channel for all members in the Enterprise org. Members cannot leave mandatory channels.
is_org_shared	Indicates whether this shared channel is shared between Enterprise organization workspaces within the same organization. It's a little different from (externally) shared channels, yet is_shared will be true.
is_pending_ext_shared	Means the conversation is ready to become an is_ext_shared channel, but needs some kind of approval or sign off first. Best to treat it as if it were a shared channel, even if it traverses only one workspace.
is_private	Means the conversation is privileged between two or more members. Ensure that you meet their privacy expectations.
is_read_only	Means the conversation can't be written to by the user performing the API call.
is_shared	Means the conversation is in some way shared between multiple workspaces. Look for is_ext_shared and is_org_shared to learn which kind it is, and if that matters, act accordingly.
is_starred	Whether the user has starred this channel.
is_thread_only	Means the conversation can't be written to by the user performing the API call, except to reply to messages in the channel.
num_members	The number of members in the conversation. num_members may not make an appearance in the response for conversation types like DMs, where the number of members is constant.

Other conversation-related attributes

Property	Type	Description
connected_team_ids	Array of team_id	Connected external team IDs.
context_team_id	String (team_id)	The ID of the workspace the conversation is within. Required field.
conversation_host_id	String	Appears on shared channel objects and indicates the "host" of the shared channel. The value may contain a workspace's ID (beginning with T) or an Enterprise organization's ID (beginning with E).
created	Int	Timestamp, in seconds, of when the conversation was created.
creator	String	The ID of the member that created this conversation.
enterprise_id	String	The Enterprise organization ID.
frozen_reason	String	Reason the channel is frozen (when is_frozen is true).
internal_team_ids	Array of workspace_id	Internal team IDs for shared channels.
is_moved	Integer	Timestamp when the channel was moved (Enterprise orgs).
name	String	Indicates the name of the channel-like thing, without a leading hash sign. Don't get too attached to that name; it may change — instead, when working with channel-like things, focus on their IDs, their type, and the team/workspace they belong to.
name_normalized	String	The normalized version of the channel name. Required field.
parent_conversation	String	The parent conversation ID, or null if there is none.
pending_connected_team_ids	Array of workspace_id	Pending connected team IDs.
pending_shared	Array of workspace_id	Pending shared workspace IDs.
previous_names	Array of strings	Previous names the channel has had.
purpose	Object	Provides information about the channel purpose. Structure is {value: string, creator: string, last_set: integer}.
retention_duration	Integer	The custom message retention duration for this conversation, in days. Only present when a custom retention policy has been set (via the admin.conversations.setCustomRetention method). When absent, the workspace or org default retention policy applies.
shared_team_ids	Array of workspace_id	IDs of workspaces the channel is shared with.
topic	Object	Provides information about the channel topic. Structure is {value: string, creator: string, last_set: integer}.
unlinked	Integer	Whether the channel was previously shared then disconnected.
updated	Int	The timestamp, in milliseconds (not seconds like created), when the channel settings were updated — for example, the "topic" or "description" of the channel changed.
use_case	String	Channel use-case classification.
user	String (user_id)	The other user's ID (DM-specific).

Some API methods; for example, conversations.join, can include extra state information for channels when the calling user is a member:

Property	Type	Description
last_read	Timestamp	The timestamp for the last message the calling user has read in this channel.
unread_count	Int	A full count of visible messages that the calling user has yet to read.
unread_count_display	Int	A count of messages that the calling user has yet to read that matter to them (excludes things like join/leave messages).
latest	String	The latest message in the channel. no_latest=true for non-first party requests.
properties	Object	Additional channel properties (see below).

The properties object contains many additional fields that appear based on the context of the object.

Property	Type	Description
at_channel_restricted	Boolean	Indicates if the @channel mention is restricted.
at_here_restricted	Boolean	Indicates if the @here mention is restricted.
auto_open_tab_id	String	Indicates which tab in the channel auto opens.
canvas	Object	The channel canvas.
channel_solutions	Object	Properties for channel solutions: workflow_trigger_ids, workflow_workflow_ids, canvas_ids, list_ids.
channel_workflows	Array	An array of workflows in the channel.
crm	Object	Properties for Slack CRM.
default_tab_id	String	Indicates which tab in the channel is the default.
huddles	Object	Properties for huddles for the channel the huddle occurred in.
huddles_restricted	Boolean	Indicates if huddles are restricted.
meeting_notes	Object	Properties for channel meeting notes.
membership_limit	Integer	Limit of users in channel.
posting_restricted_to	Object	An object comprised of three arrays: subteam, type, and user, each offering a different way to restrict who can post in the channel.
record_channel	Object	Properties for Salesforce channels.
sharing_disabled	Boolean	Indicates if sharing is disabled.
tabs	Object	List of channel tabs. Each tab has an id, label, type, data, and is_disabled property. Its type can be any of the following: list, canvas, files, bookmarks, folder, pins, workflows, channel_canvas, record_list, record_overview, record_summary, record_related_list,salesforce_list_view.
threads_restricted_to	Object	An object comprised of three arrays: subteam, type, and user, each offering a different way to restrict who can post in threads in the channel.
who_can_manage_channel_agent	String	Controls who can configure, add, or remove a channel agent for this conversation. Possible values: everyone, channel_managers.
workflow	Object	Properties for a workflow; currently contains one field, primary_workflow_url.

These channel objects are not the same object type as those for private channels created before March 2021, which are considered group objects.