Skip to main content

agents.conversations.create method

Facts​

DescriptionCreate a dedicated code channel for an agent session.
Method Access
POST https://slack.com/api/agents.conversations.create
Scopes
Content types
application/x-www-form-urlencoded
application/json
Rate LimitsSpecial rate limits apply.

Arguments​

Required arguments

tokenstringRequired

Authentication token bearing the code_channels:manage scope. Must be a granular bot token.

Example: xxxx-xxxxxxxxx-xxxx
namestringRequired

A friendly display name for the code channel. Optional when origin_channel_id and origin_message_ts are provided — in that case the channel is named from the origin message and re-titled automatically. Required when no origin link is given.

Example: Help me debug auth flow

Optional arguments

team_idstringOptional

Encoded team id to create the channel in. Required for org tokens when origin_channel_id is not provided. When omitted, the workspace is derived from the origin channel.

Example: T1234567890
session_idstringOptional

An opaque identifier for the agent session. When provided, the call is idempotent: if a channel already exists for this session_id, it is returned instead of creating a new one.

Example: ses_abc123
is_privatebooleanOptional

Whether the code channel is private. When omitted, the channel matches the privacy of origin_channel_id, or is public if no origin is given. An explicit value is always honored, even if it differs from the origin channel's privacy: passing false creates a public channel from a private origin.

Example: true
origin_channel_idstringOptional

The channel ID where the agent session was initiated from. Must be provided together with origin_message_ts. The channel must be accessible to the calling user and must not be externally shared (Slack Connect). When team_id is omitted with an org token, the channel is created in the same workspace as this origin channel.

Example: C1234567890
origin_message_tsstringOptional

The message timestamp in the origin channel that started the agent session. Must be provided together with origin_channel_id. The author of this message is automatically invited to the newly created code channel.

Example: 1234567890.123456

Usage info​

Your app can create a code channel from any message, but the most common flow is: a user @-mentions your agent, your app receives the app_mention event, and, when the request implies multi-step work, your app calls this method to spin up a dedicated channel automatically. Judge that from the request and its context; users shouldn't have to ask for a channel by name.

This method accepts bot tokens only. The calling bot user becomes the channel's agent. Calls with user tokens are rejected.

Pass origin_channel_id and origin_message_ts to link the session back to the triggering message. Slack automatically invites the author of the origin message to the new code channel; your app does not need to invite them separately. When you provide an origin link and omit is_private, Slack also sets the channel's privacy to match the origin channel and allows users who are members of the origin channel to join the code channel. This is the recommended default; it means the right people can find and follow the session without your app needing to manage invites.

If you pass is_private explicitly, Slack uses that value instead of the origin channel's privacy. For example, is_private: false creates a public code channel even when the origin message is in a private channel, so only set it when your app intends to override the origin's privacy.

The origin link must refer to a valid, accessible channel and an existing message. The origin link is recorded on the channel as the origin_link property, connecting the session back to the conversation it started from. If either origin_channel_id or origin_message_ts cannot be resolved, the request fails with invalid_origin_link and no channel is created.

When session_id is provided, the call is idempotent. If a channel already exists for that session, it is returned instead of creating a new one. This lets agent processes reconnect to their channel across retries or restarts.

The calling bot user is automatically attributed as the channel's agent and invited to the channel as part of creation.

Example request​

POST /api/agents.conversations.create
{
  "name": "Migrate billing cron to Temporal",
  "session_id": "ses_8675309",
  "origin_channel_id": "C1234567890",
  "origin_message_ts": "1717171717.123456"
}

Workspace selection on Enterprise Grid​

On an Enterprise Grid org, a channel lives in a specific workspace, so the method has to pick one:

  • Workspace-level tokens always create the channel in the token's workspace. The team_id is not needed; if you do send it, it must match the token's workspace or the call fails with team_not_found.
  • Org-level app tokens with team_id create the channel in that workspace. The workspace must belong to the caller's org (team_not_found is returned otherwise), and your app must be granted access to it (app_not_installed_on_team is returned otherwise).
  • Org-level app tokens without team_id derive a workspace, in order:
    • The origin channel's workspace, when origin_channel_id is provided, keeping the code channel next to the conversation it started from. This is the recommended way to omit team_id.
    • The creating user's default workspace.
    • Any workspace shared by the app and the creating user.

A fallback workspace is only used if your app has been granted access to it. If no workspace qualifies, the call fails with no_shared_workspace.

Pass team_id explicitly whenever your app knows which workspace the session belongs in; rely on the origin-channel derivation when creating from a mention.

Response​

Typical success response

{
  "ok": true,
  "channel_id": "C9876543210"
}

Typical error response

{
  "ok": false,
  "error": "feature_disabled"
}

Errors​

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok parameter in the response.

Error
Description
access_denied

Access to a resource specified in the request is denied.

accesslimited

Access to this method is limited on the current network

account_inactive

Authentication token is for a deleted user or workspace when using a bot token.

channel_creation_failed

The code channel could not be created.

channel_not_viewable

A channel exists for this session but the caller does not have permission to view it.

deprecated_endpoint

The endpoint has been deprecated.

ekm_access_denied

Administrators have suspended the ability to post a message.

enterprise_is_restricted

The method cannot be called from an Enterprise.

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.

feature_disabled

The caller is not authorized to create code channels. The app must be a recognized agent session app, or the user must have the feature enabled.

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_agent

The agent bot user associated with the calling app is not a valid bot.

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_array_arg

The method was passed an array as an argument. Please only input valid strings.

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_origin_link

The origin link is invalid. Either origin_channel_id and origin_message_ts were not provided together, the channel does not exist or is not accessible to the caller, or the message was not found at the given timestamp.

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.

invite_failed

The channel was created but the agent bot could not be invited.

method_deprecated

The method has been deprecated.

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_or_origin_required

A name must be provided unless an origin link (origin_channel_id and origin_message_ts) is given to derive the channel name from.

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_shared_workspace

No workspace could be found where both the app and the requesting user are present. The org app must have a workspace grant for at least one workspace the user belongs to.

not_allowed_token_type

The token type used in this request is not allowed.

not_authed

No authentication token provided.

open_failed

The channel was created but could not be opened in the sidebar.

org_login_required

The workspace is undergoing an enterprise migration and will not be available until migration is complete.

origin_channel_externally_shared

The origin message is in an externally shared (Slack Connect) channel, DM, or group DM. Code channels cannot be created from a Slack Connect conversation.

origin_channel_is_file_channel

The origin message is a comment on a file or canvas. Code channels cannot be created from a file channel — when the canvas belongs to a code channel, continue that session instead.

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.

restricted_action

The calling user is not permitted to create channels of the requested type in this workspace.

service_unavailable

The service is temporarily unavailable

team_access_not_granted

The token used is not granted the specific workspace access required to complete this request.

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_expired

Authentication token has expired

token_revoked

Authentication token is for a deleted user or workspace or the app has been removed when using a user token.

two_factor_setup_required

Two factor setup is required.

user_not_enabled

The author of the origin message does not have the code channels feature enabled.