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.

Microsoft Teams

Teams supports rich Adaptive Card notifications. With a Bot Framework bot, reviewers can approve or deny directly from the card.

Option A: Incoming Webhook (Simple)

Create a webhook in your Teams channel for notification-only mode (link to dashboard for approval).

1. Open Workflows

Right-click your Teams channel > Workflows > search "webhook" > select "Send webhook alerts to a channel".

2. Configure and Save

Select your team and channel, then click Save. Copy the webhook URL.

3. Configure in SidClaw

In the dashboard, go to Settings > Integrations > Microsoft Teams and enter the Webhook URL. Enable and save.

Option B: Bot Framework (Interactive Buttons)

Register a Bot in Azure for full interactive Approve/Deny buttons directly in Teams.

1. Register a Bot

Go to dev.botframework.com/bots/new or use the Azure Portal to create a Bot registration. Copy the App ID and App Secret.

2. Set Messaging Endpoint

Set the bot's messaging endpoint to:

https://api.sidclaw.com/api/v1/integrations/teams/callback

3. Configure in SidClaw

In the dashboard, enter the Webhook URL, Bot App ID, and Bot App Secret under Microsoft Teams settings.

What the Message Looks Like

The Adaptive Card includes:

• Agent name and owner (who requested it)
• Human-readable action description
• Risk level and data classification (side by side)
• Policy rationale explaining why the action was flagged
• Timestamp, expiry, and approval ID
• Approve and Deny buttons (Bot Framework mode) or Review & Decide link (webhook mode)
• SidClaw branding footer

After a decision, the card updates in-place 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, teams, or telegram).

Security

• Slack callbacks are verified using the Slack signing secret (HMAC-SHA256). Replay protection rejects requests older than 5 minutes.
• Teams callbacks are verified via HMAC-SHA256 using the bot secret. 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.

Teams cards not appearing? Verify the webhook URL is correct. For Workflows webhooks, ensure the workflow is active in Power Automate. For Bot Framework, check the messaging endpoint matches your API URL.

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.