Skip to content

Integrations — overview

Integrations are how agents reach outside the platform: receive chat messages, send notifications, read user data. Each integration type is a row in user_integrations, encrypted at rest, scoped per-profile via the scope model.

CategoryWhat it doesMembers
Notifications & chatAgents send messages out; users send messages in (when bidirectional).Slack, Telegram, Email, Webhook
Data sourcesAgents read your data.Mail (IMAP/SMTP), Calendar (CalDAV)

Bank data via Teller is no longer built in; it ships as the separate @vonzio/plugin-teller plugin.

The dashboard’s Settings → Integrations page groups them this way.

IntegrationPattern
SlackOAuth (server initiates, callback on /api/slack/callback)
MailIMAP/SMTP host + username + app password; verified before saving
CalendarCalDAV URL + username + app password; verified before saving
TelegramBotFather token + /link claim in DM, OR one-tap pair with the instance bot (if configured)
EmailResend API key entered by user; stored encrypted
WebhookURL entered by user; optional HMAC secret
  • Telegram — one row per bot (each independently bindable to a profile).

For all others, one integration per user.

When a playbook or agent sends a notification, it routes by the channel value:

ChannelFormat
Bare type (slack, email, webhook, telegram)Uses the user’s default integration of that type.
telegram:<integration_id>Specific Telegram bot. Required when using thread-claim.

Specify channel via notification_channels[] on a playbook, or as channel in mcp__notify__notify_user calls. See notify MCP.

Integration granted to profileAgent gets
Mailmcp__mail__* tools
Calendarmcp__calendar__* tools
Slack / TelegramInbound chat surfaces (user messages route to this profile via the bot).
Email / WebhookOutbound via notify_user only. No inbound surface.

DELETE /v1/integrations/:id removes the row + revokes downstream auth (Telegram webhook deleted, Slack token revoked where supported). OAuth refresh tokens that we hold are deleted; revoking them on the provider side requires the user to visit their Slack account settings.