Complete API reference for listing connected messaging channels, checking their status and capabilities, and reconnecting disconnected channels.

Channel API

Manage the messaging channels connected to your CodeSpar instance. CodeSpar supports five channels: WhatsApp, Slack, Discord, Telegram, and Web (API). Each channel can be independently enabled, monitored, and reconnected.

Endpoints Overview

Method	Path	Description
`GET`	`/api/channels`	List all channels with status and capabilities
`POST`	`/api/channels/:name/reconnect`	Force-reconnect a channel

List Channels

Retrieve all configured channels, their current connection status, and their capabilities.

GET /api/channels

Request

curl http://localhost:3000/api/channels

Response

{
  "channels": [
    {
      "name": "whatsapp",
      "platform": "whatsapp",
      "connected": true,
      "capabilities": {
        "threads": false,
        "codeBlocks": false,
        "syntaxHighlighting": false,
        "fileAttachments": true,
        "reactions": false,
        "maxMessageLength": 4096,
        "mentionFormat": "text"
      }
    },
    {
      "name": "slack",
      "platform": "slack",
      "connected": true,
      "capabilities": {
        "threads": true,
        "codeBlocks": true,
        "syntaxHighlighting": true,
        "fileAttachments": true,
        "reactions": true,
        "maxMessageLength": 40000,
        "mentionFormat": "user_id"
      }
    },
    {
      "name": "discord",
      "platform": "discord",
      "connected": false,
      "capabilities": {
        "threads": true,
        "codeBlocks": true,
        "syntaxHighlighting": true,
        "fileAttachments": true,
        "reactions": true,
        "maxMessageLength": 2000,
        "mentionFormat": "user_id"
      }
    },
    {
      "name": "telegram",
      "platform": "telegram",
      "connected": false,
      "capabilities": {
        "threads": false,
        "codeBlocks": false,
        "syntaxHighlighting": false,
        "fileAttachments": true,
        "reactions": false,
        "maxMessageLength": 4096,
        "mentionFormat": "username"
      }
    },
    {
      "name": "web",
      "platform": "web",
      "connected": true,
      "capabilities": {
        "threads": false,
        "codeBlocks": true,
        "syntaxHighlighting": true,
        "fileAttachments": false,
        "reactions": false,
        "maxMessageLength": 100000,
        "mentionFormat": "none"
      }
    }
  ]
}

Response Schema

Each channel object contains the following fields:

Field	Type	Description
`name`	string	Channel identifier: `whatsapp`, `slack`, `discord`, `telegram`, `web`
`platform`	string	Platform type. Same as `name` for built-in channels.
`connected`	boolean	Whether the channel is currently connected and processing messages
`capabilities`	object	Channel-specific capabilities (see below)

Capabilities Object

The capabilities object describes what each channel supports. CodeSpar uses this information to format messages appropriately for each channel.

Field	Type	Description
`threads`	boolean	Whether the channel supports threaded replies. Slack and Discord support threads; WhatsApp and Telegram do not.
`codeBlocks`	boolean	Whether the channel renders code blocks with monospace formatting.
`syntaxHighlighting`	boolean	Whether code blocks support language-specific syntax highlighting.
`fileAttachments`	boolean	Whether the channel can send and receive file attachments.
`reactions`	boolean	Whether the channel supports emoji reactions on messages.
`maxMessageLength`	number	Maximum characters per message. Messages exceeding this limit are automatically split.
`mentionFormat`	string	How the channel handles @mentions: `"text"` (raw text), `"user_id"` (platform user ID), `"username"` (platform username), `"none"` (no mentions).

How Capabilities Affect Behavior

CodeSpar adapts its output based on channel capabilities:

Capability	When `true`	When `false`
`threads`	Responses are posted as thread replies	Responses are posted as flat messages
`codeBlocks`	Code is wrapped in triple-backtick blocks	Code is sent as plain text
`syntaxHighlighting`	Language identifier is added to code blocks (e.g., ```typescript)	Code blocks use no language identifier
`maxMessageLength`	Messages within limit are sent as-is	Messages exceeding limit are split into multiple messages

Channel Connection States

The connected field is a boolean. For more detailed status information, the full internal states are:

State	`connected` Value	Description
Connected	`true`	Channel is online and processing messages
Disconnected	`false`	Channel lost connection or encountered an error
Disabled	`false`	Channel is not enabled in configuration
Connecting	`false`	Channel is attempting to establish connection (transitional)

Reconnect a Channel

Force a channel to disconnect and reconnect. Useful when a channel is stuck in a disconnected or error state.

POST /api/channels/:name/reconnect

Path Parameters

Parameter	Type	Description
`name`	string	Channel name: `whatsapp`, `slack`, `discord`, `telegram`

Request

curl -X POST http://localhost:3000/api/channels/discord/reconnect

Response

{
  "success": true,
  "channel": "discord",
  "connected": true
}

The connected field reflects the state after the reconnection attempt. If the reconnection fails (e.g., invalid token, service unavailable), connected will be false.

Verify Reconnection

After a reconnection attempt, verify the channel status:

curl http://localhost:3000/api/channels

Error Responses

Channel not found (404):

curl -X POST http://localhost:3000/api/channels/teams/reconnect

{
  "error": "Channel 'teams' not found. Valid channels: whatsapp, slack, discord, telegram",
  "code": "CHANNEL_NOT_FOUND",
  "status": 404
}

Channel not enabled (400):

curl -X POST http://localhost:3000/api/channels/telegram/reconnect

{
  "error": "Channel 'telegram' is not enabled. Set ENABLE_TELEGRAM=true to enable.",
  "code": "CHANNEL_DISABLED",
  "status": 400
}

Channel Configuration Reference

Each channel requires specific environment variables. See Configuration for full details.

Channel	Enable Variable	Required Variables
WhatsApp	`ENABLE_WHATSAPP=true`	`EVOLUTION_API_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE`
Slack	`ENABLE_SLACK=true`	`SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`
Discord	`ENABLE_DISCORD=true`	`DISCORD_BOT_TOKEN`
Telegram	`ENABLE_TELEGRAM=true`	`TELEGRAM_BOT_TOKEN`
Web	Always enabled	None (built-in REST API)

Usage Examples

Check If All Channels Are Connected

curl -s http://localhost:3000/api/channels | jq '.channels[] | {name, connected}'

{"name": "whatsapp", "connected": true}
{"name": "slack", "connected": true}
{"name": "discord", "connected": false}
{"name": "telegram", "connected": false}
{"name": "web", "connected": true}

Reconnect All Disconnected Channels

# Get disconnected channels and reconnect each one
for channel in $(curl -s http://localhost:3000/api/channels \
  | jq -r '.channels[] | select(.connected == false) | .name'); do
  echo "Reconnecting $channel..."
  curl -s -X POST "http://localhost:3000/api/channels/$channel/reconnect"
  echo ""
done

Check a Channel's Message Length Limit

curl -s http://localhost:3000/api/channels \
  | jq '.channels[] | select(.name == "discord") | .capabilities.maxMessageLength'

Configure a Channel

Programmatically configure a channel's connection settings. This is an alternative to setting environment variables manually.

POST /api/channels/configure

Request Body

Field	Type	Required	Description
`channel`	string	Yes	Channel name: `telegram`, `whatsapp`, `discord`, `slack`
`config`	object	Yes	Channel-specific configuration (see below)

Channel Config Objects

Telegram:

{
  "channel": "telegram",
  "config": {
    "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
  }
}

WhatsApp:

{
  "channel": "whatsapp",
  "config": {
    "evolutionApiUrl": "http://localhost:8084",
    "evolutionApiKey": "your-evolution-api-key",
    "evolutionInstance": "codespar"
  }
}

Discord:

{
  "channel": "discord",
  "config": {
    "botToken": "your-discord-bot-token"
  }
}

Slack:

{
  "channel": "slack",
  "config": {
    "botToken": "xoxb-...",
    "appToken": "xapp-..."
  }
}

Request Example

curl -X POST http://localhost:3000/api/channels/configure \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "config": {
      "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
    }
  }'

Response

{
  "success": true,
  "channel": "telegram",
  "configured": true
}

Validation

The endpoint validates:

The channel field must be one of: telegram, whatsapp, discord, slack
The config object must contain all required fields for the specified channel
Empty or missing config values are rejected with a 400 error

Invalid channel names return:

{
  "error": "Invalid channel. Must be one of: telegram, whatsapp, discord, slack",
  "code": "INVALID_CHANNEL",
  "status": 400
}

All configuration changes are logged to the Audit Trail for traceability.

Next Steps

Configuration -- Channel environment variables
Multi-Channel Setup -- Enable multiple channels simultaneously
Agent API -- Manage agents that use channels

Channel API

On this page