Channels API

Channel integrations connect ZERG to external messaging platforms: Slack, Microsoft Teams, Telegram, and generic webhooks.

Overview

Channels are gen_server-based integrations that receive messages from external platforms, relay them to a Luna agent for processing, and send responses back. Each channel type has a dedicated adapter that handles the platform-specific wire format and authentication.

Authentication

Channel management endpoints require Authorization: Bearer <token>. Webhook receivers use platform-specific signature verification.

Endpoints

List Channels

GET /api/v1/channels

Returns configured channels:

{
  "ok": true,
  "data": [
    {
      "id": "ch-slack-001",
      "type": "slack",
      "name": "general",
      "status": "active",
      "config": { "workspace": "acme.slack.com" }
    }
  ]
}

Create Channel

POST /api/v1/channels

Request Body (Slack):

{
  "type": "slack",
  "name": "support",
  "config": {
    "webhook_url": "https://hooks.slack.com/services/T00/B00/xxx",
    "signing_secret": "abc123"
  }
}

Request Body (Telegram):

{
  "type": "telegram",
  "name": "alerts",
  "config": {
    "bot_token": "123456:ABC-DEF",
    "chat_ids": ["-1001234567890"]
  }
}

Request Body (Teams):

{
  "type": "teams",
  "name": "dev-ops",
  "config": {
    "webhook_url": "https://outlook.office.com/webhook/...",
    "tenant_id": "tenant-uuid"
  }
}

Update Channel

PUT /api/v1/channels/:id

Update channel configuration and name.

Delete Channel

DELETE /api/v1/channels/:id

Remove a channel integration.

Webhook Receiver

POST /api/v1/channels/webhook/:token

Generic webhook receiver. Accepts arbitrary JSON payloads:

{
  "text": "What is the current deployment status?",
  "user": "deploy-bot",
  "metadata": { "source": "jenkins" }
}

Webhook Signature Verification:

Platform	Method	Header
Slack	HMAC-SHA256	X-Slack-Signature
Teams	JWT	Authorization
Telegram	—	IP allowlist

Error Codes:

Code	Description
400	Invalid channel configuration
401	Authentication or signature verification failed
404	Channel not found
422	Unsupported channel type

Examples:

curl http://127.0.0.1:11434/api/v1/channels \
  -H "Authorization: Bearer $TOKEN"

curl -X POST http://127.0.0.1:11434/api/v1/channels \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "slack", "name": "ops", "config": {"webhook_url": "https://hooks.slack.com/services/...", "signing_secret": "..."}}'