Skip to main content
The Chat Sync API allows you to bidirectionally sync messages between Hazel Chat and external chat platforms (Slack, Discord, etc.). This enables seamless communication across different platforms.

​
Overview

Chat Sync consists of two main resources:
  • Connections - Links to external workspaces (e.g., a Slack workspace)
  • Channel Links - Mappings between Hazel channels and external channels

​
Sync Directions

Channel links support three sync directions:
  • both - Bidirectional sync (default)
  • inbound - Only sync messages from external platform to Hazel
  • outbound - Only sync messages from Hazel to external platform

​
Supported Providers

  • Slack
  • Discord
  • Microsoft Teams (coming soon)

​
Connection Management

​
Create Connection

Create a connection to an external workspace. 
import { chatSync } from "@hazel/domain/rpc"

const result = await chatSync.connection.create({
  organizationId: "org_123",
  provider: "slack",
  externalWorkspaceId: "T12345678",
  externalWorkspaceName: "Acme Corp",
  integrationConnectionId: "int_conn_123", // Optional OAuth connection
  settings: {
    syncThreads: true,
    syncReactions: true
  }
})
​
organizationId
OrganizationId
required
The organization to create the connection for
​
provider
'slack' | 'discord' | 'teams'
required
The external platform provider
​
externalWorkspaceId
string
required
The workspace ID on the external platform
​
externalWorkspaceName
string
Display name for the external workspace
​
integrationConnectionId
IntegrationConnectionId
Associated OAuth integration connection
​
settings
Record<string, unknown>
Provider-specific sync settings
​
metadata
Record<string, unknown>
Additional metadata for the connection
Response
​
data
ChatSyncConnection
The created connection
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors
  • ChatSyncConnectionExistsError - Connection already exists for this workspace
  • ChatSyncIntegrationNotConnectedError - Integration not connected
  • UnauthorizedError - Not authorized
  • InternalServerError - Server error

​
List Connections

List all sync connections for an organization. 
const connections = await chatSync.connection.list({
  organizationId: "org_123"
})

​
Delete Connection

Delete a sync connection and all its channel links. 
await chatSync.connection.delete({
  syncConnectionId: "sync_conn_123"
})
Deleting a connection will permanently remove all channel links. Messages that have already been synced will not be deleted.
Link a Hazel channel to an external channel. 
const link = await chatSync.channelLink.create({
  syncConnectionId: "sync_conn_123",
  hazelChannelId: "ch_456",
  externalChannelId: "C12345678",
  externalChannelName: "#general",
  direction: "both",
  settings: {
    syncPins: true,
    mentionMapping: true
  }
})
​
syncConnectionId
SyncConnectionId
required
The parent sync connection
​
hazelChannelId
ChannelId
required
The Hazel channel to sync
​
externalChannelId
ExternalChannelId
required
The external channel ID
​
externalChannelName
string
Display name of the external channel
​
direction
'both' | 'inbound' | 'outbound'
Sync direction (default: both)
​
settings
Record<string, unknown>
Channel-specific sync settings
List all channel links for a connection. 
const links = await chatSync.channelLink.list({
  syncConnectionId: "sync_conn_123"
})
Update a channel link’s settings or direction. 
const updated = await chatSync.channelLink.update({
  syncChannelLinkId: "link_789",
  direction: "inbound",
  isActive: true
})
Remove a channel link to stop syncing. 
await chatSync.channelLink.delete({
  syncChannelLinkId: "link_789"
})

​
Use Cases

​
Cross-Platform Teams

Sync channels between Hazel and Slack for teams using both platforms: 
// Connect to Slack workspace
const slackConnection = await chatSync.connection.create({
  organizationId: "org_123",
  provider: "slack",
  externalWorkspaceId: "T12345678",
  externalWorkspaceName: "Engineering Team"
})

// Link general channels
await chatSync.channelLink.create({
  syncConnectionId: slackConnection.data.id,
  hazelChannelId: "ch_general",
  externalChannelId: "C987654321",
  direction: "both"
})

​
Inbound Announcements

Sync announcements from Slack to Hazel in read-only mode: 
await chatSync.channelLink.create({
  syncConnectionId: slackConnection.data.id,
  hazelChannelId: "ch_announcements",
  externalChannelId: "C111111111",
  direction: "inbound" // Only Slack → Hazel
})

​
Discord Community Bridge

Connect Discord community to Hazel for support: 
const discordConnection = await chatSync.connection.create({
  organizationId: "org_123",
  provider: "discord",
  externalWorkspaceId: "987654321098765432",
  externalWorkspaceName: "Community Server"
})

await chatSync.channelLink.create({
  syncConnectionId: discordConnection.data.id,
  hazelChannelId: "ch_support",
  externalChannelId: "123456789012345678",
  direction: "both"
})

​
Best Practices

Use descriptive connection names to easily identify which external workspace each connection represents.
Be careful with bidirectional sync to avoid message loops. Test with a single channel first before syncing multiple channels.
Sync typically happens within 1-2 seconds. Large message backlogs may take longer to sync initially.

Channels API

Manage Hazel channels

Messages API

Send and manage messages

Organizations API

Manage organizations

Build docs developers (and LLMs) love

Get started for freeTalk to us