Managing integrations

Integrations connect your agent to external services and platforms. This guide covers how to find, add, configure, and manage integrations in your ADK project.

Finding integrations

Search the Botpress Integration Hub

Search for integrations by keyword:

adk search crm

List available integrations

Browse all available integrations from the Botpress Integration Hub:

adk list --available

View integration details

Get detailed information about a specific integration, including its actions, events, and channels:

adk info linear

You can also filter the output:

adk info linear --actions    # Show only actions
adk info linear --events     # Show only events
adk info linear --channels   # Show only channels

See the CLI reference for all available flags and options.

Adding integrations

Add an integration using the adk add command:

adk add linear

✓ Added linear version 2.1.2 as linear to agent.config.ts dependencies

Added as disabled. Enable and configure it in the Control Panel.

This adds the integration to your agent.config.ts as a string shorthand:

dependencies: {
  integrations: {
    chat: "chat@0.7.7",
    webchat: "webchat@0.3.0",
    linear: "linear@2.1.2",
  },
},

Newly added integrations are disabled by default. Enable and configure them in the Control Panel during adk dev.

Pinning a version

Add a specific version instead of the latest:

adk add notion@3.0.0

Using an alias

Add an integration with a custom alias. This is useful when you need multiple instances of the same integration:

adk add webhook --alias webhookOrders

The alias is how you reference the integration in your code:

import { actions } from "@botpress/runtime";

await actions.webhookOrders.send({ url: "https://api.example.com/orders", data: payload });

Avoid aliasing built-in channel integrations (webchat, chat, slack, teams, telegram, whatsapp). The runtime uses the alias to identify these integrations, and a custom alias will prevent default message components from loading.

Workspace-scoped integrations

Add a private or custom integration from your workspace:

adk add my-workspace/custom-integration@1.0.0

Configuring integrations

Integration settings (API keys, tokens, OAuth credentials) are managed in the Control Panel, not in agent.config.ts.

1. Run adk dev to start the development server
2. Open the Control Panel at http://localhost:3001/integrations
3. Find the integration and click to configure it
4. Enter the required settings and enable it

Each integration card in the Control Panel shows its current status:

Status	Meaning
Connected	Enabled, registered, and configured
Disabled	Turned off, can be enabled
Needs Action	Requires installation, configuration, or enabling
Failed	Registration error

Listing installed integrations

View integrations currently installed in your project. The Alias column shows the key you use to reference each integration in your code:

adk list

Installed Integrations (3)

Alias               Name                          Version
───────────────────────────────────────────────────────────────
chat                chat                          0.7.7
webchat             webchat                       0.3.0
linear              linear                        2.1.2

Updating integrations

Update a specific integration

adk upgrade linear

Update all integrations interactively

adk upgrade

This shows available updates and lets you choose which to upgrade:

✓ Upgraded:
  • linear (2.0.0 → 2.1.2)

Run adk dev to install the updated integrations

Removing integrations

Remove an integration from your project:

adk remove linear

✓ Removed linear from agent.config.ts dependencies
  Run adk dev to update your project

You can also run adk remove without a name to choose interactively.

Using integrations in code

Once an integration is installed and enabled, its actions become available in your agent:

import { actions } from "@botpress/runtime";

// Call an integration action
await actions.linear.createIssue({
  title: "Bug report from user",
  teamId: "TEAM-123",
});

You can subscribe to integration events in Triggers and Conversations (via the events prop).