Chat Integrations

SidClaw can send approval notifications directly to your team's chat platform. When an agent action requires approval, reviewers get a rich message with context and can approve or deny without leaving their chat app.

Supported Platforms

Slack

Option A: Interactive Buttons (Recommended)

Create a Slack app with a bot token for full interactive approve/deny buttons.

1. Create a Slack App

Go to api.slack.com/apps and create a new app.

2. Add Bot Scopes

Under OAuth & Permissions, add the chat:write bot scope.

3. Enable Interactivity

Under Interactivity & Shortcuts, enable interactivity and set the Request URL to:

https://api.sidclaw.com/api/v1/integrations/slack/actions

4. Install to Workspace

Install the app to your Slack workspace and copy the Bot User OAuth Token (xoxb-...).

5. Configure in SidClaw

In the SidClaw dashboard, go to Settings > Integrations > Slack and enter:

• Bot Token: The xoxb-... token from step 4
• Channel ID: The channel where notifications should be posted (e.g., C0123456789)
• Signing Secret: Found under Basic Information in your Slack app settings

Option B: Simple Webhook (No Buttons)

For notification-only mode (no interactive buttons), use a Slack incoming webhook:

1. In your Slack workspace, go to Apps > Incoming Webhooks
2. Add a new webhook and select a channel
3. Copy the webhook URL
4. In SidClaw, enter the Webhook URL under Slack settings

Webhook mode sends a text notification with a link to the dashboard. Reviewers click the link to approve or deny.

What the Message Looks Like

The Slack Block Kit message includes:

• Agent name and risk level
• The action being requested and target integration
• Data classification
• Why the action was flagged
• Approve and Deny buttons (with confirmation dialogs)
• View in Dashboard link

After a decision, the message updates to show who approved or denied and when.

Telegram

Telegram supports full interactive approve/deny via inline keyboard buttons.

1. Create a Bot

Message @BotFather on Telegram and create a new bot. Copy the bot token.

2. Add Bot to Group

Add your new bot to the Telegram group or channel where you want notifications.

3. Get Chat ID

Send a message in the group, then visit:

https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

Find the chat.id value (negative number for groups).

4. Configure in SidClaw

In the dashboard, go to Settings > Integrations > Telegram and enter:

• Bot Token: From step 1
• Chat ID: From step 3

The webhook is automatically registered with Telegram when you save.

What the Message Looks Like

The Telegram message includes:

• Agent name, action, classification, and risk level
• Why the action was flagged
• Approve and Deny inline buttons
• View in Dashboard link

After a decision, the buttons are removed and a reply shows the result.

API Reference

Get Integration Configuration

GET /api/v1/tenant/integrations

Returns current integration settings with tokens masked.

Update Integration Configuration

PATCH /api/v1/tenant/integrations
Content-Type: application/json

{
  "slack": {
    "enabled": true,
    "bot_token": "xoxb-...",
    "channel_id": "C0123456789",
    "signing_secret": "..."
  }
}

Send Test Notification

POST /api/v1/tenant/integrations/:provider/test

Sends a test notification to the specified provider (slack or telegram).

Security

• Slack callbacks are verified using the Slack signing secret (HMAC-SHA256). Replay protection rejects requests older than 5 minutes.
• Telegram callbacks are verified by looking up the approval to find the tenant and matching the bot token.
• Integration callback endpoints skip SidClaw authentication and instead use platform-specific verification.
• All tokens are stored encrypted in the tenant settings JSON field and masked when returned via the API.

Troubleshooting

Slack buttons not working? Ensure the Interactivity Request URL is set correctly and the bot has the chat:write scope.

Telegram buttons not responding? Check that the webhook is registered by visiting https://api.telegram.org/bot<TOKEN>/getWebhookInfo. Ensure the bot is in the group and has permission to post messages.

Test notification not arriving? Use the Test button in Settings > Integrations to send a test message and check for errors.