Skip to main content

​
Overview

The Channels API allows you to create, update, and delete channels in your organization. Channels can be public, private, direct messages (DMs), group messages, or threads. All channel operations require authentication and appropriate permissions.

​
Channel Types

  • public - Visible to all organization members
  • private - Only visible to invited members
  • direct - Group direct message with multiple participants
  • single - One-on-one direct message between two users
  • thread - Conversation thread attached to a message

​
Methods

​
channel.create

Creates a new channel in an organization. The current user is automatically added as a member of the channel.
​
name
string
required
Channel name
​
type
ChannelType
required
Channel type: public, private, thread, direct, or single
​
organizationId
string
required
UUID of the organization
​
icon
string | null
Channel icon/emoji
​
parentChannelId
string | null
Parent channel ID (for threads)
​
sectionId
string | null
Section ID to organize the channel
​
id
string
Optional client-provided ID for optimistic updates
​
addAllMembers
boolean
If true, automatically adds all organization members to the channel
​
data
Channel
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channel.create({
  name: "General",
  type: "public",
  organizationId: "org-123",
  icon: "💬",
  addAllMembers: true
});
Errors:
  • UnauthorizedError - User lacks permission to create channels
  • InternalServerError - Unexpected server error

​
channel.update

Updates an existing channel. Only users with appropriate permissions can update a channel.
​
id
string
required
Channel ID to update
​
name
string
New channel name
​
icon
string | null
New channel icon/emoji
​
sectionId
string | null
Move channel to a different section
​
data
Channel
Updated channel object (see channel.create for structure)
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channel.update({
  id: "ch-abc123",
  name: "General Discussion",
  icon: "💬"
});
Errors:
  • ChannelNotFoundError - Channel doesn’t exist
  • UnauthorizedError - User lacks permission to update channel
  • InternalServerError - Unexpected server error

​
channel.delete

Deletes a channel (soft delete). Only users with appropriate permissions can delete a channel.
​
id
string
required
Channel ID to delete
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channel.delete({
  id: "ch-abc123"
});
Errors:
  • ChannelNotFoundError - Channel doesn’t exist
  • UnauthorizedError - User lacks permission to delete channel
  • InternalServerError - Unexpected server error

​
channel.createDm

Creates a direct message or group channel with specified participants. For single DMs, automatically checks if a DM already exists between users. All participants are automatically added as channel members.
​
participantIds
string[]
required
Array of user IDs to include in the DM (excluding yourself)
​
type
'direct' | 'single'
required
  • single - One-on-one DM (must have exactly 1 participant)
  • direct - Group DM (can have multiple participants)
​
organizationId
string
required
UUID of the organization
​
name
string
Optional custom name for the DM channel (auto-generated for single DMs)
​
data
Channel
Created DM channel object
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channel.createDm({
  participantIds: ["user-456"],
  type: "single",
  organizationId: "org-123"
});
// Creates a DM named "Alice Smith, Bob Jones"
Errors:
  • DmChannelAlreadyExistsError - DM already exists (for single type)
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error or invalid participant count

​
channel.createThread

Ensures a thread channel exists for a message and returns it. If a thread already exists, it is returned. Otherwise this atomically creates the thread channel, adds the creator as a member, and links the original message to the thread.
​
messageId
string
required
ID of the message to create a thread for
​
organizationId
string
Optional organization ID (must match message’s parent channel organization)
​
id
string
Optional client-provided channel ID for optimistic updates
​
data
Channel
Thread channel object
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channel.createThread({
  messageId: "msg-abc123"
});
Errors:
  • MessageNotFoundError - Message doesn’t exist
  • NestedThreadError - Cannot create thread from a message that’s already in a thread
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error

​
channel.generateName

Generates an AI-powered name for a thread channel. Uses the ThreadNamingWorkflow to analyze the thread conversation and generate a descriptive 3-6 word name.
​
channelId
string
required
Thread channel ID to generate a name for
​
success
boolean
Whether the name generation was initiated successfully
const result = await client.channel.generateName({
  channelId: "ch-thread-xyz"
});
Note: This operation is asynchronous. The thread name will be updated in the background via a workflow. Errors:
  • ChannelNotFoundError - Channel doesn’t exist or is not a thread
  • MessageNotFoundError - Original message not found
  • UnauthorizedError - User lacks permission
  • WorkflowServiceUnavailableError - Cannot connect to workflow service
  • ThreadChannelNotFoundError - Thread channel not found in workflow
  • OriginalMessageNotFoundError - Original message not found in workflow
  • ThreadContextQueryError - Database query failed in workflow
  • AIProviderUnavailableError - AI service is unreachable
  • AIRateLimitError - AI service rate limit exceeded
  • AIResponseParseError - AI response cannot be parsed
  • ThreadNameUpdateError - Database update failed in workflow
  • InternalServerError - Unexpected server error

Build docs developers (and LLMs) love

Get started for freeTalk to us