Skip to main content

​
Overview

The Channel Sections API allows you to create, update, and manage channel sections within your organization. Sections help organize channels into logical groups (e.g., “Engineering”, “Marketing”, “Support”). Sections are organization-wide and visible to all members. Only organization admins/owners can manage sections.

​
Methods

​
channelSection.create

Creates a new channel section in an organization. Only organization admins/owners can create sections.
​
name
string
required
Section name (e.g., “Engineering”, “Marketing”)
​
organizationId
string
required
UUID of the organization
​
order
number
required
Display order (0-based). If set to 0, automatically assigned to end.
​
id
string
Optional client-provided ID for optimistic updates
​
data
ChannelSection
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channelSection.create({
  name: "Engineering",
  organizationId: "org-123",
  order: 0 // Auto-assigned to end
});
Errors:
  • UnauthorizedError - User lacks admin permission
  • InternalServerError - Unexpected server error

​
channelSection.update

Updates an existing channel section (rename, change order). Only organization admins/owners can update sections.
​
id
string
required
Section ID to update
​
name
string
New section name
​
order
number
New display order
​
data
ChannelSection
Updated section object (see channelSection.create for structure)
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channelSection.update({
  id: "cs-abc123",
  name: "Engineering Team"
});
Errors:
  • ChannelSectionNotFoundError - Section doesn’t exist
  • UnauthorizedError - User lacks admin permission
  • InternalServerError - Unexpected server error

​
channelSection.delete

Deletes a channel section (soft delete). When a section is deleted, all channels in that section are moved to the default section (sectionId = null). Only organization admins/owners can delete sections.
​
id
string
required
Section ID to delete
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channelSection.delete({
  id: "cs-abc123"
});
Note: All channels in the deleted section are automatically moved to the default section. Errors:
  • ChannelSectionNotFoundError - Section doesn’t exist
  • UnauthorizedError - User lacks admin permission
  • InternalServerError - Unexpected server error

​
channelSection.reorder

Reorders all sections in an organization. Takes an ordered array of section IDs and updates their order field accordingly. Only organization admins/owners can reorder sections.
​
organizationId
string
required
Organization ID
​
sectionIds
string[]
required
Ordered array of section IDs (from top to bottom)
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channelSection.reorder({
  organizationId: "org-123",
  sectionIds: [
    "cs-abc123", // First
    "cs-def456", // Second
    "cs-ghi789"  // Third
  ]
});
Errors:
  • UnauthorizedError - User lacks admin permission
  • InternalServerError - Unexpected server error

​
channelSection.moveChannel

Moves a channel to a different section. Set sectionId to null to move channel back to the default section. Only organization admins/owners can move channels between sections.
​
channelId
string
required
Channel ID to move
​
sectionId
string | null
required
Target section ID, or null for default section
​
transactionId
string
Transaction ID for optimistic updates
const result = await client.channelSection.moveChannel({
  channelId: "ch-abc123",
  sectionId: "cs-engineering"
});
Errors:
  • ChannelNotFoundError - Channel doesn’t exist
  • ChannelSectionNotFoundError - Section doesn’t exist or belongs to different organization
  • UnauthorizedError - User lacks admin permission
  • InternalServerError - Unexpected server error

​
Complete Example

// Create sections
const engineering = await client.channelSection.create({
  name: "Engineering",
  organizationId: "org-123",
  order: 0
});

const marketing = await client.channelSection.create({
  name: "Marketing",
  organizationId: "org-123",
  order: 0
});

// Create channels
const backend = await client.channel.create({
  name: "backend",
  type: "public",
  organizationId: "org-123"
});

const frontend = await client.channel.create({
  name: "frontend",
  type: "public",
  organizationId: "org-123"
});

// Organize channels into sections
await client.channelSection.moveChannel({
  channelId: backend.data.id,
  sectionId: engineering.data.id
});

await client.channelSection.moveChannel({
  channelId: frontend.data.id,
  sectionId: engineering.data.id
});

// Reorder sections
await client.channelSection.reorder({
  organizationId: "org-123",
  sectionIds: [engineering.data.id, marketing.data.id]
});

Build docs developers (and LLMs) love

Get started for freeTalk to us