Connectors

Connectors bridge your agents to chat platforms. Messages sent to the bot on any platform are routed to the assigned agent, and responses are sent back.

Supported Platforms

Discord

1. Create a bot at Discord Developer Portal
2. Copy the Bot Token
3. In SwarmClaw, go to Connectors > New Connector
4. Select Discord, paste the token, and choose an agent
5. Add channel IDs the bot should respond in (comma-separated)
6. Enable and start the connector

The bot needs the MESSAGE_CONTENT intent enabled in the developer portal.

Slack

1. Create a Slack app at api.slack.com
2. Enable Socket Mode and generate an App-Level Token
3. Add Bot Token Scopes: chat:write, app_mentions:read
4. Install to your workspace and copy the Bot Token
5. In SwarmClaw, create a Slack connector with both tokens
6. The bot responds to mentions (@YourBot) in channels it's invited to

Telegram

1. Message @BotFather on Telegram
2. Create a new bot and copy the token
3. In SwarmClaw, create a Telegram connector with the token
4. The bot responds to all direct messages and group mentions

WhatsApp

1. In SwarmClaw, create a WhatsApp connector
2. A QR code appears in the connector sheet
3. Open WhatsApp on your phone > Linked Devices > Link a Device
4. Scan the QR code
5. The connector links to your WhatsApp account

Note: WhatsApp uses the Baileys library (unofficial). The QR code may need to be re-scanned periodically.

WhatsApp Message Formatting

Connector replies are normalized to WhatsApp-friendly plain text before send, so markdown-heavy model output does not leak raw ** / backticks / link syntax in chats.

Inbound Voice Notes

Inbound voice notes are auto-transcribed before they reach the agent when STT is configured.

• Preferred STT order: ElevenLabs first, then OpenAI fallback
• If neither key is configured, the connector inserts a clear "transcription unavailable" note instead of silent failure
• If transcription fails, the connector inserts a clear failure note for the agent/user thread

Outbound Voice Notes

When an agent sends a WhatsApp voice note through connector_message_tool, SwarmClaw uses your configured ElevenLabs voice if one is available.

• If the configured default voice is rejected by ElevenLabs as a paid-only/library voice, SwarmClaw automatically retries with the built-in fallback voice
• This keeps outbound WhatsApp voice-note delivery working even when an older saved default voice is no longer usable on the current ElevenLabs plan

Email

1. Configure IMAP/SMTP credentials in the connector settings
2. Set polling interval for inbound email checks
3. Assign an agent to handle inbound messages
4. The connector converts email threads to chat context for the agent

Connector Health Monitoring

The daemon automatically monitors running connectors for liveness:

• Each connector exposes an isAlive() check (socket/connection state)
• The daemon polls every 2 minutes and detects dead connectors
• Failed connectors are auto-restarted with exponential backoff (30s base, 15min max, up to 3 wake attempts)
• Health events are logged and trigger in-app notifications
• Persistent failures result in a warning notification without further restart attempts

Managing Connectors

Each connector shows its status: running, stopped, or error. Use the toggle to start/stop connectors. Error details are displayed when something goes wrong.

Running connectors also expose a lightweight presence indicator based on last inbound activity:

• Active — message seen in the last 5 minutes
• Xm ago — recent activity within the last 30 minutes
• Inactive — no recent inbound activity

Connector Doctor

Connector Doctor helps preview routing and policy problems before or after you save a connector.

• Existing connector diagnostics: GET /api/connectors/:id/doctor
• Existing connector preview with temporary overrides: POST /api/connectors/:id/doctor
• Draft connector preview before save: POST /api/connectors/doctor

The report highlights warning conditions such as:

• Connector not currently running
• Missing or risky routing policy
• Agent/chatroom assignment issues
• Sample inbound-message policy problems

CLI equivalents:

swarmclaw connectors doctor <connectorId>
swarmclaw connectors doctor-preview <connectorId> --data '{"sampleMsg":{"text":"hello"}}'
swarmclaw connectors doctor-draft --data '{"platform":"telegram","agentId":"<agentId>","config":{"token":"***"}}'

Task Follow-Ups Over Connectors

When connector task follow-ups are enabled, completion updates prefer the same connector/channel that initiated the task. If the task generated a sendable local artifact, that file can be attached to the outbound follow-up message.

Pairing & Safety Policy

Connectors can be configured with dmPolicy: allowlist to block unknown senders until approved.

• Unknown senders receive a pairing code response.
• Approved admins can manage codes using /pair commands.
• /pair approve <code> allows that sender for future messages.
• /pair list shows pending/approved entries.

This is useful when you expose connectors to shared channels and want strict sender control.