Communication Channels API

Channels connect external messaging platforms, email, and automation triggers to Kaman agents and workflows. Each channel type has a channel definition (registered at startup) and one or more channel instances (configured by users). When a message arrives on an external platform, the channel instance parses it, routes it downstream to an agent or workflow, and sends the response back through the same platform.

Base URLs

Channel operations use two route groups:

For self-hosted installations, prepend your instance URL: http://kaman.ai/api/agent/channels

Channel Definitions

Channel definitions are registered automatically at server startup from the implementation files. Each definition describes a channel type, its configuration schema, and setup instructions.

List All Channel Definitions

Returns all registered channel definitions.

curl -X GET "http://kaman.ai/api/agent/channels" \
  -H "Authorization: Bearer kam_your_api_key"

Response

[
  {
    "id": "slack",
    "name": "Slack Channel",
    "description": "Channel for sending and receiving messages via Slack Bot API and slash commands.",
    "configDefinition": "[{\"name\":\"botToken\",\"type\":\"string\",\"description\":\"...\",\"required\":true}, ...]",
    "type": "slack",
    "setupInstructions": {
      "webhookRequired": true,
      "webhookPath": "webhook",
      "title": "Slack App Webhook Setup",
      "steps": ["..."],
      "docsUrl": "https://api.slack.com/apis/connections/events-api"
    }
  }
]

Get Channel Definition by ID

curl -X GET "http://kaman.ai/api/agent/channels/slack" \
  -H "Authorization: Bearer kam_your_api_key"

Get Channel Status

Returns the status of connected channel microservices (WebSocket connections).

curl -X GET "http://kaman.ai/api/agent/channels/status" \
  -H "Authorization: Bearer kam_your_api_key"

Response

{
  "success": true,
  "connectedChannels": { ... },
  "timestamp": "2026-02-17T10:00:00.000Z"
}

Channel Instances

Channel instances are user-created configurations that bind a channel definition to a downstream agent or workflow.

List My Channel Instances

Returns all active channel instances for the authenticated user.

curl -X GET "http://kaman.ai/api/agent/channel-instances" \
  -H "Authorization: Bearer kam_your_api_key"

Response

[
  {
    "id": 1,
    "channelId": "slack",
    "channelName": "Sales Bot",
    "downStreamResourceId": "agent::42_0",
    "config": {
      "botToken": "xoxb-...",
      "signingSecret": "abc123..."
    },
    "userId": "user-123",
    "status": "active",
    "channelType": "Slack Channel",
    "channelTypeName": "slack"
  }
]

Get Channel Instance by ID

curl -X GET "http://kaman.ai/api/agent/channel-instances/1" \
  -H "Authorization: Bearer kam_your_api_key"

Create Channel Instance

Also available at POST /api/agent/channels (legacy route). Both routes accept the same payload.

Request Body

curl -X POST "http://kaman.ai/api/agent/channel-instances" \
  -H "Authorization: Bearer kam_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "telegram",
    "channelName": "Support Bot",
    "downStreamResourceId": "agent::5_0",
    "config": {
      "botToken": "123456:ABC-DEF..."
    }
  }'

Response (201 Created)

{
  "success": true,
  "message": "Channel instance created.",
  "instanceId": 7,
  "microserviceConnected": false,
  "operation": "created",
  "webhookRegistered": true,
  "webhookError": null
}

The webhookRegistered field is only present for Telegram channels, where the webhook is automatically registered with the Telegram Bot API on creation.

Uniqueness Constraint

The combination of userId + channelName + channelId must be unique among active instances. Attempting to create a duplicate returns 409 Conflict.

Update Channel Instance

Request Body

curl -X PUT "http://kaman.ai/api/agent/channel-instances/7" \
  -H "Authorization: Bearer kam_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "botToken": "123456:ABC-DEF...",
      "parseMode": "MarkdownV2"
    }
  }'

Response (200 OK)

{
  "success": true,
  "message": "Channel instance updated successfully.",
  "instanceId": 7,
  "microserviceConnected": false,
  "webhookRegistered": true
}

Ownership is enforced: only the user who created the instance can update it. Returns 403 Forbidden on mismatch.

Delete Channel Instance

Also available at DELETE /api/agent/channels/instance/:instanceId (legacy route).

curl -X DELETE "http://kaman.ai/api/agent/channel-instances/7" \
  -H "Authorization: Bearer kam_your_api_key"

Response (200 OK)

{
  "success": true,
  "message": "Channel instance deleted successfully.",
  "instanceId": "7"
}

Deletion permanently removes the instance from the database. For Telegram channels, the webhook is automatically deleted from the Telegram Bot API. For cron-based channels, all scheduled jobs are cleaned up.

Request WhatsApp Pairing Code

Only available for WhatsApp (Baileys) channel instances. Forces a new pairing code to be generated.

curl -X POST "http://kaman.ai/api/agent/channel-instances/12/request-pairing" \
  -H "Authorization: Bearer kam_your_api_key"

Response (200 OK)

{
  "success": true,
  "pairingCode": "A1B2C3D4",
  "message": "Your pairing code is: A1B2C3D4. Open WhatsApp > Settings > Linked Devices > Link with phone number, then enter this code."
}

If the code cannot be generated within 20 seconds, returns success: false with pairingCode: null.

Webhook Callback Endpoint

External platforms (Slack, Telegram, WhatsApp, etc.) send messages to this endpoint:

For example, the webhook URL for a Telegram instance with ID 7 is:

This endpoint does not require authentication -- it accepts raw webhook payloads from external platforms. Each channel implementation handles its own signature verification (e.g., Slack signing secret, Discord Ed25519, WhatsApp X-Hub-Signature-256).

Downstream Resource Routing

The downStreamResourceId field determines where incoming messages are routed:

Per-Channel Configuration Reference

Each channel type requires specific configuration fields when creating an instance. All channels also support two optional access control fields:

These fields are listed below per channel only where the channel explicitly supports them.

Slack

Channel ID: slack Type: Webhook (Events API + Slash Commands)

Configuration Fields

Webhook URL

Message Handling

• Responds to Slack URL verification challenges (type: "url_verification")
• Verifies X-Slack-Signature header using HMAC-SHA256 with the signing secret
• Handles slash commands via msg.command (returns ephemeral acknowledgment, sends full response async)
• Handles bot mentions and direct messages via Events API (msg.event.type === "message")
• Sends file artifacts using Slack's three-step upload flow (files.getUploadURLExternal, upload, files.completeUploadExternal)

Setup Steps

1. Go to https://api.slack.com/apps and select or create your app
2. Navigate to Event Subscriptions and enable Events
3. Paste the Webhook URL shown above
4. Subscribe to bot events: message.im, app_mention, message.channels
5. Optionally add slash commands under Slash Commands
6. Install/reinstall the app to your workspace

Microsoft Teams

Channel ID: teams Type: Webhook (Bot Framework + Incoming Webhook)

Configuration Fields

At least one of webhookUrl or appId+appPassword should be provided.

Webhook URL

Message Handling

• Handles Bot Framework message activities (text messages)
• Handles invoke activities for adaptive card actions (adaptiveCard/action)
• Dual response mode: sends via incoming webhook (MessageCard format) or via Bot Framework REST API with OAuth2 token
• Sends file artifacts as Hero Cards with download buttons (Bot Framework) or MessageCards with OpenUri actions (webhook)

Setup Steps

1. Go to Azure Portal and create a Bot Channels Registration
2. Copy the Microsoft App ID and create a client secret (App Password)
3. In Bot settings, add Microsoft Teams as a channel
4. Set the Messaging Endpoint to the Webhook URL above
5. In Teams Admin Center, approve the bot for your organization
6. Alternatively, for outgoing messages only, use an Incoming Webhook URL

Mattermost

Channel ID: mattermost Type: Webhook (Outgoing Webhook)

Configuration Fields

Webhook URL

Message Handling

• Verifies incoming webhook token against configured token
• Extracts user_id and text from the outgoing webhook payload
• Sends replies via response_url with Bearer token authorization
• Sends file artifacts by uploading via POST /api/v4/files then creating a post with the file attached

Setup Steps

1. Log in to your Mattermost instance as an admin
2. Go to Main Menu > Integrations > Outgoing Webhooks
3. Click Add Outgoing Webhook
4. Set a Title and Description
5. Choose the channel(s) to listen to, or use Trigger Words
6. Paste the Callback URL (Webhook URL) shown above
7. Click Save and copy the generated Token

Discord

Channel ID: discord Type: Webhook (Interactions Endpoint)

Configuration Fields

Webhook URL

Message Handling

• Responds to Discord PING interactions (type: 1) with PONG (type: 1)
• Verifies Ed25519 signatures using X-Signature-Ed25519 and X-Signature-Timestamp headers
• Handles slash commands (type: 2, APPLICATION_COMMAND) with deferred responses (type: 5)
• Handles message components (type: 3, buttons and selects)
• Handles regular bot mentions/DMs (removes mention tags from text)
• Splits messages exceeding Discord's 2000 character limit
• Sends file artifacts as multipart form uploads to Discord's REST API

Setup Steps

1. Go to https://discord.com/developers/applications and select your application
2. Navigate to General Information and copy the Application ID and Public Key
3. Go to Bot section and copy the Bot Token
4. Paste the Webhook URL into Interactions Endpoint URL and save
5. Discord will verify the endpoint automatically
6. Invite the bot to a server using the OAuth2 URL Generator

Telegram

Channel ID: telegram Type: Webhook (auto-registered)

Configuration Fields

Webhook URL

The webhook is automatically registered with the Telegram Bot API when you create or update the channel instance. No manual webhook setup is needed. The webhook is also re-registered on server startup and automatically deleted when the instance is deleted.

Message Handling

• Verifies X-Telegram-Bot-Api-Secret-Token header using a deterministic SHA-256 hash of the bot token
• Handles regular messages (msg.message)
• Handles edited messages (msg.edited_message)
• Handles callback queries (msg.callback_query) for inline keyboard buttons
• Responds to /start and /help commands with a greeting
• Splits messages exceeding Telegram's 4096 character limit
• Sends image artifacts via sendPhoto, all other file types via sendDocument

Setup Steps

1. Create a bot with @BotFather on Telegram and get your Bot Token
2. Paste the Bot Token in the config and save
3. The webhook is registered automatically -- no manual setup needed
4. Start chatting with your bot on Telegram

WhatsApp Business

Channel ID: whatsapp Type: Webhook (Meta Cloud API)

Configuration Fields

Webhook URL

Also accepts GET for Meta's webhook verification challenge (hub.mode, hub.challenge, hub.verify_token).

Message Handling

• Handles GET requests for Meta's webhook subscription verification
• Verifies X-Hub-Signature-256 header using HMAC-SHA256 with the app secret
• Parses the Meta webhook payload structure (entry[0].changes[0].value.messages[0])
• Extracts text from both text.body and interactive.button_reply.title
• Uses the sender's phone number as the session ID for conversation continuity
• Sends file artifacts by uploading media to WhatsApp Cloud API then sending a media message (image, video, audio, or document)

Setup Steps

1. Go to Meta for Developers (https://developers.facebook.com) and select your app
2. Navigate to WhatsApp > Configuration
3. Under Webhook, click Edit and paste the Webhook URL
4. Enter your Webhook Verify Token (must match the webhookVerifyToken config)
5. Click Verify and Save
6. Subscribe to the messages webhook field
7. Ensure your WhatsApp Business Account is linked

WhatsApp (Baileys)

Channel ID: baileys-whatsapp Type: Persistent WebSocket connection (pairing code auth)

Configuration Fields

This channel does not use webhooks. It maintains a persistent WebSocket connection to WhatsApp Web using the Baileys library.

Pairing Flow

1. Create the channel instance with your phone number
2. A pairing code is generated automatically and sent as a notification
3. On your phone, open WhatsApp > Settings > Linked Devices > Link a Device
4. Choose Link with phone number and enter the pairing code
5. Once paired, the channel connects automatically

To request a new pairing code at any time:

curl -X POST "http://kaman.ai/api/agent/channel-instances/{instanceId}/request-pairing" \
  -H "Authorization: Bearer kam_your_api_key"

Message Handling

• Receives all incoming messages via the Baileys WebSocket listener
• Filters by allowedNumbers if configured
• Supports text messages, image messages, document messages, video messages, and audio messages
• Downloads received media files and forwards them to the agent as file inputs
• Sends file artifacts natively via WhatsApp (image, video, audio, document)
• Auth state is persisted in S3 storage, surviving server restarts
• Automatically reconnects on connection drops (3-second backoff)
• On logout, clears auth state and requests a new pairing code

Instance Status

The config.waStatus field in the instance reflects the connection state:

Twilio SMS

Channel ID: twilio-sms Type: Webhook

Configuration Fields

Webhook URL

Message Handling

• Validates incoming AccountSid against configured account
• Extracts From, To, Body, and MessageSid from the Twilio form-urlencoded payload
• Returns a TwiML <Response><Message> acknowledgment
• Handles status callbacks (MessageStatus, SmsStatus)
• Splits outgoing messages at 1500 characters (Twilio handles concatenation)
• Sends image artifacts via MMS using MediaUrl; other file types as text with download link
• Uses Messaging Service SID when available, otherwise sends from the configured phone number

Setup Steps

1. Log in to Twilio Console (https://console.twilio.com)
2. Navigate to Phone Numbers > Manage > Active Numbers
3. Select the phone number to configure
4. Scroll to Messaging Configuration
5. Under A MESSAGE COMES IN, select Webhook and paste the URL
6. Set HTTP method to HTTP POST
7. Click Save configuration

Email (IMAP/SMTP)

Channel ID: email Type: Polling (IMAP) + SMTP for sending

Configuration Fields

This channel does not use webhooks. It polls for new emails using IMAP.

Message Handling

• Uses BullMQ with Redis for repeatable polling jobs
• Connects to IMAP and searches for UNSEEN emails in the INBOX
• Parses email content using mailparser
• Sends replies via SMTP with Re: prefix on the original subject
• Sends file artifacts as text messages with download links

Setup Steps

1. Enter your SMTP server details (host, port, secure)
2. Enter your IMAP server details (host, port, secure)
3. Provide email credentials (username and password)
4. For Gmail: use App Passwords (regular password will not work)
5. For Office 365: use your full email as username
6. Set the check interval in minutes

Gmail

Channel ID: gmail Type: Polling (Gmail API with OAuth2)

Configuration Fields

This channel does not use webhooks. It uses the Gmail History API for efficient polling.

Message Handling

• Uses OAuth2 with automatic token refresh via refresh token
• Initializes with users.messages.list to get the starting history ID
• Polls using users.history.list with historyTypes: ["messageAdded"] for efficient change detection
• Fetches full message content (format: "full") and parses headers and body
• Handles multipart messages (extracts text/plain parts)
• Sends replies using users.messages.send with base64url-encoded RFC 2822 messages
• Uses BullMQ for repeatable polling jobs

Setup Steps

1. Go to Google Cloud Console (https://console.cloud.google.com)
2. Create or select a project and enable the Gmail API
3. Go to Credentials and create an OAuth 2.0 Client ID
4. Set up consent screen and add Gmail scopes
5. Copy the Client ID and Client Secret
6. Complete the OAuth flow to obtain a Refresh Token

HTTP Webhook

Channel ID: http-webhook Type: Webhook (generic)

Configuration Fields

Webhook URL

Message Handling

• Verifies X-Webhook-Signature, X-Hub-Signature-256, or X-Signature headers using HMAC-SHA256 with the configured secret
• Extracts the message from the configured messageField path, or falls back to message, text, content, body, data.message, payload.text, or the full JSON body
• Extracts the session ID from the configured sessionIdField path, or falls back to sessionId, session_id, userId, user_id, id
• In async mode (default): returns immediately with status: "accepted" and sends the response to responseUrl or response_url from the payload, or the configured responseWebhookUrl
• In sync mode (syncResponse: true): blocks up to 30 seconds and returns the AI response inline
• Signs outgoing response payloads with X-Webhook-Signature if a secret is configured

Async Response Example

{
  "status": "accepted",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Webhook received, processing asynchronously"
}

Sync Response Example

{
  "status": "success",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "response": "The AI agent's response text..."
}

Setup Steps

1. Copy the Webhook URL
2. Configure your external service to send POST requests with JSON payloads
3. Include a message or text field (or configure a custom field path)
4. Optionally include sessionId for conversation continuity
5. For security, configure a webhook secret and send HMAC-SHA256 signatures in X-Webhook-Signature
6. Responses are sent to the responseUrl in the payload or the configured Response Webhook URL

Cron Scheduler

Channel ID: cron Type: Scheduled (BullMQ + Redis)

Configuration Fields

This channel does not use webhooks. It schedules jobs using BullMQ with Redis.

Cron Expression Examples

Message Handling

• Validates the cron expression format (5 fields, valid ranges)
• Creates a BullMQ repeatable job with the cron pattern and timezone
• On each trigger, sends the configured message to the downstream agent/workflow
• Supports manual triggering via the manual_trigger callback
• Supports oneShot mode: the instance self-destructs after a single execution
• Properly cleans up BullMQ jobs when the instance is updated or deleted

Google Workspace

Channel ID: google-workspace Type: Polling (Google Drive API with OAuth2)

Configuration Fields

This channel does not use external webhooks (though it optionally sets up Drive push notifications).

Message Handling

• Polls the specified Drive folder for files modified since the last check
• Filters by file extension if fileTypes is configured
• Sends file event details to the downstream agent: "File updated: filename.pdf at https://drive.google.com/..."
• Creates a response text document in the same Drive folder with the agent's output
• Optionally sets up a Drive files.watch webhook for push-based notifications
• Uses BullMQ for repeatable polling jobs

Setup Steps

1. Go to Google Cloud Console
2. Create or select a project and enable the Google Drive API
3. Create OAuth 2.0 Client ID credentials
4. Set up consent screen and add Drive scopes
5. Complete OAuth flow to obtain a Refresh Token
6. Enter the Folder ID of the Drive folder to monitor
7. Optionally filter by file types (e.g., pdf,docx)

Odoo Events

Channel ID: odoo-events Type: Polling (JSON-RPC API)

Configuration Fields

This channel does not use external webhooks. It polls Odoo via JSON-RPC.

Message Handling

• Authenticates with Odoo via POST /web/session/authenticate
• Polls each configured model using search_read with a write_date >= lastCheckTime filter
• Distinguishes between create and write events based on whether create_date > lastCheckTime
• Sends event details to the downstream agent: "Odoo create event in sale.order (ID: 42): {...}"
• Creates response notes in Odoo using mail.message (or note.note as fallback)
• Uses BullMQ for repeatable polling jobs

Setup Steps

1. Enter your Odoo instance URL
2. Provide database name and admin credentials
3. Specify which models to monitor (e.g., res.partner,sale.order)
4. Choose event types: create, write, unlink
5. Set the polling interval in minutes
6. Ensure API access is enabled for your Odoo user

Identity Verification

The verification system allows users to link their external identities (phone, Telegram, email, Slack, Discord, Mattermost) to their Kaman account. Once verified, channels with identifyUsers: true can resolve incoming messages to Kaman users for access control and billing attribution.

Get Available Verification Providers

No authentication required.

curl -X GET "http://kaman.ai/api/agent/verification/providers"

Response

{
  "success": true,
  "providers": {
    "telegram": true,
    "email": true,
    "slack": false,
    "discord": false,
    "mattermost": false
  }
}

Each provider is true only if the required environment variables are configured on the server.

Get My Verified Identities

curl -X GET "http://kaman.ai/api/agent/verification/identities" \
  -H "Authorization: Bearer kam_your_api_key"

Response

{
  "success": true,
  "identities": [
    { "field": "phone", "value": "+972501234567" },
    { "field": "telegram", "value": "123456789" },
    { "field": "whatsapp", "value": "972501234567" },
    { "field": "email", "value": "user@example.com" }
  ]
}

Known identity types: phone, telegram, whatsapp, email, slack, discord, mattermost, teams.

Telegram Verification

Verifies phone number and Telegram ID simultaneously using a Telegram bot.

Start Verification

curl -X POST "http://kaman.ai/api/agent/verification/start-telegram" \
  -H "Authorization: Bearer kam_your_api_key"

Response

{
  "success": true,
  "deepLink": "https://t.me/KamanVerify_bot?start=abc123...",
  "expiresInSeconds": 300,
  "message": "Open this link to verify your phone and Telegram identity: ..."
}

The user clicks the deep link, opens the verification bot, and shares their contact. The bot verifies the phone number and Telegram user ID, then stores three identities: phone, telegram, and whatsapp.

Verification Bot Webhook (internal)

This is called by Telegram when users interact with the verification bot. No manual configuration needed.

Callback (internal)

Called by the verification bot after the user shares their contact. Requires INTERNAL_SERVICE_KEY authorization.

Email Verification

Sends a 6-digit OTP to the user's email address.

Start Verification

curl -X POST "http://kaman.ai/api/agent/verification/start-email" \
  -H "Authorization: Bearer kam_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

Response

{
  "success": true,
  "expiresInSeconds": 600,
  "message": "Verification code sent to user@example.com"
}

Verify OTP

curl -X POST "http://kaman.ai/api/agent/verification/verify-email" \
  -H "Authorization: Bearer kam_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "otp": "123456" }'

Response

{
  "success": true,
  "message": "Email user@example.com verified successfully",
  "email": "user@example.com"
}

Slack Verification (OAuth)

Links a Slack user ID to the Kaman account via OAuth.

curl -X POST "http://kaman.ai/api/agent/verification/start-slack" \
  -H "Authorization: Bearer kam_your_api_key"

Response

{
  "success": true,
  "authUrl": "https://slack.com/oauth/v2/authorize?client_id=...&user_scope=identity.basic&..."
}

The user opens the authUrl in a browser, authorizes the app, and the callback at GET /api/agent/verification/callback/slack completes the verification.

Discord Verification (OAuth)

Returns an authUrl for Discord OAuth with identify scope. Callback at GET /api/agent/verification/callback/discord.

Mattermost Verification (OAuth)

Returns an authUrl for Mattermost OAuth. Callback at GET /api/agent/verification/callback/mattermost. Requires MATTERMOST_VERIFY_URL environment variable.

OAuth Callback (unified)

This endpoint handles the OAuth redirect. It validates the state parameter from Redis, exchanges the authorization code for user identity, and stores the verified identity. Returns an HTML page that sends a postMessage to the opener window and auto-closes.

Environment Variables

Channel System

Verification System

Database Tables

channels

Stores channel definitions (populated at startup).

channel_instances

Stores user-created channel instances.

Unique constraint on id. Soft uniqueness enforced by code on userId + channelName + channelId among active instances.

Tool Confirmation via Channels

When an agent encounters a tool that requires human approval, the channel presents a human-readable confirmation prompt:

The pending confirmation is stored in Redis with a 10-minute TTL. The user's next message is checked for confirmation keywords (yes/y/approve/ok/1 for approve, always/2 for session-wide approve, no/n/reject/cancel/3 for reject). If the user sends a non-confirmation message, the pending interrupt is cleared and the message is processed normally.